Connecting an OpenID Connect service

Introduction

There are three basic OpenID flows, depending whether the service name must be authenticated using its client secret or not:

OpenID flow

Implicit flow

The Service Provider sends the user to the IdP.

The IdP authenticates the user.

The user returns control to the Service Provider along an OpenID token and an OAuth token.

Client credentials flow

The Service Provider sends the user to the IdP.

The IdP authenticates the user.

The user returns control to the Service Provider along an authorization code.

The Service Provider gets the OpenID token and OAuth token from the IdP by presenting the authorization code, and its client secret. This request is using a direct connection between them.

Password authentication flow

The Service Provider asks for a user name and password.

The Service Provider gets the OpenID token and OAuth token from the IdP by presenting the user's name and password, and optionally its client secret. This request is using a direct connection between them.

Examples

1. Authorization code flow

The client application creates a random String, named nonce, and sends to he user the following URL

Request

https://<identityprovider>/authorization?

redirect_uri=https://<serviceprovider>/response&

client_id=MYCLIENT&

nonce=12345679801234567890&

scope=openid&

response_type=code

Then, the user will be asked for a username and password, or any other means of authentication. After authenticating the user, the browser will be redirected to the URL configured in the service provider page, adding a one-time authorization code.

Request

https://iam-sync-tenantidp.soffidnet:2443/authorization?redirect_uri=http://localhost/return&client_id=tenant&nonce=123456789&scope=openid+test&response_type=code

Response

xxxxxxxxxx
 
https://iam-sync-tenantidp.soffidnet:2443/authorization?redirect_uri=http://localhost/return&client_id=tenant&nonce=123456789&scope=openid+test&response_type=code

~~Response~~

http://localhost/return?code=Uw6AP2okBDzlaF0%2FxVrxHEucLk3iWCFHGcVcb1xdO50cdyRU

Request

https://<serviceprovider>/response/?
code=XXXXXXXXXXXXXXX&
nonce=12345679801234567980

Once the service provider has received the one-time authorization code, it can connect to the identity provider to retrieve the oAuth token, as well as the OpenID token.

Request

POST https://<YOUR_SERVER>:2443/token

Accept: application/json

Authorization: Basic dGVzdDp0ZXN0

Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=XXXXXXXXXXXX

Parameters

Authorization: contains, coded in base 64, the client id and the client secret, as it would have been sent for a standard Basic authentication header. The identity provider will match these against the stored credentials.

grant_type: should be authorization_code.

code: should be the one-time authorization code received in the previous requested.

Response

{

"access_token":"8bDP2P...",

"refresh_token":"gjLmSW...",

"id_token":"eyJra.eyJ.LQ_XtHKr.RY3A4...",

"token_type":"Bearer",

"expires_in":11998

}

The id_token tag contains the OpenId token.

The access_token tag contains the oAuth token.

Before the number of seconds specified om expires_in are elapsed, the token can be renewed by invoking again the token endpoint changing the grant_type:

Request

POST https://<YOUR_SERVER>:2443/token

Accept: application/json
Authorization: Basic dGVzdDp0ZXN0
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=XXXXXXXXXXXX

Parameters

Authorization: contains, coded in base 64, the client id and the client secret, as it would have been sent for a standard Basic authentication header. The identity provider will match these against the stored credentials.

grant_type: should be refresh_token.

refresh_code: should be refresh code received in the previous requested.

Response

{

"access_token":"8bDP2P...",

"refresh_token":"gjLmSW...",

"id_token":"eyJra.eyJ.LQ_XtHKr.RY3A4...",

"token_type":"Bearer",

"expires_in":11998

}

2. User’s password + client credentials flow

The application asks the user for the user name and password. Then, it connects to the token endpoint to get an access token:

Request

POST https://<YOUR_SERVER>:2443/token

Accept: application/json
Authorization: Basic dGVzdDp0ZXN0
Content-Type: application/x-www-form-urlencoded

grant_type=password&
username=USER&
password=PASSWORD&XXXXXXXXXXXX

Parameters

Authorization: contains, coded in base 64, the client id and the client secret, as it would have been sent for a standard Basic authentication header. The identity provider will match these against the stored credentials

grant_type: should be password

username: must be the user name entered by the user.

password: must be the password entered by the user.

Response

{
"access_token":"8bDP2P...",
"refresh_token":"gjLmSW...",
"id_token":"eyJra.eyJ.LQ_XtHKr.RY3A4...",
"token_type":"Bearer",
"expires_in":11998
}

The id_token tag contains the openid token.

The access_token tag contains the oAuth token.

Before the number of seconds specified in expires_in are elapsed, the token can be renewed by invoking again the token endpoint:

Request

POST https://<YOUR_SERVER>:2443/token

Accept: application/json
Authorization: Basic dGVzdDp0ZXN0
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=XXXXXXXXXXXX

Parameters

Authorization: contains, coded in base 64, the client id and the client secret, as it would have been sent for a standard Basic authentication header. The identity provider will match these against the stored credentials

grant_type: should be refresh_token

refresh_code: should be refresh code received in the previous requested

Response

{
"access_token":"8bDP2P...",
"refresh_token":"gjLmSW...",
"id_token":"eyJra.eyJ.LQ_XtHKr.RY3A4...",
"token_type":"Bearer",
"expires_in":11998
}

3. Closing the session

The application wants to revoke the token and session cookie:

Request

POST https://<YOUR_SERVER>:2443/revoke
Accept: application/json
Content-type: application/x-www-form-urlencoded
Authorization: Basic dGVzdDp0ZXN0

token_type_hint=token=access_token
&token=99999999

Parameters

Authorization: contains the encoded client id and client secret.

token_type_hint: can have the following values:
- access_token
- refresh_token
- session_cookie

token: contains the authorization token, refresh_token or session_cookie value

4. Getting user attributes

All the user attributes can be extracted from the OpenID token. Anyway, it is possible to get them in a more readable format user the user-info endpoint.

Request

GET https://<YOUR_SERVER>:2443/user-info

Accept: application/json
Authorization: Bearer dGVzdDp0ZXN0

Parameters

Authorization: contains a valid access token.

Response

{

"sub": "admin",

"surname": "Admin",

"given_name": "Admin",

"member_of": [

"TestRole2@soffid",

"TestRole@soffid"

]

}

5. Getting a session cookie for the user

Sometimes, a mobile application has authenticated the user using the username & password grant, but wants to share this authenticated session with the underlying web browser. For such a case, the application can request a session cookie with this request:

Request

GET https://<YOUR_SERVER>:2443/session_cookie

Accept: application/json
Authorization: Bearer dGVzdDp0ZXN0

Parameters

Authorization: contains a valid access token.

Response

{ "stats":"Success" }

{

"stats":"Success"

}