Single sign-on (SSO) is an authentication mechanism used to access different applications using the same credentials. It is convenient, efficient, and secure. Users need to change the password once and not have to worry about updating it across other applications using SSO.
Login with SSO option
Usage Engine supports SSO using an OpenID Connect (OIDC) compliant Identity Provider. Microsoft Active Directory can be configured as the Identity Provider. If this is not applicable, it is also possible to add an OIDC Proxy in front of the Active Directory to enable the OIDC protocol.
The system is configured as a Relaying Party in the OIDC 1.0 flow. For more details refer to 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
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 Users endpoint to get the group membership is performed. Make sure to add API Permission GroupMember.Read.All in Azure.
Configuration
The feature is configured via the helm chart. Refer to the auth.oicd.rp.* values in the values file for details.
Kubernetes Secret
You need to add the following values to the OIDC provider as redirect URLs:
Property | Description |
|---|---|
User Interface | http(s)://<desktop online hostname>:<desktop online web server port>/desktop/sso |
Desktop Launcher | http(s)://<platform hostname>:<platform web server port>/launch/api/desktop/v1/sso |
Credentials can be written into a Secret object named env-secrets prior to installation.
Example - Secret object
$ kubectl create secret generic oidc-rp-secrets -n <namespace> \ --from-literal=keystorePassword="<password>" \ --from-literal=keyPassword="<password>" \ --from-literal=clientSecret="<secret>"
Helm Values
Credentials can also be provided through values to Helm, by providing them in values.yaml or by passing them on the command line.
Example - Helm credentials
$ helm install <release_name> ./usage-engine-private-edition --wait --timeout=5m --namespace <namespace> \ --set auth.oidc.rp.auth.jwt.jks.storePassword="<password>" \ --set auth.oidc.rp.auth.jwt.jks.password="<password>" \ --set auth.oidc.rp.auth.client.secret="<secret>"
Private Key Authentication
When method: "PRIVATE_KEY_JWT" is used the section jwt needs to be defined.
In addition to the values in the helm values file, a Java Keystore in JKS format also needs to be created and put into a Kubernetes Secret. The name of the keystore needs to be ssokeystore.jks. The key algorithm needs to be RSA or EC. The signing algorithm of the JWT used to authenticate to the Token Endpoint is RS256 for RSA keys and ES256 for EC keys.
The script below shows how these can be generated and stored in the Secret. Note that this generates a self-signed certificate, which is not suitable for use in publicly exposed interfaces. Make sure to set the parameters in the beginning of the script before execution. This script produces the ssokeystore.jks and creates a secret from it. 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 K8S_NAMESPACE=<namespace> 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 kubectl create secret generic oidc-cert --namespace $K8S_NAMESPACE --from-file=ssokeystore.jks