Custom authenticator

The Onegini SDK offers an API which enables you to integrate it with any custom authenticator. The SDK is able to authenticate the user using the data sent from the custom authenticator to the Extension Engine.

• Availability
• Register Custom Authenticator
• Authenticate using Custom Authenticator
• Deregister Custom Authenticator

Availability

Custom authentication is available only if all of the following requirements are met:

• Custom Authenticators feature must be enabled in the Token Server system configuration.
• The application configuration on the Token Server allows the use of custom authentication.
• Registration and Authentication scripts must be submitted to the Custom Authenticator configuration.

Register Custom Authenticator

Implementing authenticator registration is described within the Authenticator topic guide. However, in the case of Custom Authenticator there is one additional step to implement. During registration the SDK will call userClient:didReceiveCustomAuthFinishRegistrationChallenge: method on your delegate. This step is required in order to pass the authenticator data from your application to the Extension Engine.

The userClient:didReceiveCustomAuthFinishRegistrationChallenge: method has two parameters:

• userClient (ONGUserClient) user client performing registration.
• challenge (ONGCustomAuthFinishRegistrationChallenge) challenge used to complete the registration.

Challange object provides all information about the authenticator registration and the sender awaiting for the response:

• userProfile (ONGUserProfile) user profile for which registration request challenge was sent.
• authenticator (ONGAuthenticator) authenticator being registered.
• sender (id<ONGCustomAuthFinishRegistrationChallengeSender>) sender awaiting for response to the registration request challenge.

Using the sender object you will be able to respond to challenge with data or cancel it.

• respondWithData:challenge: - used to deliver the authenticator data to the SDK.
• cancelChallenge:underlyingError: - used for registration cancellation. Optionally, you can pass the underlying error containing the reason behind the cancellation. The underlying error will be included within the userInfo (under NSUnderlyingErrorKey) of cancellation error returned by the SDK in failure callback.

Example implementation:

- (void)userClient:(ONGUserClient *)userClient didReceiveCustomAuthFinishRegistrationChallenge:(ONGCustomAuthFinishRegistrationChallenge *)challenge
{
    // Continue authenticator registration with data
    [challenge.sender respondWithData:@"custom authenticator data" challenge:challenge];

    // Or cancel challenge
    [challenge.sender cancelChallenge:challenge underlyingError:nil];
}

Authenticate using Custom Authenticator

Authentication is described in the Authenticate User topic guide. However, when you use a custom authenticator for authentication, you will be prompted to authenticate with the custom authenticator instead of a PIN. The SDK will call the userClient:didReceiveCustomAuthFinishAuthenticationChallenge: method on your ONGAuthenticationDelegate. You will be able to choose how to respond to the challenge.

The userClient:didReceiveCustomAuthFinishAuthenticationChallenge: method has two parameters:

• userClient (ONGUserClient) user client performing registration.
• challenge (ONGCustomAuthFinishAuthenticationChallenge) challenge used to complete the authentication.

Challange object provides all information about the authentication and the sender awaiting for the response:

• userProfile (ONGUserProfile) user profile for which authentication request challenge was sent.
• authenticator (ONGAuthenticator) authenticator used for authentication.
• sender (id<ONGCustomAuthFinishAuthenticationChallengeSender>) sender awaiting for response to the authentication challenge.

Using the sender object you will be able to respond to challenge with data, fallback to PIN or cancel it.

• respondWithData:challenge: - used to deliver the authenticator data to the SDK.
• respondWithPinFallbackForChallenge: - used to complete the authentication with PIN instead of custom authenticator.
• cancelChallenge:underlyingError: - used for authentication cancellation. Optionally, you can pass the underlying error containing the reason behind the cancellation. The underlying error will be included within the userInfo (under NSUnderlyingErrorKey) of cancellation error returned by the SDK in failure callback.

- (void)userClient:(ONGUserClient *)userClient didReceiveCustomAuthFinishAuthenticationChallenge:(ONGCustomAuthFinishAuthenticationChallenge *)challenge
{
    // Continue authentication using custom authenticator
    [challenge.sender respondWithData:@"custom authenticator data" challenge:challenge];

    // Fallback to pin if needed
    [challenge.sender respondWithPinFallbackForChallenge:challenge];

    // Or cancel challenge
    [challenge.sender cancelChallenge:challenge underlyingError:nil];
}

In case of any issues encountered with custom authenticator Onegini SDK provides an option to fallback to PIN or cancel authentication. Calling the cancelChallenge method on the challenge will also result in cancelling the authentication process.

Deregister Custom Authenticator

Implementing authenticator deregistration is described in the Authenticator Deregistration topic guide. When using Custom Authenticator the SDK will send a challenge in order to receive the authenticator data needed to complete the deregistration.

Following method will be called by the SDK -[ONGAuthenticatorDeregistrationDelegate userClient:didReceiveCustomAuthDeregistrationChallenge:]:

• userClient (ONGUserClient) user client performing registration.
• challenge (ONGCustomAuthDeregistrationChallenge) challenge used to complete the authenticator deregistration.

Challange object provides all information about the authenticator deregistration and the sender awaiting for the response:

• userProfile (ONGUserProfile) user profile for which authentication request challenge was sent.
• authenticator (ONGAuthenticator) authenticator used for authentication.
• sender (id<ONGCustomAuthDeregistrationChallengeSender>) sender awaiting for response to the authentication challenge.

Using the sender object you will be able to respond to challenge with data or cancel it.

• respondWithData:challenge: - used to deliver the authenticator data to the SDK.

• cancelChallenge:underlyingError: - used for deregistration cancellation. Optionally, you can pass the underlying error containing the reason behind the cancellation. The underlying error will be included within the userInfo (under NSUnderlyingErrorKey) of cancellation error returned by the SDK in failure callback.

  - (void)userClient:(ONGUserClient *)userClient didReceiveCustomAuthDeregistrationChallenge:(ONGCustomAuthDeregistrationChallenge *)challenge
  {
      // Continue custom authenticator deregistration
      [challenge.sender respondWithData:@"custom authenticator data" challenge:challenge];
  
      // Or cancel challenge
      [challenge.sender cancelChallenge:challenge underlyingError:nil];
  }