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 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.

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. For the combination of these parameters, a signature should be defined on the Token Server, which is unique for this particular application and its configuration. To generate an application signature please see the application signature chapter. The signature will be verified via the OCRA protocol. As a timestamp is used within the OCRA protocol it is mandatory that the time on the device is equal to the time on the Token Server, independent of time zones. The maximum time offset is ten minutes. There are two common reasons why DCR would fail. First, the time on the device not being in sync and second the app version not properly configured in the Token Server. The SDK does not provide the app with an error other than a general DCR error.

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

OneginiSDK.getOneginiClient(this).getUserClient().registerUser(null, new String[]{ "read" }, new OneginiRegistrationHandler() {
    @Override
    public void onSuccess(final UserProfile userProfile, final CustomInfo customInfo) {
      // show user is registered and authenticated
    }

    @Override
    public void onError(final OneginiRegistrationError error) {
      // check error reason and handle it or explain it to the user
    }
  }
}

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

final Set<OneginiIdentityProvider> identityProviders = OneginiSDK.getOneginiClient(this).getUserClient().getIdentityProviders();

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

OneginiSDK.getOneginiClient(this).getUserClient().registerUser(identityProvider, new String[]{ "read" }, new OneginiRegistrationHandler() {
    @Override
    public void onSuccess(final UserProfile userProfile, final CustomInfo customInfo) {
      // show user is registered and authenticated
    }

    @Override
    public void onError(final OneginiRegistrationError error) {
      // check error reason and handle it or explain it to the user
    }
  }
}