Single Sign On (OIDC)

Single sign-on (SSO) is a way to log in only once and access different applications using the same login details. It is convenient, efficient, and secure. You just need to change the password once and not have to worry about updating it across other applications.

Login with SSO

MediationZone supports SSO using an OpenID Connect (OIDC) compliant Identity Provider. Microsoft Active Directory can be configured to act as such an Identity Provider.

The system can act as a Relaying Party in the OIDC 1.0 flow. Refer for more details: https://openid.net/specs/openid-connect-core-1_0.html.

The conceptual diagram below describes the details of the OIDC SSO authentication flow toward Active Directory.

OIDC SSO Authentication Diagram

Configuration

To turn on SSO several properties need to be added to the platform and will take effect after a platform restart. The following properties are mandatory.

Property	Description

Property	Description
auth.oidc.rp.client.id	Default value "" Client ID provided by Identity Provider. If it is not present, the SSO functionality is disabled.
auth.oidc.rp.provider.url	Default value "" Provide the Base URL to the associated Identity Provider. This URL, concatenated with `/.well-known/openid-configuration`, must retrieve the OpenID Provider's configuration as per the OpenID Connect Discovery specification. Example: https://login.microsoftonline.com/<tenant_ID>/v2.0
auth.oidc.rp.provider.name	Default value "" The name of the provider needs to be Azure if it is used and groups are returned as uids.
auth.oidc.rp.groupPath	Default value "roles" Path in ID Token or UserInfo object to find an array of users Access groups as defined by the Access Controller, separated with a dot (.). The groups should be an array of Strings. Example: Groups array in an object Here the groups array is inside an object. { myObject : { myGroups : [ "myGroup1", "mygroup2" ] } } The path should then be: groupPath: myObject.myGroups When the group's array is directly under UserInfo then groupPath is just the name of the group's array.
auth.oidc.rp.auth.method	Default value "CLIENT_SECRET_BASIC" Available authentication methods are CLIENT_SECRET_BASIC and PRIVATE_KEY_JWT

The following property is mandatory when CLIENT_SECRET_BASIC is used as an authentication method:

Property	Description

Property

Description

auth.oidc.rp.client.secret

Default value ""

This property sets the relevant Client Secret. Needs to be encrypted.

You need to add the following values to the OIDC provider as redirect URLs:

Property	Description

Property	Description
User Interface	http(s)://<hostname>:<ui-webserver-port>/desktop/sso
Desktop Launcher	http(s)://<hostname>:<platform-webserverport>/launch/api/desktop/v1/sso

The following properties are mandatory when PRIVATE_KEY_JWT is used as an authentication method:

Property	Description

Property	Description
auth.oidc.rp.auth.jwt.keystorePath	Default value "" Path to JKS keystore when PRIVATE_KEY_JWT is used
auth.oidc.rp.auth.jwt.alias	Default value "" Alias for key in keystore when PRIVATE_KEY_JWT is used
auth.oidc.rp.auth.jwt.keystorePassword	Default value "" Keystore password when PRIVATE_KEY_JWT is used, needs to be Encrypted by MediationZone.
auth.oidc.rp.auth.jwt.keyPassword	Default value "" Key password when PRIVATE_KEY_JWT is used, needs to be Encrypted by eMediationZone.

The following properties are optional:

Property	Description

Property	Description
auth.oidc.rp.scopes	Default value "" Optional additional scopes. Default scopes are openid, profile, and email.
auth.oidc.rp.claims.username	Default value "" Claim to use as the user name, if not specified sub will be used. This value should be unique.
auth.oidc.rp.auth.jwt.keyId	Default value "" Optional Key ID for JWT header when PRIVATE_KEY_JWT is used
auth.oidc.rp.group.syncDisabled	Default value false. Disable group synchronization from Identity Provider. When this is true groups are set manually on each SSO User.
auth.oidc.rp.group.default	Default value "" When Group Sync is disabled a default group can be added to users logged in through SSO
auth.oidc.rp.multigroupsync.defaultGroup	Default value "" This property assigns a default group to the user who is a member of multiple groups when the user logs in for the first time. It takes effect only when the group synchronization is enabled. The default group can be changed after logging in and must be one of the member groups. Changes made to the default group after logging in will persist in the next login.
auth.oidc.rp.auth.debug	Default value false. Set this to true during the implementation of SSO Access to get more information.

Use the following command to add the properties:

Topo Example

mzsh topo open platform

Azure as Identity Provider

When Azure is used as an ID provider, be sure to set the property auth.oidc.rp.provider.name to Azure to be able to fetch the groups. Then the groups are fetched from Microsoft Graph REST API. A request to the user's endpoint to get the group membership is performed. Make sure to add API Permission GroupMember.Read.All in Azure.

Private Key Authentication

When the method: "PRIVATE_KEY_JWT" is used, you need to create a Java Keystore in JKS format using an EC or RSA algorithm. The signing algorithm of the JWT used to authenticate to the Token Endpoint will be RS256 for RSA keys and ES256 for EC keys.

The script below shows how these can be generated. Note that this will generate a self-signed certificate, which is not suitable for use in publicly exposed interfaces. Make sure to set the parameters at the beginning of the script before execution. This script produces the ssokeystore.jks. It also produces the file publicCert.pem, this file should be uploaded to the ID provider in advance.

Example - How to generate a self-signed certificate

#!/bin/bash
KEY_PASSWORD=DefaultKeystorePWD
STORE_PASSWORD=DefaultKeystorePWD
DNAME=CN=exampledomain.com,O=Example

rm -f ssokeystore.jks publicCert.pem
 
keytool -genkey -keystore ssokeystore.jks -storepass $STORE_PASSWORD -keypass $KEY_PASSWORD -alias certificate -keyalg RSA -keysize 2048 -dname $DNAME 
keytool -keystore ssokeystore.jks -exportcert -alias certificate -rfc -file publicCert.pem -deststorepass $STORE_PASSWORD