Enable SSO Access to OAuth 2.0 and OIDC-Authenticated Resources Using Delegation

Since R2024b

In MATLAB^® Online Server™, your users might need to access resources that require the same single sign-on (SSO) credentials they used to sign in to MATLAB Online™. To prevent users from having to sign in every time they access these resources, you can configure the MATLAB sessions of your users to have delegated access to their SSO credential tokens.

This form of SSO access requires an OAuth 2.0 or OpenID Connect (OIDC) identity provider (IdP). If your organization uses a cloud storage provider to host remote resources, you can enable SSO access by following one of these procedures instead:

Prerequisites

Your organization uses an OAuth 2.0 or OIDC IdP to authenticate MATLAB Online Server users. For details about configuring the IdP in MATLAB Online Server, see OAuth 2.0 and OIDC Authentication in MATLAB Online Server.
Any remote storage resources your users access must be configured as public client applications in your IdP. MATLAB Online Server does not support delegated access to confidential client applications.

Deploy Kubernetes Secret for User Credentials

To delegate SSO user access to remotely stored resources, MATLAB Online Server transmits user credentials between services in the Kubernetes^® cluster. Encrypt these credentials by storing them in a Kubernetes secret object and deploying the object to the cluster.

Note

If you already deployed a Kubernetes secret object for user credentials to the cluster, proceed to the next section.

Generate a random 64-bit-encoded string that the cluster can use to encrypt the user credentials. For example, this Linux^® bash script generates a random string of alphanumeric characters wrapped onto 32-character lines.
#!/bin/bash SECRET=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1) echo $SECRET echo -n $SECRET | base64

Create a file named credentials-secret.yaml and copy in the fields shown. For the credentials-secret field, replace <secret string> with the string you generated in the previous step. Save the file in any location on the Kubernetes cluster.

`credentials-secret.yaml`
apiVersion: "v1" kind: "Secret" metadata: name: "credentials-secret" data: credentials-secret: "<secret string>"

Deploy the secret to the Kubernetes cluster. Replace <namespace-name> with your MATLAB Online Server namespace.
```
kubectl apply -f credentials-secret.yaml --namespace <namespace-name>
```

Configure Delegated Access on MATLAB Online Server

Configure the services running in MATLAB Online Server to have delegated access to users' credential tokens.

Configure Authentication Service

Enable delegation in the MATLAB Online Server authentication service, authnz, by configuring the authnz.yaml file, located here:

<server-root>/overrides/<cluster-name>/<namespace-name>/authnz.yaml

<server-root> is the name of the MATLAB Online Server installation folder.
<cluster-name> is the name of the Kubernetes cluster.
<namespace-name> is the namespace of the MATLAB Online Server deployment.

Sample path:

~/matlab_online_server/overrides/matlab-online-server/mathworks/authnz.yaml

Under identityProviders, within the id section for your IdP, add a delegation section with this structure. The supported identity providers are OAuth 2.0 or OAuth 2.0 with OIDC. For more details, see OAuth 2.0 and OIDC Authentication in MATLAB Online Server.

Sample OAuth 2.0 configuration:

identityProviders:
  - id: "oauth"
    type: "oauth"
    clientType: "public"

    # standard OAuth 2.0 configuration
    ...

    delegation:
      identityPassthrough:
#       failureMode: "bypass" # (default) | "halt"

Sample OAuth 2.0 with OIDC configuration:

identityProviders:
  - id: "oauth"
    type: "oauth"
    clientType: "public"
    oidc:
      enabled: true

    # standard OAuth 2.0 with OIDC configuration
    ...

    delegation:
      identityPassthrough:
#       failureMode: "bypass" # (default) | "halt"

The IdP is now configured to provide MATLAB Online Server with delegated access to user SSO credential tokens. The server stores the tokens in these locations:

JSON file — /home/matlab/.OIPT/tokens.json
Environment variable — OIPT_TOKENS

The table describes the fields you can configure in the identityPassthrough section.

Field	Required or Optional	Description
`failureMode`	Optional	Action that the authentication provider takes when a delegation request fails. `"bypass"` (default) — Process the failed delegation request as a warning and enable the user to log in to MATLAB Online. `"halt"` — Process the failed delegation request as an error and do not log the user in to MATLAB Online.

Configure Other Services

Enable delegation in all other services by configuring the all.yaml file, located here:

<server-root>/overrides/<cluster-name>/<namespace-name>/all.yaml

<server-root> is the name of the MATLAB Online Server installation folder.
<cluster-name> is the name of the Kubernetes cluster.
<namespace-name> is the namespace of the MATLAB Online Server deployment.

Sample path:

~/matlab_online_server/overrides/matlab-online-server/mathworks/all.yaml

In the global section, add a delegation section with this structure.

global:
  tls:
    enabled: true
 
  delegation:
    providers:
      - type: "oipt" # OAuth 2.0 and OIDC identity passthrough
        enabled: true

Configure these fields.

Field	Required or Optional	Description
`providers`	Required	Delegation provider. To enable OAuth 2.0 and OIDC identity passthrough, `type` must be `"oipt"` and `enabled` must be `true`.

Deploy Changes to Server

To apply your changes, undeploy and redeploy the server.

./mosadm undeploy
./mosadm deploy

After redeploying, the configuration changes take effect for users the next time they log in to MATLAB Online with their SSO credentials.

Enable Resources to Access Credentials

Although users' MATLAB Online sessions contain the SSO credential tokens, the remote resources do not automatically have access to the tokens. Enable the resources to access these credentials. For example, if users access a resource from a website, write a script that passes the tokens as a web request to that resource. The script to write depends on the type of resource being accessed.

You can get the credential tokens to use in your script from users' MATLAB sessions. To open the file containing these tokens, enter this command at the MATLAB command prompt. The output shows a sample set of tokens authenticated using OAuth 2.0 with OIDC.

open(getenv("OIPT_TOKENS"))

{
    "IDToken": "eyJ0eXAi...",
    "AccessToken": "eyJ0eXAi...",
    "RefreshToken": "0.AScAET..."
}