# Connecting Service Providers



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

# Connecting a SAML service

## Introduction

To connect a SAML service provider, the service provider must offer you its SAML metadata. The SAML metadata contains inform<span style="color: #000000;">ation about its public id, the</span> services that implement and the service endpoints.

## Register a SAML service provider

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">1.</span> Open the **Identity &amp; Service Provider** page.

`<span class="link" id="bkmrk-main-menu">Main Menu</span><span id="bkmrk-%C2%A0%3E%C2%A0"> > </span><span class="link" id="bkmrk-administration">Administration</span><span id="bkmrk-%C2%A0%3E%C2%A0-0"> > </span><span class="link" id="bkmrk-configure-soffid">Configure Soffid</span><span id="bkmrk-%C2%A0%3E%C2%A0-1"> > </span><span class="link" id="bkmrk-web-sso">Web SSO</span><span id="bkmrk-%C2%A0%3E%C2%A0-2"> > </span><span id="bkmrk-identity-%26-service-p">Identity & Service providers</span>`

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">2.</span> To add a new service provider, click on the **Add Service Provider** button.

<p class="callout info">Be in mind that you can configure more than one Entity Group and you could add new service providers in each one.</p>

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">3.</span> Then you must fill in the required fields. Also, you need to provide the identity provider metadata. You can either copy it from the Soffid federation page or instruct the service provider to download the federation metadata by itself.

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

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

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">4. </span>To publish the federation members metadata, the main sync server exports the members metadata at the path /SAML/metadata.xml. Thus, if your sync server is listening at soffid1.your.domain, you can get the whole federation metadata document from https://soffid1.your.domain:760/SAML/metadata.xml.

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">5. </span>After some seconds, up to five minutes, every federation member will notice any change.

# Connecting Soffid console

## Introduction

Soffid console has a built-in SAML client, so it can act as a service provider in the Soffid federation. It is interesting to use this configuration, as it allows you to enforce the use of two factors authentication to log into the Soffid console.

### Register Soffid as a service provider

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">1.</span> Enable the SAML protocol in the Soffid console:

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">1.1.</span> Open the **Authentication** page:

`Main Menu > Administration > Configure Soffid > Security settings > Authentication`

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">1.2.</span> You must enable the **External XAML identity provider**.

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">1.3.</span> Then you must fill in the fields:

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

- **Soffid server host name**: URL of the Soffid console.
- **SAML federation metadata URL**: URL where the whole federation metadata can be obtained. It used to be [https://your.primary.sync.server:760/SAML/metadata.xml ](https://your.primary.sync.server:760/SAM/metadata.xml)Sometimes, an error as "unable to find valid certification path to requested target" could be displayed.

In that case, you must obtain the public certificate from the sync server and store in your Java trusted certs repository. To do that, use the keytool command. The trusted certs repository is located at &lt;JAVA\_HOME&gt;/lib/security/cacerts

The command should look like the next one. When prompted for a password type in "changeit"

<table border="0" id="bkmrk-post-https%3A%2F%2Ftargeta" 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;">root@myserver:~$ /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/keytool   
-import -file /tmp/RootCA -trustcacerts -alias syncserver  
-keystore /usr/lib/jvm/java-8-openjdk-amd64/jre/lib/security/cacerts

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

- **Cache limit (seconds)**: the amount of time the metadata should be kept in memory before refreshing.
- **Identity provider**: after reading the federation metadata, this drop-down box lets you select any identity provider present at the federation. Usually, you will select the Soffid IdP.

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">2.</span><span style="background-color: #ffffff;"> Download Soffid console metadata: </span>

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">2.1.</span> Open the **Authentication** page:

`Main Menu > Administration > Configure Soffid > Security settings > Authentication`

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">2.1. </span><span style="background-color: #ffffff;">Click the **Download metadata** button and save the file.</span>

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

This XML file is the metadata descriptor for the console, including a self-signed certificate generated to sign SAML requests.

The XML file will be like the next one:

![](https://bookstack.soffid.com/uploads/images/gallery/2021-09/embedded-image-qh53z6p1.png)

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">3.</span> Register Soffid Metadata in the third-party Identity Provider.

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">4.</span> You can use the Wizard to Add Applications

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

<p class="callout info">For more information, visit [the Add Applications page.](https://bookstack.soffid.com/books/configuration-wizard/page/add-applications-qO4)</p>

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">5.</span> Test it

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">5.1.</span> Next time you log into the Soffid console, a new button will appear for **External (XAML) login**

[![image-1640009166065.png](https://bookstack.soffid.com/uploads/images/gallery/2021-12/scaled-1680-/image-1640009166065.png)](https://bookstack.soffid.com/uploads/images/gallery/2021-12/image-1640009166065.png)

**<span style="color: #a6d100; font-weight: bold; font-size: 18px;">5.2.</span>** Click on the External (SAML) login button, and the user will be forwarded to the identity provider.

![](https://bookstack.soffid.com/uploads/images/gallery/2021-09/embedded-image-zhqz8evp.png)

# Connecting your custom applications

## Introduction

SAML 2.0 is a complex and not easy to implement standard. There are some libraries that can help somewhat, but a correct implementation needs a deep knowledge of SAML protocol, and is always hard to test and debug.

To make it easier, Soffid provides some JSON rest web services, that can help any application to correctly implement the SAML service provider part of the protocol.

## Data flow

The following diagram, shows the resulting data flow between the end user, your application, the identity provider and Soffid web services:

<div drawio-diagram="478"><img src="https://bookstack.soffid.com/uploads/images/drawio/2021-10/drawing-5-1633684556.png" alt=""/></div>

### Data flow steps

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">1.</span> The end-user requests access to a protected page

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">2.</span> The custom application can check the user identity looking up a session variable. By the time being, the user is not authenticated.

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">3.</span> The custom application issues a JSON request to Soffid web service. In turn, Soffid web service builds, signs and maybe encrypts a SAML request

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">4.</span> Then custom application taks the JSON request and builds an HTTP Redirect response with the received data.

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">5.</span> The identity provider identifies the user as usual.

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">6.</span> The custom application receives the SAML response. At this point, the application packs and forwards the received data to Soffid Web Service.

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">7.</span> Soffid Web Service decrypts and checks SAML response integrity and correctnes, and returns a JSON document specifying the success or failure status, and the underlying identity attributes. If needed, Soffid web service can provision a new identity in target systems on the fly.

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">8.</span> The custom application gets the identity data, stores it in a session variable and provides the protected resource to the end user.

In order to get it, will be necessary:

1. Declare the custom application as an internal service provider in the federation page.
2. Create a Soffid application account for the custom application.
3. Implement the protection filters.
4. Implement the endpoint where the SAML response must be sent.

## Example

### 1. Creating an internal service provider

You can create an internal service provider as a SAML service provider.

### 2. SAML Request generator

After deploying Soffid SAML addon, a web service to generate SAML request will be automatically deployed. This web service requires an account with the **federation:serviceProvider** authorization.

The endpoint will be locate in Soffid Console:

[http://your.soffid.console:8080/webservice/federation/rest/generate-saml-request](http://your.soffid.console:8080/webservice/federation/rest/generate-saml-request)

Method:

```POST`

Headers to include in the request:

`Accept = “application/json”`  
`Content-Type = “application/json”`

Request: Send a JSON decument with following fields:

`user → suggested user to authenticate (optional)`  
`identityProvider → identity provider public ID. Must match the public ID of any`  
`identity provider registered in Soffid federation.`  
`serviceProviderName → service provider which requests the user`  
`authentication. Must match the public ID of an internal service provider`  
`sessionSeconds → max time for the user session inactivity`

Response:

`method → Method to use: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST`  
`instructs the application to build a HTML Form that automatically submits the`  
`following parameters. Value urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect`  
`instructs the application to perform a redirect (Location HTTP header) with the`  
`URL and parameters specified`  
`parameters → every parameter included must be submited to the identity`  
`provider. Usually, these two will be present:`  
`RelayState → identifier of the ticket of the SAML request`  
`SAMLRequest → encoded SAML request`  
`url → identity provider endpoint.`

Request sample:

<table border="0" id="bkmrk-%5B%C2%A0-%C2%A0-%C2%A0%7B%C2%A0-%C2%A0-%C2%A0-%C2%A0-%C2%A0%22pat" 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;">{

 "user" : "myuser@soffid.poc",  
 "identityProvider" : "my-service-provider",  
 "serviceProviderName" : "https://idp.soffid.com",  
 "sessionSeconds" : "3600"

}

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

Response sample:

<table border="0" id="bkmrk-%7B%C2%A0-%C2%A0-%22method%22%3A-%22urn%3A" 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;">{  
 "method": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",  
 "parameters": {  
 "RelayState":  
 "\_457cab260c4948ef4c6d35a67cac000d3348d1ec48f53215",  
 SAMLRequest":  
 “PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48c2FtbDJ..."  
 },  
 "url": "https://idp.soffid.com/SAML/Redirect"  
}

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

### 3.

In turn, your application will issue the following location header to the browser

<table border="0" id="bkmrk-location%3A-https%3A%2F%2Fid" 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;">Location: https://idp.soffid.com/SAML/Redirect?RelayState=\_457cab260c4948ef4c6d35a67cac000d3348d1ec48f53215&amp;SAMLRequest=PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48c2FtbDJ...

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

Should the method be urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST, your application should build an HTML similar the following one:

<table border="0" id="bkmrk-%3Cform-action%3D%22https%3A" 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;">&lt;form action="https://idp.soffid.com/SAML/Redirect"&gt;  
 &lt;input type="hidden" name="RelayState" value="457cab260c4948ef4c6d35a67cac000d3348d1ec48f53215" /&gt;  
 &lt;input type="hidden" name="SAMLRequest" value="PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48c2FtbDJ....."  
/&gt;  
&lt;/form&gt;  
&lt;script&gt;  
 document.form\[0\].submit();  
&lt;/script&gt;

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

### 4. SAML Response endpoints

Your application must implement the SAML response endpoint. This endpoint must accept the POST method and forward each received parameter to Soffid's parse-saml-response. Mind that your endpoint must accept application/x-www-form-urlencoded parametern while Soffid service accepts application/json.

Soffid endpoint will be located in Soffid Console:

`http://your.soffid.console:8080/webservice/federation/rest/generate-saml-request`

Method:

`POST`

Headers:

`Accept = “application/json”`  
`Content-Type = “application/json”`

Authentication:

Use your application account to login using basic authentication schema. In multitenant environments, the user name will have the forma TENANT\_NAME\\ACCOUNT\_NAME

Request: send a JSON document with following fields

`autoProvision → [false|true] Set to true if you want Soffid to automatically enroll`  
`unknown identities. This is not normally needed if you are using Soffid IdP, but it's`  
`useful when using third party IdPs.`  
`response: JSON object with any parameter received in post method.`  
`RelayState → identifier of the ticket of the SAML response`  
`SAMLResponse → encoded SAML response`  
`protocol → use always “urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST”`  
`serviceProviderName → service provider which requests the user authentication`

Response:

`authentication → [yes|no]`  
`failureMessage → if authentication=”no”, a message with the error cause.`  
`principalName → account name, as sent by the IdP`  
`user → Soffid identity with standard attributes`  
`attributes → Soffid identity custom attributes`  
`sessionId → session identifier`

##### Example data received by your endpoint

<table border="0" id="bkmrk-post-%2Fsaml-receiverh" 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 /saml-receiver  
Host: my-service-provider  
Content-Type: application/x-www-form-urlencoded  
RelayState=\_523866242f943b4c63234dc8942ffc2f08cea03aa129a4e2&amp;SAMLResponse=PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48c2FtbDJ.…

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

##### Example request

<table border="0" id="bkmrk-%7B%C2%A0-%C2%A0-%22autoprovision%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;">{  
 "autoProvision" : false,  
 "response" : {  
 "RelayState":  
 "\_523866242f943b4c63234dc8942ffc2f08cea03aa129a4e2",  
 "SAMLResponse":  
 "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48c2FtbDJ...."  
 },  
 "protocol" : "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",  
 "serviceProviderName" : "my-service-provider"  
}

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

##### Example response

<table border="0" id="bkmrk-%7B%C2%A0-%C2%A0-%22authentication" 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;">{  
 "authentication": "yes",  
 "principalName": "your-name@somedomain.com",  
 "user": {  
 "id": 123456,  
 "userName": "your-id",  
 "firstName": "Your",  
 "lastName": "Name",  
 "primaryGroup": "enterprise",  
 "active": true,  
 "shortName": "your-name",  
 "mailDomain": "somedomain.com"  
 },  
 "attributes": {  
 "employeeId": "AS14567"  
 },  
 "sessionId": "ABCTASHO54684A"  
}

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

# Openid-connect to SAML interoperability

## Introduction

**OpenID-Connect** has a clear design suitable for both frontend and backend.

**SAML** has a clear design for the frontend, but the backend usage is harder as the security in SAML cannot be placed at transport layer. Instead, in must be placed at document level. Additionally, it requires intensive use of cryptographic algorithms for signature and encryption.

That’s why some applications put a SAML frontend protection for both the frontend and relay on the session cookies generated by the fronted for backend access.

The problem arises when one service provider needs to invoke some services from a SAML enabled application that does not support or implement WS-Security.

To solve it, **Soffid Identity Provide**r provides a service to get the session cookies required to access to a SAML application.

## Data flow

The rest service **/userinfo/impersonate?url=….** will do the job, and will return the cookies to use to act upon the target application impersonating the current user.

<div drawio-diagram="487"><img src="https://bookstack.soffid.com/uploads/images/drawio/2021-10/drawing-5-1634292052.png" alt=""/></div>

#### 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;">POST [https://&lt;YOUR\_SERVER&gt;:2443/](https://soffid.bubu.lab:2443/token)userinfo/impersonate?url=http://targetapplication/  
Accept: application/json  
Content-type: application/x-www-form-urlencoded  
Authorization: Basic dGVzdDp0ZXN0

\[  
 {  
 "path":"/",  
 "domain":"samltest.id",  
 "name":"\_shibsession\_64656661756c7468747470733a2f2f73616d6c746573742e69642f73616d6c2f7370",  
 "value":"\_fa49874951dd05c18a0f68642c0736e9"  
 },  
 {  
 "path":"/",  
 "domain":"samltest.id",  
 "name":"\_opensaml\_req\_ss%3Amem%3A88b0af3e1ff47c911257490bc1a5749dfda1670948a563cec2fdf9e8a799f2c4",  
 "value":""

 }  
\]

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

##### Parameters

- **URL**: is the access URL for the target application.
- **Authorization**: contains the oauth token.

#### Response

The response contains the list of cookies to send to the target application.

<table border="0" id="bkmrk-%5B%C2%A0-%C2%A0-%C2%A0%7B%C2%A0-%C2%A0-%C2%A0-%C2%A0-%C2%A0%22pat" 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;">\[  
 {  
 "path":"/",  
 "domain":"samltest.id",  
 "name":"\_shibsession\_64656661756c7468747470733a2f2f73616d6c746573742e69642f73616d6c2f7370",  
 "value":"\_fa49874951dd05c18a0f68642c0736e9"  
 },  
 {  
 "path":"/",  
 "domain":"samltest.id",  
 "name":"\_opensaml\_req\_ss%3Amem%3A88b0af3e1ff47c911257490bc1a5749dfda1670948a563cec2fdf9e8a799f2c4",  
 "value":""

 }  
\]

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

#### Request

Once the application has got the list of cookies, it can invoke the target application URL

<table border="0" id="bkmrk-post-https%3A%2F%2Ftargeta" 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 [https://targetapplication/api/service1](https://targetapplication/api/service1)  
Accept: application/json  
Content-type: application/json  
Cookie: cookie1=value1

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

<p class="callout info">As security measures, the impersonation profile must be enabled, and the source application must be entitled to use it against the target application</p>

# Openid-connect Dynamic Register

## Introduction

Openid-connect allows a service provider registers dynamically other service providers.

## Dynamic Register

To dynamically register a client, acquire an initial access token, and then register the new application by using the registration API. You can get the access token from Soffid.

#### Register Server

##### Request

```shell
POST https://<YOUR_SERVER>:2443/register
```

**Authorization**

- **Authorization**: contains the Bearer Token.

**Header**

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

**JSON**

```shell
{
    "application_type": "web",
    "redirect_uris":
        ["https://client.example.org/callback",
         "https://client.example.org/callback2"],
    "client_name": "My Example 7",
    "logo_uri": "https://client.example.org/logo.png",
    "subject_type": "pairwise",
    "token_endpoint_auth_method": "client_secret_basic",
    "jwks_uri": "https://client.example.org/my_public_keys.jwks",
    "userinfo_encrypted_response_alg": "RSA1_5",
    "userinfo_encrypted_response_enc": "A128CBC-HS256",
    "contacts": ["ve7jtb@example.org", "mary@example.org"],
    "request_uris":
        ["https://client.example.org/rf.txt#qpXaRLh_n93TTR9F252ValdatUQvQiJi5BDub2BeznA"]
}
```

##### Response 200 OK

```shell
{
    "client_secret_expires_at": 0,
    "registration_client_uri": "https://iam-sync-tenantidp.soffidnet:2443/register?client_id=DR_7",
    "client_secret": "wBeH8G6hT2GRwr7jJ6HfX2lMJDGdwGi9M49SKF2MjHRGOtwZ",
    "redirect_uris": [
        "https://client.example.org/callback",
        "https://client.example.org/callback2"
    ],
    "registration_access_token": "NjYxODg1Ng.AFa8jQbltq+bocWQpT3okPvHXHrTM+HqXQC26Kz5mfAWfXWG",
    "client_name": "My Example 7",
    "client_id": "DR_7"
}
```

#### Client read request

##### Request

```shell
GET https://<YOUR_SERVER>:2443/register?client_id=DR_7
```

**Authorization**

- **Authorization**: contains the Bearer Token. It contains the registration\_access\_token Token received as the response when the server was registered.

**Header**

- **Content-type**: application/json

**Params**

- **client\_id**

##### Response

```shell
{
    "client_secret_expires_at": 0,
    "registration_client_uri": "https://iam-sync-tenantidp.soffidnet:2443/register?client_id=DR_7",
    "redirect_uris": [
        "https://client.example.org/callback",
        "https://client.example.org/callback2"
    ],
    "client_name": "My Example 7",
    "client_id": "DR_7"
}
```

####   

# Connecting CAS client

## Introduction

The CAS protocol is a simple and powerful ticket-based protocol. It involves one or many clients and one server. Clients are embedded in CASified applications (called “CAS services”) whereas the CAS server is a standalone component.

## Register CAS client

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">1.</span> Open the **Identity &amp; Service Provider** page.

`<span class="link" id="bkmrk-main-menu">Main Menu</span><span id="bkmrk-%C2%A0%3E%C2%A0"> > </span><span class="link" id="bkmrk-administration">Administration</span><span id="bkmrk-%C2%A0%3E%C2%A0-0"> > </span><span class="link" id="bkmrk-configure-soffid">Configure Soffid</span><span id="bkmrk-%C2%A0%3E%C2%A0-1"> > </span><span class="link" id="bkmrk-web-sso">Web SSO</span><span id="bkmrk-%C2%A0%3E%C2%A0-2"> > </span><span id="bkmrk-identity-%26-service-p">Identity & Service providers</span>`

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">2.</span> To add a new service provider, click on the **Add Service Provider** button.

<p class="callout info">Be in mind that you can configure more than one Entity Group and you could add new service providers in each one.</p>

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">3.</span> Then you must fill in the required fields. Also, you need to provide the identity provider metadata. You can either copy it from the Soffid federation page or instruct the service provider to download the federation metadata by itself.

## [![image-1661408241083.png](https://bookstack.soffid.com/uploads/images/gallery/2022-08/scaled-1680-/image-1661408241083.png)](https://bookstack.soffid.com/uploads/images/gallery/2022-08/image-1661408241083.png)

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

# Connecting Tacacs+

## Introduction

TACACS (**Terminal Access Controller Access Control System**) is a security protocol that provides centralized validation of users who are attempting to gain access to a router or NAS

TACACS+ is a protocol for AAA services:

- Authentication
- Authorization
- Accounting

## Register Tacas+

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">1.</span> Open the **Identity &amp; Service Provider** page.

`<span class="link" id="bkmrk-main-menu">Main Menu</span><span id="bkmrk-%C2%A0%3E%C2%A0"> > </span><span class="link" id="bkmrk-administration">Administration</span><span id="bkmrk-%C2%A0%3E%C2%A0-0"> > </span><span class="link" id="bkmrk-configure-soffid">Configure Soffid</span><span id="bkmrk-%C2%A0%3E%C2%A0-1"> > </span><span class="link" id="bkmrk-web-sso">Web SSO</span><span id="bkmrk-%C2%A0%3E%C2%A0-2"> > </span><span id="bkmrk-identity-%26-service-p">Identity & Service providers</span>`

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">2.</span> To add a new service provider, click on the **Add Service Provider** button.

<p class="callout info">Be in mind that you can configure more than one Entity Group and you could add new service providers in each one.</p>

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">3.</span> Then you must fill in the required fields. Also, you need to provide the identity provider metadata. You can either copy it from the Soffid federation page or instruct the service provider to download the federation metadata by itself.

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

<p class="callout info">For more information about the attributes, you can visit [the Tacacs+ detailed info](https://bookstack.soffid.com/link/392#bkmrk-tacacs%2B).</p>

When a Tacacs Service Provider is created, Soffid creates an Information System

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

There are some roles defined for this Information System (0: anonymous, 1: user, ....15: root)

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

# Connecting Radius client

## Introduction

The Radius protocol (Remote Authentication Dial-In User Service) is a networking protocol that authorizes and authenticates users who access a remote network.

## Register a Radius client

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">1.</span> Open the **Identity &amp; Service Provider** page.

`<span class="link" id="bkmrk-main-menu">Main Menu</span><span id="bkmrk-%C2%A0%3E%C2%A0"> > </span><span class="link" id="bkmrk-administration">Administration</span><span id="bkmrk-%C2%A0%3E%C2%A0-0"> > </span><span class="link" id="bkmrk-configure-soffid">Configure Soffid</span><span id="bkmrk-%C2%A0%3E%C2%A0-1"> > </span><span class="link" id="bkmrk-web-sso">Web SSO</span><span id="bkmrk-%C2%A0%3E%C2%A0-2"> > </span><span id="bkmrk-identity-%26-service-p">Identity & Service providers</span>`

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">2.</span> To add a new service provider, click the **Add Service Provider** button.

<p class="callout info">Be in mind that you can configure more than one Entity Group and you could add new service providers in each one.</p>

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">3.</span> Then, you must fill in the required fields. Also, you need to provide the identity provider metadata. You can either copy it from the Soffid federation page or instruct the service provider to download the federation metadata by itself.

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

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