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


## Register an OpenId Connect Service Provider

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">1.</span> To register an OpenId Connect service provider, open the federation page:

`Main Menu > Administration > Configuration > Web SSO > Identity & Service providers`

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">2.</span> Then, select an Entity Group and the branch Service Providers and click on the **Add Service Provider** button.

[![image-1689235669464.png](https://bookstack.soffid.com/uploads/images/gallery/2023-07/scaled-1680-/image-1689235669464.png)](https://bookstack.soffid.com/uploads/images/gallery/2023-07/image-1689235669464.png)

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">3.</span> Soffid will display the following window:

[![image-1689236053673.png](https://bookstack.soffid.com/uploads/images/gallery/2023-07/scaled-1680-/image-1689236053673.png)](https://bookstack.soffid.com/uploads/images/gallery/2023-07/image-1689236053673.png)

<p class="callout info">For more information about the attributes, you can visit [the OpenID Connect detailed info](https://bookstack.soffid.com/link/392#bkmrk-openid-connect).</p>

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">4.</span> Finally, you must apply changes.

<div class="pointer-container" id="bkmrk-%C2%A0"><div class="pointer anim is-page-editable"><svg class="svg-icon" data-icon="link" role="presentation" viewbox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"></svg><div class="input-group inline block"> <button class="button outline icon" data-clipboard-target="#pointer-url" title="Copy Link" type="button"><svg class="svg-icon" data-icon="copy" role="presentation" viewbox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"></svg></button></div><svg class="svg-icon" data-icon="edit" role="presentation" viewbox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"></svg></div></div>## Examples

### 1. Authorization code flow

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

#### Request

<table border="0" id="bkmrk-https%3A%2F%2F%3Cidentitypro" style="width: 98.3951%; border-collapse: collapse; border-style: solid; border-color: #6983a7;"><tbody><tr><td style="width: 100%; border-color: #33bde0; border-style: solid;">http<span style="color: #000000;">s://[youridentityprovider:2443](https://soffid.bubu.lab:2443/token)/<span style="color: #ff0000;">**authorization**</span>?</span>

<span style="color: #000000;">**redirect\_uri**=https://&lt;serviceprovider&gt;/response&amp;</span>

<span style="color: #000000;">**client\_id**=MYCLIENT&amp;</span>

<span style="color: #000000;">**nonce**=1234567980123456</span>7890&amp;

**scope**=openid+test+other&amp;

**response\_type**=code

</td></tr></tbody></table>

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.

<div data-lang="western align-left" id="bkmrk-https%3A%2F%2Fiam-sync-ten"><textarea style="display: none;">https://iam-sync-tenantidp.soffidnet:2443/authorization?redirect\_uri=http://localhost/return&amp;client\_id=tenant&amp;nonce=123456789&amp;scope=openid+test&amp;response\_type=code</textarea></div><table border="0" id="bkmrk-https%3A%2F%2F%3Cserviceprov" style="width: 98.3951%; border-collapse: collapse; border-style: solid; border-color: #6983a7;"><tbody><tr><td style="width: 100%; border-style: solid; border-color: #33bde0;">https://&lt;serviceprovider&gt;/response/?  
code=XXXXXXXXXXXXXXX&amp;  
nonce=12345679801234567980

</td></tr></tbody></table>

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

<table border="0" id="bkmrk-post-https%3A%2F%2F%3Cyour_s" style="width: 98.3951%; border-collapse: collapse; border-style: solid; border-color: #6983a7;"><tbody><tr><td style="width: 100%; border-style: solid; border-color: #33bde0;"><span style="color: #000000;">**POST** [https://youridentityprovider:2443/<span style="color: #ff0000;">**token**</span>](https://soffid.bubu.lab:2443/token)</span>

*<span style="color: #000000;">HEADERS</span>*

<span style="color: #000000;">**Accept**: application/json</span>

<span style="color: #000000;">**Authorization**: Basic dGVzdDp0ZXN0</span>

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

*BODY PARAMS*

**grant\_type**=authorization\_code&amp;

**code**=XXXXXXXXXXXX

</td></tr></tbody></table>

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

<table border="0" id="bkmrk-%7B-%C2%A0-%C2%A0-%22access_token%22" style="width: 98.3951%; border-collapse: collapse; border-style: solid; border-color: #6983a7;"><tbody><tr><td style="width: 100%; border-style: solid; border-color: #33bde0;">{

 "access\_token":"8bDP2P...",

 "refresh\_token":"gjLmSW...",

 "id\_token":"eyJra.eyJ.LQ\_XtHKr.RY3A4...",

 "token\_type":"Bearer",

 "expires\_in":11998

}

</td></tr></tbody></table>

- 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

<table border="0" id="bkmrk-post-https%3A%2F%2F%3Cyour_s-0" style="width: 98.3951%; border-collapse: collapse; border-style: solid; border-color: #6983a7;"><tbody><tr><td style="width: 100%; border-style: solid; border-color: #33bde0;">**POS**<span style="color: #000000;">**T** [https://](https://soffid.bubu.lab:2443/token)[youridentityprovider:2443](https://soffid.bubu.lab:2443/token)[/<span style="color: #ff0000;">**token**</span>](https://soffid.bubu.lab:2443/token)</span>

<span style="color: #000000;">*HEADERS*</span>

<span style="color: #000000;">**Accept**: application/json</span>  
<span style="color: #000000;">**Authorization**: Basic dGVzdDp0ZXN0</span>  
<span style="color: #000000;">**Content-Type**: application/x-www-form-urlencoded</span>

*BODY PARAMS*

**grant\_type**=refresh\_token&amp;

**refresh\_token**=gjLmSW...

</td></tr></tbody></table>

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

<table border="0" id="bkmrk-%7B-%C2%A0-%C2%A0-%22access_token%22-0" style="width: 98.3951%; border-collapse: collapse; border-style: solid; border-color: #6983a7;"><tbody><tr><td style="width: 100%; border-style: solid; border-color: #33bde0;">{

 "access\_token":"8bDP2P...",

 "refresh\_token":"gjLmSW...",

 "id\_token":"eyJra.eyJ.LQ\_XtHKr.RY3A4...",

 "token\_type":"Bearer",

 "expires\_in":11998

}

</td></tr></tbody></table>

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

<table border="0" id="bkmrk-post-https%3A%2F%2F%3Cyour_s-1" style="width: 98.3951%; border-collapse: collapse; border-style: solid; border-color: #6983a7;"><tbody><tr><td style="width: 100%; border-style: solid; border-color: #33bde0;"><span style="color: #000000;">**POST** [https://](https://soffid.bubu.lab:2443/token)[youridentityprovider:2443](https://soffid.bubu.lab:2443/token)[/<span style="color: #ff0000;">**token**</span>](https://soffid.bubu.lab:2443/token)</span>

*<span style="color: #000000;">HEADERS</span>*

<span style="color: #000000;">**Accept**: application/json</span>  
<span style="color: #000000;">**Authorization**: Basic dGVzdDp0ZXN0</span>  
<span style="color: #000000;">**Content-Type**: application/x-www-form-urlencoded</span>

*BODY PARAMS*

<span style="color: #000000;">**grant\_type**=password&amp;</span>  
**username**=USER&amp;  
**password**=PASSWORD&amp;XXXXXXXXXXXX

</td></tr></tbody></table>

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

<table border="0" id="bkmrk-%7B-%C2%A0-%C2%A0-%22access_token%22-3" style="width: 98.3951%; border-collapse: collapse; border-style: solid; border-color: #6983a7;"><tbody><tr><td style="width: 100%; border-style: solid; border-color: #33bde0;">{  
 "access\_token":"8bDP2P...",  
 "refresh\_token":"gjLmSW...",  
 "id\_token":"eyJra.eyJ.LQ\_XtHKr.RY3A4...",  
 "token\_type":"Bearer",  
 "expires\_in":11998   
}

</td></tr></tbody></table>

- 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

<table border="0" id="bkmrk-post-https%3A%2F%2F%3Cyour_s-2" style="width: 98.3951%; border-collapse: collapse; border-style: solid; border-color: #6983a7; height: 146px;"><tbody><tr style="height: 146px;"><td style="width: 100%; border-style: solid; border-color: #33bde0; height: 146px;"><span style="color: #000000;">**POST** [https://](https://soffid.bubu.lab:2443/token)[youridentityprovider:2443](https://soffid.bubu.lab:2443/token)[/<span style="color: #ff0000;">**token**</span>](https://soffid.bubu.lab:2443/token)</span>

*<span style="color: #000000;">HEADERS</span>*

<span style="color: #000000;">**Accept**: application/json</span>  
<span style="color: #000000;">**Authorization**: Basic dGVzdDp0ZXN0</span>  
**Content-Type:** application/x-www-form-urlencoded

*BODY PARAMS*

**grant\_type**=refresh\_token&amp;

**refresh\_token**=gjLmSW...

</td></tr></tbody></table>

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

<table border="0" id="bkmrk-%7B%C2%A0-%C2%A0-%22access_token%22%3A" style="width: 98.3951%; border-collapse: collapse; border-style: solid; border-color: #6983a7; height: 146px;"><tbody><tr style="height: 146px;"><td style="width: 100%; border-style: solid; border-color: #33bde0; height: 146px;">{  
 "access\_token":"8bDP2P...",  
 "refresh\_token":"gjLmSW...",  
 "id\_token":"eyJra.eyJ.LQ\_XtHKr.RY3A4...",  
 "token\_type":"Bearer",  
 "expires\_in":11998   
}

</td></tr></tbody></table>

### 3. Closing the session

The application wants to revoke the token and session cookie:

#### Request

<table border="0" id="bkmrk-post-https%3A%2F%2F%3Cyour_s-3" style="width: 98.3951%; border-collapse: collapse; border-style: solid; border-color: #6983a7;"><tbody><tr><td style="width: 100%; border-style: solid; border-color: #33bde0;">**POST** h<span style="color: #000000;">ttps://[youridentityprovider:2443](https://soffid.bubu.lab:2443/token)</span>/<span style="color: #ff0000;">**revoke**</span>

*HEADERS*

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

*BODY PARAMS*

**token\_type\_hint**=token=access\_token&amp;

**token**=8bDP2P...

</td></tr></tbody></table>

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

<table border="0" id="bkmrk-get-https%3A%2F%2F%3Cyour_se" style="width: 98.3951%; border-collapse: collapse; border-style: solid; border-color: #6983a7; height: 79px;"><tbody><tr style="height: 79px;"><td style="width: 100%; border-style: solid; border-color: #33bde0; height: 79px;"><span style="color: #000000;">**GET** [https://](https://soffid.bubu.lab:2443/session_cookie)[youridentityprovider:2443](https://soffid.bubu.lab:2443/token)[/<span style="color: #ff0000;">**userinfo**</span>](https://soffid.bubu.lab:2443/session_cookie)</span>

*<span style="color: #000000;">HEADERS</span>*

<span style="color: #000000;">**Accept**: application/json</span>  
<span style="color: #000000;">**Authorization**: Bearer dGVzdDp0ZXN0</span>

</td></tr></tbody></table>

##### Parameters

- **Authorization**: contains a valid access token.

#### Response

<table border="0" id="bkmrk-%7B-%C2%A0-%C2%A0-%22sub%22%3A-%22admin%22" style="width: 98.3951%; border-collapse: collapse; border-style: solid; border-color: #6983a7;"><tbody><tr><td style="width: 100%; border-style: solid; border-color: #33bde0;">{

 "sub": "admin",

 "surname": "Admin",

 "given\_name": "Admin",

 "member\_of": \[

 "TestRole2@soffid",

 "TestRole@soffid"

 \]

}

</td></tr></tbody></table>

### 5. Getting a session cookie for the user

Sometimes, a mobile application has authenticated the user using the username &amp; 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

<table border="0" id="bkmrk-get-https%3A%2F%2F%3Cyour_se-0" style="width: 98.3951%; border-collapse: collapse; border-style: solid; border-color: #6983a7;"><tbody><tr><td style="width: 100%; border-style: solid; border-color: #33bde0;">**GET** <span style="color: #000000;">[https://](https://soffid.bubu.lab:2443/session_cookie)[youridentityprovider:2443](https://soffid.bubu.lab:2443/token)[/session\_cookie](https://soffid.bubu.lab:2443/session_cookie)</span>

*<span style="color: #000000;">HEADERS</span>*

<span style="color: #000000;">**Accept**: ap</span>plication/json  
**Authorization**: Bearer dGVzdDp0ZXN0

</td></tr></tbody></table>

##### Parameters

- **Authorization**: contains a valid access token.

#### Response

<table border="0" id="bkmrk-%7B-%C2%A0-%C2%A0-%22stats%22%3A%22succe" style="width: 98.3951%; border-collapse: collapse; border-style: solid; border-color: #6983a7;"><tbody><tr><td style="width: 100%; border-style: solid; border-color: #33bde0;">{

"cookie\_domain": "cookied",  
"user": "pgarcia",  
"cookie\_value": "5458083\_bT2CZlaa6psl/q3ue6NObxX8Q7duQKj0hAuUJIouT5Y=",  
"cookie\_name": "cookien"

}

</td></tr></tbody></table>

<p class="callout warning">Please note that it is mandatory to fill in the name of the cookie in the identity provider, at the session management section</p>