OAuth 2.0 and OIDC Authentication in MATLAB Online Server

In MATLAB^® Online Server™, you can configure authentication using an OAuth 2.0 and OpenID Connect (OIDC) identity provider (IdP). OAuth 2.0 is an authorization protocol that allows third-party applications such as MATLAB Online Server to access resources on behalf of a user. For details about this protocol, see the OAuth 2.0 specification. OIDC is an authentication protocol that layers additional functionality on top of OAuth 2.0. For information about how OIDC works, see the OpenID specification.

Prerequisites

MATLAB Online Server is installed. See Installation.
Your organization's IdP follows the OAuth 2.0 protocol and, optionally, the OIDC protocol. If your IdP does not use OIDC, then the server obtains user data from the user information endpoint URL of your OAuth 2.0 IdP.
You have access to your IdP. To obtain access, contact your identity management administrator.
You are familiar with the MATLAB Online Server authentication workflow. See Configure User Authentication in MATLAB Online Server.

Deploy Client Secret

OAuth 2.0 and OIDC IdPs include a password-like attribute called a client secret. MATLAB Online Server uses the client secret to request access tokens on behalf of users. To make the client secret available to MATLAB Online Server, deploy it to the server as a Kubernetes secret.

Create a YAML file named oauth-client-secret.yaml with these contents:

`oauth-client-secret.yaml`
apiVersion: "v1" kind: "Secret" metadata: name: "oauth-client" data: secret: <client secret> # must be base-64 encoded

apiVersion and kind are standard fields in Kubernetes^® secrets. Set apiVersion to "v1" and kind to "Secret".
name is the name you want to give the Kubernetes secret. The default is "oauth-client". If you specify a custom name value, then in the Configure Identity Provider step, you must specify this value in the secretName field so that MATLAB Online Server can read the correct Kubernetes secret.
secret is the client secret string. This string must use base 64 encoding. To generate a base-64 encoding for a string, use this command:
```
echo -n <client secret> | base64
```

Deploy the contents of this file to the server as a Kubernetes secret. Replace your-namespace with your MATLAB Online Server namespace.

kubectl apply -f "oauth-client-secret.yaml" --namespace your-namespace

Open Configuration File

In a plain-text editor, open the authnz.yaml file, which configures information about your IdP.

server_root/overrides/cluster/namespace/authnz.yaml

server_root is the root folder of your MATLAB Online Server installation. For example: matlab_online_server
cluster is the name of your Kubernetes cluster. For example: matlab-online-server
namespace is the Kubernetes namespace you used to deploy MATLAB Online Server. For example: mathworks

Remove Local Accounts

If your configuration still includes local accounts (type: "local"), remove them from the authnz.yaml file or comment them out. For example:

identityProviders:
#  - id: "local"
#    type: "local"
#    accounts:
#      - subjectId: "admin"
#        displayName: "admin"
#        password: "password"
#        extra: {}

Security Considerations: Local user accounts are for testing purposes only and do not meet production security standards. Deploying them to production is not recommended.

Configure Identity Provider

In the identityProviders section, add the following structure and update the fields with information from your IdP. Commented-out fields are optional. Fields with values in angle brackets (<>) have no defaults.

identityProviders:
  - id: "<display name used identify IdP on server>"
    type: "oidc"
    clientId: "<client ID>"
#   oidc:    # required if authorizationLocation, tokenLocation, and graphLocation are not specified
#     enabled: false
#     discoveryUrl: "<https://user/information/endpoint/URL>"
#     retryMode: "retry"
#   authorizationLocation: "<https://authorization/endpoint/URL>" # required if oidc not enabled and disoveryUrl not specified
#   tokenLocation: "<https://token/endpoint/URL>"                 # required if oidc not enabled and disoveryUrl not specified
#   graphLocation: "<https://user/information/endpoint/URL>"      # required if oidc not enabled and disoveryUrl not specified
#   redirectPath: "/authnz/oauth/code"
#   secretName: "oauth-client"
#   scopes: "user.read,openid,profile,email"
#   pkce:
#     enabled: false
#     challengeMethod: "S256"
#     challengeLength: 32
#   delegation:
#     gcp:
#       <GCP delegation configuration fields>
#   subjectAttributeMapping:
#     subjectId: "<IdP username attribute>"
#     displayName: "<IdP display name attribute>"
#     groups: "<IdP user group attribute>"
#     extra:
#       email: "<IdP user email attribute>"
#       uid: "<IdP UNIX user ID attribute>"
#       gid: "<IdP UNIX group ID attribute>"

Field	Default Value	Required or Optional	Description
`id`	`""`	Required	Display name that identifies the IdP in MATLAB Online Server microservices and log files.
`type`	`"oauth"`	Required	Type of IdP. To configure local user accounts, you must set `type` to `"oauth"`.
`clientId`	`""`	Required	Client identifier, which must be the same as the client identifier in the IdP.
`oidc`	`""`	Optional (Required if you do not specify `authorizationLocation`, `tokenLocation`, and `graphLocation`)	URL that MATLAB Online Server uses to look up the authorization, token, and user endpoints required by the OIDC protocol. Specify these subfields: `enabled` — Set this subfield to `true` to enable specifying the URL from which to look up the endpoints. If you set this subfield to `false` or omit the `oidc` field, specify these endpoints in the `authorizationLocation`, `tokenLocation`, and `graphLocation` fields. `discoveryUrl` — URL that the server uses to look up the endpoints. Get this URL from your IdP. This URL typically contains `/.well-known/` in the path. `retryMode` — Mode that the `authnz` service uses to fetch OIDC information from `discoveryUrl` after an unsuccessful attempt. Specify one of these strings: `"retry"` (default) — Fetch information from `discoveryUrl` every 2ⁿ seconds (1, 2, 4, and so on). If the `authnz` service is unable to fetch information after 64 seconds, Kubernetes might restart the service after a few minutes. `"bypass"` — Perform no operation and log any error messages. `"panic"` — Send a "panic operation" to Kubernetes so that it attempts to restart the pod. The `authnz` service then attempts to fetch the OIDC information again after restarting. You must specify either the `oidc` field or the `authorizationLocation`, `tokenLocation`, and `graphLocation` fields, but not both. Example: oidc: enabled: true discoveryUrl: https://host/.well-known/... retryMode: "bypass"
`authorizationLocation`	`""`	Optional (Required if you do not enable `oidc` and do not specify `discoveryUrl`)	Authorization endpoint. For details about this endpoint, see its description in the OAuth 2.0 Authorization Framework. If you set the `oidc` field to look up this endpoint from a discovery URL, omit this field. Example: `authorizationLocation: "https://keycloak.example.com/realms/example-realm/protocol/openid-connect/auth"`
`tokenLocation`	`""`	Optional (Required if you do not enable `oidc` and do not specify `discoveryUrl`)	Token endpoint. For details about this endpoint, see its description in the OAuth 2.0 Authorization Framework. If you set the `oidc` field to look up this endpoint from a discovery URL, omit this field. Example: `tokenLocation: "https://keycloak.example.com/realms/example-realm/protocol/protocol/openid-connect/token"`
`graphLocation`	`""`	Optional (Required if you do not enable `oidc` and do not specify `discoveryUrl`)	User information endpoint. For details about this endpoint, see its description in the OIDC specification.This endpoint must use the HTTPS protocol and can include port, path, and query parameters. If you set the `oidc` field to look up this endpoint from a discovery URL, omit this field. Example: `graphLocation: https://keycloak.example.com/realms/example-realm/protocol/openid-connect/userinfo`
`redirectPath`	`"/authnz/oauth/code"`	Optional	Path portion of the redirection endpoint. For details about this endpoint, see its description in the OAuth 2.0 Authorization Framework. The default value results in this redirection endpoint: `https://domain-base/authnz/oauth/code` where `domain-base` is the value of the `DOMAIN_BASE` property in your `install.config` file.
`secretName`	`"oauth-client"`	Optional	Name of the Kubernetes secret that contains the client secret associated with the `clientId`. Specify the `name` field of the Kubernetes secret you deployed in the Deploy Client Secret step.
`scopes`	`"user.read,openid,profile,email"`	Optional	Comma-separated list of permissions that the OAuth 2.0 and OIDC protocols have. Do not insert a space after each comma.
`pkce`	`""`	Optional	Use the proof key for code exchange (PKCE) protocol for authentication. PKCE is an extension of the OAuth 2.0 and OIDC protocols. The `pkce` field has these subfields. `enabled` — Set this subfield to `true` to enable PKCE. To disable PKCE, set this subfield to `false` or omit the `pkce` field. `challengeMethod` — Challenge method that encodes the authentication string sent between MATLAB Online Server and the IdP, which you can specify as `"S256"` (SHA256 encoding—default if you omit this field) or `"plain"` (plain-text encoding—not recommended). `challengeLength` — Length of the authentication string, which you can specify as an integer from `32` to `96`. If you omit this field, the default string length is 32 characters. For more details on PKCE, see Authorization Code Flow with Proof Key for Code Exchange on the Auth0 website. Example: pkce: enabled: true challengeMethod: "S256" challengeLength: 32
`delegation`	`""`	Optional	Give MATLAB Online Server delegated access to the cloud storage accounts of users. When you enable delegation, the server acquires the credentials that users need to access their cloud storage so their data is available to them as soon as they sign in to MATLAB Online™. OIDC supports delegation for this cloud platform service: Google Cloud Platform™ (GCP) delegation: gcp: <GCP delegation configuration fields> For details on configuring GCP delegation, see Enable Access to Google Cloud Platform Storage Using Delegation.
`subjectAttributeMapping`	`{}`	Optional	Map of user-related attributes from your IdP to the corresponding YAML fields in MATLAB Online Server. The server uses these fields to look up information about the user for use across services on the cluster. Valid fields are as follows. Enclose each `subjectAttributeMapping` field value in quotes. subjectAttributeMapping: subjectId: "<IdP username attribute>" displayName: "<IdP display name attribute>" groups: "<IdP user group attribute>" extra: email: "<IdP user email attribute>" uid: "<IdP UNIX user ID attribute>" gid: "<IdP UNIX group ID attribute>" `subjectId` — Username or user ID attribute in IdP. When the server checks out a license, the value from this attribute appears in license server logs. `displayName` — User display name attribute in IdP. The value from this attribute appears in the MATLAB Online Server user interface. `groups` — Group attribute in IdP. Values from this attribute lists the groups that the user belongs to. You can use these values in the `allowedGroups` field of the `matlab-pool` YAML file to restrict MATLAB access to specific user groups. For details, see Configure Group-Based Authorization in MATLAB Online Server. `extra` — Additional IdP attributes that the server uses to configure user-specific storage folders on the network file system. `email` — User email address attribute in IdP `uid` — UNIX^® user ID attribute in IdP `gid` — UNIX group ID attribute in IdP Do not leave any field in the `extra` section empty. Either specify a value or remove the empty field. If your `extra` section is empty, omit the section entirely. For details on how to configure user storage by using these fields, see Configure File Storage for Users in MATLAB Online Server.

Sample Configuration

replicaCount: 1
identityProviders:
  - id: "oauth"
    type: "oauth"
    clientId: "example-realm-oidc"
    authorizationLocation: "https://example-keycloak.example.com/realms/example-realm/protocol/openid-connect/auth"
    tokenLocation: "https://example-keycloak.example.com/realms/example-realm/protocol/openid-connect/token"
    graphLocation: "https://example-keycloak.example.com/realms/example-realm/protocol/openid-connect/userinfo"
    scopes: "openid,profile,roles"
    subjectAttributeMapping:
      subjectId: "preferred_username"
      displayName: "preferred_username"
      groups: "groups"
      extra:
        email: "email"
        uid: "uidNumber"
        gid: "gidNumber"

The graphLocation field (user information endpoint) returns a JSON response similar to the following:

{\"sub\":\"269e67a3-877a-4525-9c88-fb8707ac7a93\",\"randomAttribute\":\"user1RandomAttribute\",
\"resource_access\":{\"account\":{\"roles\":[\"manage-account\",\"manage-account-links\",
\"view-profile\"]}},\"email_verified\":false,\"groups\":[\"non-gpu\",\"user\"],
\"preferred_username\":\"user1\",\"given_name\":\"user1_FirstName\",
\"realm_access\":{\"roles\":[\"non-gpu\",\"user\"]},\"uidNumber\":\"7777\",
\"name\":\"user1_FirstName user1_LastName\",\"gidNumber\":\"7777\",
\"family_name\":\"user1_LastName\",\"email\":\"user1@example.com\"}

The license server logs an entry similar to the following:

21:52:53 (MLM) OUT: "MATLAB" user1@mathworks-matlab-pool-7b775bc559-ct2vv

Additionally, the MATLAB Online Server user interface displays "user1" as the username.

If other attributes passed as claims from the IdP must appear in the license server logs and MATLAB Online Server user interface, then update the mapping. For example, suppose you use randomAttribute instead of preferred_name for the license log entry and the username in the user interface.

identityProviders:
  - id: "oauth"
    type: "oauth"
    clientId: "ex-realm-oidc"
      authorizationLocation: https://ex-keycloak.matlabonlineserver.com/realms/ex-realm/protocol/openid-connect/auth
      tokenLocation: https://ex-keycloak.matlabonlineserver.com/realms/ex-realm/protocol/openid-connect/token
      graphLocation: https://ex-keycloak.matlabonlineserver.com/realms/ex-realm/protocol/openid-connect/userinfo
      scopes: "openid,profile,roles"
      subjectAttributeMapping:
        subjectId: "randomAttribute"
        displayName: "name"
        groups: "groups"
        extra:
          email: "email"

The license server would contain an entry similar to the following:

21:52:53 (MLM) OUT: "MATLAB" user1RandomAttribute@mathworks-matlab-pool-7b775bc559-ct2vv

The MATLAB Online Server user interface would display "user1_FirstName user1_LastName" as the username.

Because of the value set for the groups field in the sample subjectAttributeMapping above and the associated values of the claims returned by the IdP, the user is allowed to access a MATLAB version that has the following configuration in the associated matlab-pool.yaml file.

resourceDefinition:
  allowedGroups:
  - "gpu"

Deploy Configuration

To deploy your changes to the server, redeploy the authnz service. From the MATLAB Online Server root folder, run these commands.

./mosadm undeploy authnz
./mosadm deploy authnz

If your IdP configures single sign-on (SSO), your users can now sign in to MATLAB Online using their SSO credentials.

If you are configuring multiple IdPs, the server uses the first IdP listed in the identityProviders section as the default IdP. To authenticate users with a nondefault IdP, in the MATLAB Online URL you give to users, include an IdPId query parameter that specifies the ID value of the IdP. For example:

https://domain-base/matlabonline?idpId=id

where domain-base is the value of the DOMAIN_BASE property in your install.config file. For more information, see Configure Multiple Identity Providers.