Configure User Authentication in MATLAB Online Server

Authentication is the process of validating the identity of users when they sign in to MATLAB^® Online Server™, such as through the use of a third-party identity provider (IdP). You can integrate your organization's IdP with MATLAB Online Server to authenticate users and grant them access to authorized resources.

Authentication Workflow

This sample authentication workflow shows how users in your organization access MATLAB Online™.

The user signs in to MATLAB Online, either with a username and password or single sign-in (SSO) credentials.
In MATLAB Online Server, the authentication and authorization service, authnz, communicates with your organization's IdP to authenticate the user.
The authnz service communicates with the MATLAB resource pool to see if the user is authorized to access that resource. The authnz service also communicates with related services required to access MATLAB, such as the license service and storage resource service.
If authorization is successful, the server grants the user access to MATLAB Online.

Prerequisites

MATLAB Online Server is installed. See Installation.
Your organization's IdP follows one of these authorization and authentication protocols:
- OpenID Connect (OIDC) and OAuth 2.0
- Security Assertion Markup Language (SAML)
- Lightweight Directory Access Protocol (LDAP)

Configure Local User Accounts

Before configuring your organization's IdP, you can create local user accounts in memory to test signing in to MATLAB Online. By default, MATLAB Online Server configures one administrator account with these credentials:

Username — admin
Password — password (or the ML_PASSWORD parameter value that you set in the install.config file during installation)

To view details of this account, in a plain-text editor, open the authnz.yaml configuration file.

<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

Under identityProviders, the local identity provider section includes these default fields:

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

You can modify the account credentials or add more local accounts in the accounts section.

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

These tables describe the fields you can configure.

Global Fields

Field	Default Value	Required or Optional	Description
`id`	`"local"`	Required	Display name that identifies the local IdP in MATLAB Online Server microservices and log files.
`type`	`"local"`	Required	Type of IdP. To configure local user accounts, you must set `type` to `"local"`.

Account-Specific Fields

Field	Default Value	Required or Optional	Description
`subjectId`	`""`	Required	User ID or username for the account. Example: `"myusername"`
`displayName`	`""`	Required	Display name for the account. This name appears in the MATLAB user interface after the user signs in. Example: `"FirstName LastName"`
`password`	`""`	Required	Account password. Example: `"mypassword123!"`
`groups`	`[]`	Optional	Groups that the user belongs to, specified as a comma-separated list. Enclose the groups in square brackets, `[]`, even if you are specifying only one group. Use these groups to control which MATLAB configurations the user has authorization to access. Unlike groups that you configure through an IdP, the server does not validate groups in any way. For details on authorizing users by the groups they belong to, see Configure Group-Based Authorization in MATLAB Online Server. Example: `["group1","group2"]`
`extra`	`{}`	Optional	Extra metadata fields to add to the account when the user signs in. MATLAB Online Server does not validate this metadata in any way. 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. Enclose each value in square brackets, `[]`. Example: `{uid: ["1001"], department: ["MATLAB Online Server"]}`

This sample YAML configuration contains an administrator account and two user accounts:

identityProviders:
  - id: "local"
    type: "local"
    displayName: "local"
    accounts:
      - subjectId: "admin"
        displayName: "Admin"
        password: "mypassword123!"
        groups: ["admin"]
        extra: {}
      - subjectId: "testUser1"
        password: "mypassword456@"
        groups: ["user"]
        extra: {mail: ["user1@acme.com"]}
      - subjectId: "testUser2"
        password: "password789#"
        groups: ["user"]
        extra: {mail: ["user2@acme.com"]}

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

Configure Identity Provider

When you are ready to deploy the server to production, integrate your IdP with the authentication service.

In the identityProviders field, either delete or comment out the local accounts section. For example:

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

Create a new section for each identity provider. Set the type field to the value corresponding to the type of authentication and authorization protocol your IdP uses. Then, follow the configuration instructions shown in the table.

Authentication and Authorization IdP Type	`authnz.yaml` Structure	Configuration Instructions
OAuth 2.0 with optional OpenID Connect (OIDC) support	identityProviders: - id: "<IdP ID>" type: "oauth" ...	OAuth 2.0 and OIDC Authentication in MATLAB Online Server
OAuth 2.0 with optional OIDC support using Microsoft^® Authentication Library (MSAL)	identityProviders: - id: "<IdP ID>" type: "msal" ...	MSAL Authentication in MATLAB Online Server
Lightweight Directory Access Protocol (LDAP)	identityProviders: - id: "<IdP ID>" type: "ldap" ...	LDAP Authentication in MATLAB Online Server
Security Assertion Markup Language (SAML)	identityProviders: - id: "<IdP ID>" type: "saml" ...	SAML Authentication in MATLAB Online Server

Configure Multiple Identity Providers

If you have multiple IdPs to configure, then in the identityProviders section, add sections for those IdPs. The first IdP you specify is the default one that MATLAB Online Server uses to authenticate users. To authenticate users with a nondefault IdP, include an IdPId=id query parameter in the MATLAB Online URL you give to users. The value of id is the ID of the IdP.

For example, suppose your organization uses two IdPs that follow the OAuth 2.0 and OIDC protocol, one provided by Okta^® and one provided by Ping Identity^®.

identityProviders:
  - id: "okta"
    type: "oauth"
    ...
  - id: "pingid"
    type: "oauth"
    ...

To authenticate users with the Okta IdP, provide those users with the following MATLAB Online URL:

https://<domain-base>/matlabonline

<domain-base> is the value of the DOMAIN_BASE property in your install.config file.
Because the Okta IdP is listed first in the identityProviders section, you do not need to include the idpId=okta query parameter in the URL.

To authenticate users with the Ping Identity IdP, provide those users with the following URL:

https://<domain-base>/matlabonline?idpId=pingid

Because the Ping Identity IdP is not first in the identityProviders section, you must include the idpId=pingid query parameter in the URL.