SAML2 Integration

Available from version 3.0-jailbreak

1 Note
2 Configuration in Keycloak
- 2.1 Identity Provider
- 2.2 Authentication Flow
3 Configuration in Service Provider (SP) or applications
4 Extra nginx configuration
5 Authentication scheme with SAML

Starting from platform version 3.0-jailbreak, it is possible to use Keycloak as advanced IM and configure Identity Brokering with a SAML2 IdP.

This will allow you to delegate the authentication to the IdP having Keycloak as an intermediary, so you can continue using Oauth2 as authentication/authorization standard in the platform and applications that work with it.

Note

Although you can still use OAuth and the tokens generated by this mechanism, only the authorization code flow can be used to obtain the token. This is because, as is well known, SAML2 is a synchronous protocol that requires the participation of the browser in a series of redirections. Once the token is obtained, it can be used in the Authorization HTTP headers.

Configuration in Keycloak

The first step is to configure identity brokering in Keycloak.

Identity Provider

The first step is to register the IdP SAML2 server. To do this, you will have to log into the Keycloak administration console. (e.g. https://development.onesaitplatform.com/auth/ )

Once inside, go to the Realm "onesaitplatform", which is the one used by default if multitenant is not used.

Next, go to the "Identity providers" section of the menu, and add a new one of type "SAML v2.0":

Here you will have to configure a number of parameters related to the IdP to be used.

alias → Name of the configured IdP (e.g. saml2idp)

Single Sign-On Service URL → IdP SSO service URL (e.g. http://localhost:8082/simplesaml/saml2/idp/SSOService.php)

Single Logout Service URL → IdP Log Out Service URL (e.g. http://localhost:8082/simplesaml/saml2/idp/SingleLogoutService.php)

Principal Type → Attribute [Name]

Principal Attribute → Name of the SAML attribute where the single userid information is stored (e.g. uid or sAMAccountName).

The rest of the parameters will be left as default. Click on the save button to save the configuration.

Once saved, go to the mappers tab, where you will have to add all the attributes that come from the SAML assertion and that you are going to import to be able to map with a platform user (userid, email, name).

Click on "create" to add a new attribute.

Next, select Attribute importer and the name of the attribute to import (e.g. uid, which will be the userid of the user in platform).

Repeat the process for email and name, leaving 3 mappers defined:

Authentication Flow

Now, you have to create the flow for the import of the user in the first log in.

Go to "Authentication" in the menu, and, in the same tab "Flows", click on "New":

Give it an alias and click on "save".

Once the Flow is created, it will appear in the list of the "Flows" combo box.

Now, you must click on "Add execution". Select as provider "Process IdP Login Callbak", and click on "save".

You will return to the Flows view with the new execution. In the same execution on the right, click on "Actions → Config" to configure the execution.

Here, you need to map the platform attributes: username, email and fullName with the SAML attributes that have been imported earlier. In addition, you have a field "admins whitelist", where you can indicate a comma-separated list of users to assign them ROLE_ADMINISTRATOR in platform.

Finally, you go back to "Identity providers" through the menu, and select the SAML IdP you created in the previous step. You look for the configuration parameter "First Login Flow" and select the Flow you just created:

Save the changes.

Configuration in Service Provider (SP) or applications

Once Keycloak is configured, you only need to configure the OAuth client that will use this authentication.

ClientId and ClientSecret will be: onesaitplatform

Oauth authorization code URL: https://{HOST}//auth/realms/onesaitplatform/protocol/openid-connect/auth?scope=openid&kc_idp_hint=saml2idp

Add the parameter kc_idp_hint=saml2idp that makes reference to the alias of your SAML2 provider, so that when redirecting to Keycloak, the SAML2 provider already knows that you want to authenticate through SAML, and not through platform’s user and password.

Once the application is up, when the authentication flow is triggered, you will be redirected to IdP to log in. Once authenticated in the IdP SAML2, you will be returned to the client application with a JWT token.

Below is an example using a simplesaml server as IdP for the demonstration.

Token obtained after login:

Extra nginx configuration

proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header    X-Forwarded-Host $host;
proxy_set_header Host $host;

Keycloak ENV VAR:

Onesait Platform Enterprise Docs

Features | Open Source | Releases | Docs | Try us free | Blog | Product