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 Onegini SDK uses the OAuth 2.0 protocol to authorize the device to access protected resources. To support this protocol the SDK acts as an OAuth 2.0 client.
To initialize authentication the client credentials are required. These credentials are received via Dynamic Client Registration (DCR). As an app developer, there is no need to initialize DCR as it is part of the default implementations in the SDK. Errors that can occur during the DCR are reported back to the SDK via the specified handler. For DCR the app needs to identify itself to the Token Server. This is done by sending the identifier, version and platform of the app. Depending on the configured app integrity level it might be also necessary for the app to send it's signing key certificate. To obtain the certificate please see the application integrity chapter.
As a timestamp is used within the DCR protocol it is mandatory that the time on the device is equal to the time on the Token Server, independent
of time zones. In case of a wrong time the SDK will return
UserClient offers a method to register a new user profile. The new UserProfile value object will be generated during authentication process and will be
returned with success callback. This methods is called
registerUser and requires three arguments:
OneginiIdentityProviderthe Identity Provider that should be used for registration,
Stringthe scopes authentication is requested for, when no scopes are requested the default scopes of the application will be used,
OneginiRegistrationHandlerthe registration handler to return the authentication result to.
A list (
Set<UserProfile>) of registered user profiles can be checked by calling
UserClient#getUserProfiles(). When the app is being used for the first time
(and the list of profiles is empty), or when the user wants to create a new profile, then the
registerUser() method should be used. Calling the
UserClient#registerUser() for an already registered user will result in a reregistration.
The user registration starts with enrolling a user on a device using a selected Identity Provider (IdP). The list of all possible IdPs for an app is configured in the Token Server admin panel. The TS also configures a default (primary) IdP that is used for backward compatibility.
After the enrollment with the selected IdP, the SDK will receive a refresh token and initialize a PIN creation request to get the users PIN. The PIN is used to store the refresh token encrypted on the device. Depending on the setting chosen by the app developer the user should confirm the entered PIN or not. The PIN creation request handler can be specified by the app developer by setting it on the OneginiClientBuilder. The received access token will not be persisted and only stored in memory, so it will be gone the next time the app is started.
After successful pin creation the SDK will call the
onSuccess(UserProfile userProfile, final CustomInfo customInfo) method from the
OneginiRegistrationHandler. As a result of user registration, the user is registered and already authenticated. To learn more about user authentication please
read the user authentication chapter.
In case of a user registration failure the SDK will call the
onError(OneginiRegistrationError error) method with a specific error. This error will also be
called when the registration process is aborted. Please note that you can handle errors which are relevant to you differently. To accomplish this you should
OneginiRegistrationError#getErrorType() value with the
OneginiRegistrationError error type definitions. The
OneginiRegistrationError will also
contain an additional error description for debugging and possibly a
Throwable object which you can get with the
Example code - registration of a new user profile with default Identity Provider
1 2 3 4 5 6 7 8 9 10 11 12
Initializing registration with a selected Identity Provider¶
To register a user using a different IdP than the one set as default on the TokenServer you can provide an
as a parameter. The list(
Set<OneginiIdentityProvider>) of available IdPs can be checked by calling the
Example code - fetching set of possible IdentityProviders
The MSP platform supports two main types of Identity Providers: browser and custom API. Both types of IdPs can be defined and configured in the
Token Server configuration. All IdPs that are configured by the app are returned by the SDK as
OneginiIdentityProvider interface. You can
read more about it in the identity providers reference guide. When the selected
OneginiIdentityProvider is passed
to the registration method, the SDK will check it's type and start the registration process accordingly. Please see the
Browser Identity Provider and Custom API Identity Provider for details.
Example code - registration of a new user profile
1 2 3 4 5 6 7 8 9 10 11 12