MSAL Authentication in MATLAB Online Server

In MATLAB^® Online Server™, you can configure authentication using the Microsoft^® Authentication Library (MSAL) with an OAuth 2.0 and OpenID Connect (OIDC) identity provider (IdP). MSAL provides simplified configuration options for OAuth 2.0 and OIDC IdPs that your organization hosts on the Microsoft identity platform. For details, see Overview of the Microsoft Authentication Library (MSAL) in the Microsoft documentation.

Prerequisites

MATLAB Online Server is installed. See Installation.
Your organization's IdP follows the OAuth 2.0 and OIDC protocols and runs on the Microsoft identity platform.
MATLAB Online Server is configured as a confidential client application in your IdP. For more details, see Public client and confidential client applications in the Microsoft documentation.
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 identity providers 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 msal-client-secret.yaml with these contents:

`msal-client-secret.yaml`
apiVersion: "v1" kind: "Secret" metadata: name: "msal-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 of the Kubernetes secret. Set name to "msal-client".
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 <namespace-name> with your MATLAB Online Server namespace.

kubectl apply -f "msal-client-secret.yaml" --namespace <namespace-name>

Open Configuration File

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

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

<server-root> is 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

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: "msal"
    clientId: "<client ID>"
    tenantId: "<tenant ID>"
#   redirectPath: "/authnz/msal/code"
#   scopes: "https://graph.microsoft.com/.default"
#   delegation:
#     azure:
#       <Azure delegation configuration fields>
#     gcp:
#       <GCP delegation configuration fields>
#   subjectAttributeMapping:
#     subjectId: "<username attribute in IdP>"
#     displayName: "<display name attribute in IdP>"
#     groups: "<user group attribute in IdP>"
#     extra:
#       email: "<user email attribute in IdP>"
#       uid: "<UNIX user ID attribute in IdP>"
#       gid: "<UNIX group ID attribute in IdP>"

Field	Default Value	Required or Optional	Description
`id`	`""`	Required	Display name that identifies the IdP in MATLAB Online Server microservices and log files.
`type`	`"msal"`	Required	Type of IdP. To configure local user accounts, you must set `type` to `"msal"`.
`clientId`	`""`	Required	Client ID value. In Microsoft IdPs, this value is also known as the application ID.
`tenantId`	`""`	Required	Tenant ID value. In Microsoft IdPs, this value is also known as the directory ID.
`redirectPath`	`"/authnz/msal/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/msal/code` where `domain-base` is the value of the `DOMAIN_BASE` property in your `install.config` file.
`scopes`	`"https://graph.microsoft.com/.default"`	Optional	Scopes used to obtain login and user information. Separate multiple scopes with a comma. Do not insert a space after each comma.
`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™. MSAL supports delegation for these cloud platform services: Azure^® delegation: azure: <Azure delegation configuration fields> For details on configuring Azure delegation, see Enable SSO Access to Azure Resources Using Delegation. Google Cloud Platform™ (GCP) delegation: gcp: <GCP delegation configuration fields> For details on configuring GCP delegation, see Enable SSO Access to Google Cloud Platform Resources 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.

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.

External Websites

Overview of the Microsoft Authentication Library (MSAL)