Single Sign On(3.2)

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

To turn on the feature a number of properties must be added to the values.yaml file. The properties of the file are described below.

rp:
      # Activate/deactivate Usage Engine Private Edition as OIDC Relay Party
      enabled: false
      
      auth:
        # Available auth methods is CLIENT_SECRET_BASIC and PRIVATE_KEY_JWT
        method: "CLIENT_SECRET_BASIC"
        client:
          # Client id
          id: ""
          # Client secret is only used when the method is CLIENT_SECRET_BASIC
          # Uncomment if credentials are not already provided through secret "oidc-rp-secret"
          #secret: ""
        # JWT section only used when method is PRIVATE_KEY_JWT
        jwt:
          #Opional ID Provider KeyId
          keyId:
          jks:
            secret:
              #Name of secret to store jks
              name:
            #Key Alias
            alias:

            #Key password
            # Uncomment if credentials are not already provided through secret "oidc-rp-secret"
            #password:

            #Keystore password
            # Uncomment if credentials are not already provided through secret "oidc-rp-secret"
            #storePassword:

      provider:
        # Base URL for Identity Provider
        # URL before /.well-known/openid-configuration
        # Eg. https://login.microsoftonline.com/<tenant_ID>/v2.0
        url:
        # Name of Provider, eg. Azure
        name: ""
      
	group:
        # Path in UserInfo or ID Token to find access groups mapping, separated by dot (.)
        # The groups should be a array of Strings.
        # *** Exampel ***
        # Here is the groups array inside a object.
        # { myObject : { myGroups : [ "myGroup1", "mygroup2" ] } }
        # The path should then be:
        # groupPath: myObject.myGroups
        # When the groups array is direct under UserInfo then groupPath is just the 
        # name of the groups array.
        path:
        # Disable group syncronization from Identity Provider.
        # When this is true groups is set manually on SSO Users
        syncDisabled: false
        # When Group Sync is disabled a defualt group can be added to users logged in through SSO
        defaultGroup: ""


      # Claim to use for Username
      userNameClaim:

      # Additional scopes
      scopes:

Kubernetes Secret

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-webserver-port>/launch/api/desktop/v1/sso

Credentials can be written into a Secret object named env-secrets prior to installation.

Example - Secret object

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

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