User registration
Introduction
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 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.
Prerequisites
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 its 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 INVALID_DATETIME
error.
In order for registration to work, OneginiBrowserRegistrationRequestHandler or OneginiCustomAuthenticationRequestHandler needs to be set
in OneginiClientBuilder
.
Initializing registration
The 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:
OneginiIdentityProvider
the Identity Provider that should be used for registration,String[]
the scopes authentication is requested for, when no scopes are requested the default scopes of the application will be used,OneginiRegistrationHandler
the 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
compare the 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 getMessage()
and getCause()
methods.
Example code - registration of a new user profile with default Identity Provider
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 OneginiIdentityProvider
instance
as a parameter. The list(Set<OneginiIdentityProvider>
) of available IdPs can be checked by calling the UserClient#getIdentityProviders()
method.
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 its type and start the registration process accordingly. Please see the Registration with browser IDP and Registration with custom IDP for details.
Example code - registration of a new user profile
Finalizing registration
Within registration flow, SDK call OneginiCreatePinRequestHandler#startPinCreation
in order to create PIN password. For more info check authenticate user with PIN page. Once the whole process (registration and PIN creation) is finished, OneginiRegistrationHandler#onSuccess
is called.