User registration
This topic guide explains all the steps required to add user registration to your app. In case you didn't add the SDK to your application project yet, please follow the steps in the Setting up the project topic guide.
The SDK is accompanied by a separate Example App which provides a basic implementation and shows how to interact with the SDK. The SDK relies on the app to perform certain tasks which can not be performed by the SDK itself.
The Example App demonstrates the essential steps which must be performed by the App developer.
User registration is performed using the UserClient
. The instance can be obtained by using property userClient
of the Client
implementation object or by callingSharedClient.instance
method. Attempt to obtain UserClient
without SDK configuration the SDK first, will result in throwing NSInternalInconsistencyException
exception.
The SDK does not provide any UI components but leaves this up to the app. The result of every operation on the UserClient
is reported back to the App via
a delegate. Hence, the SDK does provides delegate interfaces that must be implemented by the app. All callbacks are performed on the main queue so the app
developer can invoke methods on UIKit components directly without having to deal with queue management.
These delegates are called once a specific action is required to be taken by the app or to give the result of a requested action back to the app.
Introduction
The SDK uses the OAuth 2.0 protocol to authenticate the device to access protected resources. To support this protocol the SDK acts as an OAuth 2.0 client.
Register user
User registration is one of the first things that you need to take care of. User registration essentially means connecting a user account to a mobile application installed on a device. It is possible to register multiple user accounts with the same application. If multiple users need to be registered the registration flow that is described below needs to be triggered once for every user. There is one restriction: you cannot register the same user multiple times. If you try to register the same user account twice you will essentially override the first registration for that user. Hence, it will not fail but it will reuse the profile that was already created for that user on the device.
The UserClient
offers a method to register a new user profile. The new user profile value object will be generated during the authentication process and
will be returned in the success callback.
This methods is called registerUser
and requires three arguments:
- identityProvider
IdentityProvider
a specific identity provider used for registration, if nil is provided the token server will pick a default identity provider - scopes array
[String]
the scopes authentication is requested for, when no scopes are requested the default scopes of the application will be used, - delegate
RegistrationDelegate
the delegate delegates control back to the app in case it needs to do something or in case of a successful or failed registration attempt. The delegate must implement the methods specified in theRegistrationDelegate
class.
The example below shows you how to call the registerUser
method and let the calling class also implement the required delegate:
Register stateless user
The SDK supports custom user registration without creating a profile. The Access Token created in the process has the Stateless
type and is not stored in the user's device. This makes it possible to implement support for App2App authentication towards external identity schemas that do not allow you to make derived identities (like DigiD) in a custom registration script. This means the app will be registered "just in time" each time a user selects the custom registration method.
To register stateless user a new public API method is introduced registerStatelessUser
:
- Mobile authentication enrolment is not possible.> - Implicit authentication is not possible.> - Changing PIN is not possible - as a user does not set any PIN during the registration process.> - Works only with Custom API Identity Provider.
Stateless authentication has to be enabled for mobile clients in the Access Admin, otherwise an error will be thrown while calling registerStatelessUser
To enable the feature, head to Configuration
→ Applications
in Access Admin. Once there, you can create a new application or edit an existing one. Either way, to enable stateless authentication, under User authentication
, enable Stateless authentication
.
Stateless authentication requires a configured Custom API Identity Provider.
Identity Providers
The platform supports two main types of Identity Providers: browser and custom API. Both types of Identity Providers can be defined and configured in the
Token Server configuration. All Identity Providers that are configured in the app are returned by the SDK as IdentityProvider
. If you would like to read
more about it please refer to Identity providers guide.
Depending on the identity provider type SDK starts the registration process accordingly. Please see Browser Identity Provider and Custom API Identity Provider there is described how handles specific registration challenge type.
Note: If you are using default identity provider you must know its type to handle appropriate methods from
RegistrationDelegate
The object passed as the delegate must conform to the RegistrationDelegate
protocol. The SDK will call the following methods on it:
userClientDidStartRegistration(_:)
- method called when user registration is started.userClient(_:didReceiveBrowserRegistrationChallenge:)
- method called when the registration action requires you to open a browser with the given URL.userClient(_:didReceiveCustomRegistrationInitChallenge:)
- method called when the initialization of two step custom registration requires a optional data to continue.userClient(_:didReceiveCustomRegistrationFinishChallenge:)
- method called when the second step of two step custom registration or one step custom registration requires a optional data to continue.userClient(_:didRegisterUser:identityProvider:info:)
- method called when registration action is completed with success.userClient(_:didFailToRegisterWith:error:)
- method called when registration action failed with error.userClient(_:didReceivePinRegistrationChallenge:)
- method called when registration action requires creation of a PIN to continue.
Choose a PIN
The next step in the registration process is letting the user select a PIN. This process is triggered by the SDK. It delegates control over to the app by
calling the userClient(_:didReceivePinRegistrationChallenge:)
method on the RegistrationDelegate
.
The userClient(_:didReceivePinRegistrationChallenge:)
method has two parameters:
- userClient (
UserClient
) user client performing registration. - challenge (
CreatePinChallenge
) create pin challenge used to complete registration.
Challenge object represents create PIN challenge. It provides all information about the challenge and the sender awaiting for the response:
- userProfile (
UserProfile
) user profile for which create PIN challenge was sent. - pinLength (
NSUInteger
) required length for a new PIN. - error (
Error
) error describing cause of failure of previous challenge response. Possible error domains: ONGPinValidationErrorDomain, ONGGenericErrorDomain. - sender (
CreatePinChallengeSender
) sender awaiting for response to the create PIN challenge.
Response to the create PIN challenge is sent using respondWithCreatedPinChallenge:challenge:
method of the challenge sender.
Example implementation of userClient(_:didReceivePinRegistrationChallenge:)
delegate method:
The respondWithCreatedPin:challenge:
method of the CreatePinChallengeSender
needs to be called in order to let the SDK process the provided PIN. The SDK
might trigger an error in case the chosen PIN is invalid. This could be because it is not compliant with PIN policy for example. The possible errors are
specified in the ONGPinValidationErrorDomain
.
Below follows an example implementation of challenge error handling:
The PIN must not be stored anywhere on the device as this creates a security issue since an attacker potentially could extract it from the device.
See the Pin handling recommendations for more information about handling the user PIN correctly.
After the user has successfully provided the PIN, the registration process is finished. One of the following methods on your implementation of the
RegistrationDelegate
will be called, depending on the outcome of the registration process.
A successful outcome of the user registration will result in a user profile object. This object is the connection between the user and the registered profile in the SDK. We recommend to ask the end-user to provide a human readable reference to this profile (e.g. a name). There is also an identity provider object returned for which the user registration succeeded. Additionally in case when custom API identity provider was used, SDK might return the custom info object which might contain more detailed information.
In order to initiate authentication this user profile object needs to be provided to the SDK, therefore it is recommended to let the user choose a name for his profile so he can easily remember which user account it is linked to.
A failure outcome of the user registration will result in an error and identity provider object for which an error occured.
Deregister user
User deregistration implies the removal of all access and refresh tokens from the device for this user account. The SDK will also send a request to the token server to revoke all tokens server side.
The deregisterUser:completion:
method requires two arguments:
- userProfile (
UserProfile
) the user profile that must be deregistered - completion
((Error?) -> Void)
the completion block that notifies caller about result of the deregistration action and error (if any). Possible error domains are ONGDeregistrationErrorDomain and ONGGenericErrorDomain.
The example below shows you how to call the deregisterUser:completion:
method: