SDK integration

Onegini IDP offers an SDK to integrate the OAuth 2.0 authorization code flow into your client. The SDK is available on GitHub.

Setup

The two steps of the login flow described above are also reflected in the SDK. The first thing you have to do is create an instance of the OneginiOauthSdk.

The constructor takes a few parameters:

  1. Client id: The client id you have configured for your application
  2. Client secret: The client secret you have configured for your application
  3. Target Url: This is the URL that Onegini IDP will redirect the user back to once he has authenticated. It is the Redirection URI given as parameter of step A and is used in step C to send the user back to your application (the client).

Set the correct endpoints for your environment by calling the setAuthorizeUrl and setTokenUrl methods.

Once you have created an instance of the OneginiOauthSdk object you have to initialize it by calling the initSdk() method.

Example

OauthSdk oauthSdk = new OneginiOauthSdk("clientId", "clientSecret", "https://example.com/onegini/callback");

// Optional Overrides
oauthSdk.setAuthorizeUrl("https://example.com/oauth/authorize");
oauthSdk.setTokenUrl("https://example.com/oauth/token");

oauthSdk.initSdk();

Implementation

The first method to call is the prepareAuthentication method. This method returns an AuthorizationLocation object which contains the authorizationUrl to which the end-user must be redirected for authentication (using an http-redirect). This is step A of the login flow.

The second parameter of the AuthorizationLocation object is the state. This state is used to prevent [CSRF][csrf] attacks. This value provided in this parameter must be stored in a http session or other storage object which is persistent over multiple http requests. This state must be validated when the user returns to your application after he has authenticated with Onegini IDP.

Now you have redirected the end-user to Onegini IDP so he can perform step B (authenticate). After successful authentication the end-user is redirected back to the Redirection URI which you configured when initialising the SDK. This is step C of the login flow. As part of this redirect two parameters are present:

  • code: The authorization grant
  • state: The state that was sent to Onegini IDP

Now the last step of the login flow has to be performed, exchanging the access grant for the access token, steps D and E. Invoke the getAccessToken method of the SDK to get the access token. This method takes two parameters:

  • Callback URI: The full callback URI including the query string (!)
  • State: The state that was sent to Onegini IDP. It must be retrieved from the session or other persistent storage object, do not extract it from the URI!

When the access token is successfully retrieved from Onegini IDP you also get the User profile with it. Below is an example of a successful access token response:

{"access_token": "BE2C02E5DD935C1F8747A5116EEE57AF638C1CC125FF32DED57AF24D2F3E6F67",
  "expires_in": 3599,
  "token_type": "Bearer",
  "profile": {
    "name": {
      "first_name": "John",
      "last_name": "Doe",
      "display_name": "John Doe"
    },
    "email_addresses": [
      {
        "primary": true,
        "value": "john.doe@example.com"
      }
    ],
    "phone_numbers": [
      {
        "primary": true,
        "tag": "MOBILE",
        "value": "+12125551234"
      }
    ],
    "reference_id": "12345",
    "preferred_locale": "en"
  }
}

Of course there is always the possibility that something goes wrong. A number of unchecked exceptions can be thrown:

  • AccessGrantMissingException: The authorization code is missing in the callback from step C
  • AccessTokenDecodingException: The access token has an illegal form and could not be deserialised
  • CouldNotRetrieveAccessTokenException: The access token could not be retrieved from Onegini IDP
  • StateMismatchException: The state that has been returned from Onegini IDP does not match the state that was stored in your application.