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
xxxxxxxxxx
https://iam-sync-tenantidp.soffidnet:2443/authorization?redirect_uri=http://localhost/return&client_id=tenant&nonce=123456789&scope=openid+test&response_type=codeResponse
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
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
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
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
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
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
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
Response
{
"stats":"Success"
}