Single Sign On
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.
SSO-enabled Launcher
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 describe the details of the OIDC SSO authentication flow toward Active Directory.
OIDC SSO Authentication Diagram
Configuration
To turn on SSO a number of properties need to be added to the platform and will take effect after a platform restart.
The following properties are mandatory.
| 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. |
| 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 (.). |
| auth.oidc.rp.auth.method | Default value "CLIENT_SECRET_BASIC" Available authentication methods are CLIENT_SECRET_BASIC and PRIVATE_KEY_JWT |
The following properties are mandatory when CLIENT_SECRET_BASIC is used as an authentication method:
| 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 |
|---|---|
| User Interface | http(s)://<hostname>:<ui-webserver-port>/desktop/sso |
| Desktop Launcher | http(s)://<hostname>:<platform-webserver-port>/launch/api/desktop/v1/sso |
The following properties are mandatory when PRIVATE_KEY_JWT is used as an authentication method:
| 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 |
| auth.oidc.rp.auth.jwt.keyPassword | Default value "" Key password when PRIVATE_KEY_JWT is used, needs to be Encrypted by |
The following properties are optional:
| 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 specify 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 |
Use the following command to add the properties:
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. The reason for this is that Azure is sending a list of group ids, but the system needs the Access group name. When ID Provider is Azure it uses the group id to fetch the group name from the Azure Graph API endpoint, currently using v1.
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.
#!/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