SAML Authentication in MATLAB Online Server

In MATLAB^® Online Server™, you can configure authentication using a Security Assertion Markup Language (SAML) identity provider (IdP). For details about SAML, see the OASIS SAML Wiki.

Prerequisites

MATLAB Online Server is installed. See Installation.
Your organization's IdP follows the SAML protocol.
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.

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: "saml"
#   authRequestBinding: "POST"
#   assertionConsumerPath: "/authnz/saml/code"
    corsAllowOriginDomain: "<fully qualified domain name of server>"
    relyingPartyId: "<server hostname>"
#   supportIdPInitiated: false
#   idpIssuer: "<IdP issuer name>" # required if supportIdPInitiated is true
#   idpMetadataUrl: "<https://IdP/metadata>" # Required if idpMetadataXml is not specified
#   idpMetadataXml: |                        # Required if idpMetadataUrl is not specified
#       <xml content/>        
#   delegation:
#     aws:
#       <AWS 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`	`"saml"`	Required	Type of IdP. To configure local user accounts, you must set `type` to `"saml"`.
`authRequestBinding`	`"POST"`	Optional	Binding method for sending authentication requests to the identity provider, specified as `"POST"` (HTTP POST) or `"Redirect"` (HTTP Redirect). The HTTP Redirect method sends request data as query parameters in the URL, whereas the HTTP POST method sends data more securely in the request body.
`assertionConsumerPath`	`"/authnz/saml/code"`	Optional	Assertion consumer service (ACS) endpoint where MATLAB Online Server sends the SSO tokens. ACS is applicable to all SAML versions and both the IdP-initiated and service-provider-initiated SSO profiles.
`corsAllowOriginDomain`	`""`	Required	Fully qualified domain name of the server that communicates with MATLAB Online Server. Example: `samlintegrationhost.yourcompanydomain.com`.
`relyingPartyId`	`""`	Required	Hostname of the server that integrates with the SAML identity provider. This value is typically the hostname of the DNS entry for your MATLAB Online Server Kubernetes cluster. However, depending on the integration product or service being used to expose the identity provider via the SAML system, this value can also be an arbitrary identifier.
`supportIdpInitiated`	`false`	Optional	Set this field to `true` to enable the use of an IdP-initiated workflow for accessing applications hosted on MATLAB Online Server. In an IdP-initiated workflow, users sign in directly to their organization's IdP using their SSO credentials. The IdP then authenticates users and redirects them to their organization's application portal, from which they can select the applications they have access to (for example, MATLAB Online™). To enable IdP-initiated workflows, follows these steps: On your IdP server, set the default relay state parameter. This parameter specifies the application (for example, MATLAB Online) that the IdP redirects users to after they select the application from their organization's application portal. The exact name of the default relay state parameter varies by IdP vendor, for example, "IDP Initiated SSO Relay State" or "Default Relay State". Specify the parameter using this format: `idpIssuerName\|idpRedirectUrl` `idpIssuerName` is the name you want to use to identify the IdP issuer on the network. You can specify `idpIssuerName` as an arbitrary string or include IdP issuer information, such as the issuer URL, in this name. This string does not have to be unique. You can reuse an IdP issuer name specified in other applications. `idpRedirectUrl` is the endpoint of the application that the IdP redirects users to. Examples: http://www.okta.com/PB21eR9DUk\|https://mos.example.com/matlabonline mos-client-idp\|https://mos.example.com/matlabonline In MATLAB Online Server, in the `authnz.yaml` file: Set `supportIdpInitiated` to `true`. Set `idPIssuer` to the value of the `idpIssuerName` part of the default relay state parameter. Omit this field or set it to `false` to initiate authentication of a user's SSO credentials through the service provider (SP), which in this case is MATLAB Online Server. In an SP-initiated workflow, users sign in directly to MATLAB Online, and the server connects to the identity provider to authenticate the credentials of the user.
`idpIssuer`	`""`	Optional (Required if `supportIdpInitiated` is `true`)	IdP issuer used to authenticate users in IdP-initiated workflows. This field uniquely identifies the IdP issuer on the network, enabling MATLAB Online Server to connect to it. Set `idpIssuer` to the `idpIssuerName` part of the default relay state parameter on the IdP server. For details, see the `supportIdpInitiated` field. Examples: idpIssuer: "http://www.okta.com/PBtz21eR9DUkTAz8cQsD" idpIssuer: "mos-client-idp" This field applies only when `supportIdpInitiated` is set to `true`.
`idpMetadataUrl`	`""`	Optional (You must specify either `idpMetadataUrl` or `idpMetadataXml`, but not both)	URL to the required SAML metadata for SP-initiated or IdP-initiated profiles.
`idpMetadataXml`	`""`	Optional (You must specify either `idpMetadataUrl` or `idpMetadataXml`, but not both)	Block of XML that the SAML IdP exports. You can paste the exported XML into this field, but the field must be properly formatted YAML. Otherwise, `mosadm` is unable to deploy the `authnz` details. Depending on the integration product or service that you are using to expose the IdP through SAML, the XML might contain newline characters. Delete those newline characters before pasting the XML into `authnz.yaml`.
`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. SAML supports delegation for this cloud platform service: AWS^® delegation: aws: <AWS delegation configuration fields> For details on configuring AWS 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

identityProviders:
  - id: "saml"
    type: "saml"
    assertionConsumerPath: "/service/assertionConsumer"
    corsAllowOriginDomain: "samlintegrationhost.yourcompanydomain.com"
    relyingPartyId: "matlab.domain.com"
    supportIdpInitiated: true
    idpIssuer: "idp-issuer-name"
    idpMetadataUrl: "https://<IdP metadata>"
    subjectAttributeMapping:
      displayName: "name"
      subjectId: "myNameId"
      groups: "groups"
      extra: 
        email: "email"
        uid: "uidNumber"
        gid: "gidNumber"

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

OASIS SAML Wiki