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:
- Client id: The client id you have configured for your application
- Client secret: The client secret you have configured for your application
- 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": "[email protected]"
}
],
"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.