Enable SSO Access to AWS Resources Using Delegation

Since R2023b

In MATLAB^® Online Server™, end users can run MATLAB functions to access data stored remotely in AWS^® resources such as Amazon S3™. These functions require end users to acquire their AWS credentials in advance. Otherwise, MATLAB returns an error. You can provide MATLAB Online Server with delegated access to AWS. With AWS delegation enabled, the server acquires credentials for end users as soon as they sign in to MATLAB Online™ using their single sign-on (SSO) credentials, giving them immediate access to their remote resources.

Prerequisites

You have an AWS account with permission to manage Identity and Access Management (IAM) roles. These permissions enable you to delegate AWS resource access to MATLAB Online Server. For more details, see IAM roles (AWS).
You are using a Security Assertion Markup Language (SAML) identity provider to authenticate MATLAB Online users. For details on authenticating MATLAB Online users using SAML, see SAML Authentication in MATLAB Online Server.
Your SAML identity provider uses identity federation and has roles with privileged access to the AssumeRoleWithSAML API.
- Identity federation is the process of establishing a trust relationship between the identity provider and AWS, enabling the provider to verify user identities and transmit authentication details to AWS. For more details, see About SAML 2.0-based federation (AWS).
- The AssumeRoleWithSAML API provided by AWS allows the identity provider to assume an IAM role on behalf of the user from within AWS, granting them temporary security credentials for accessing AWS resources.

Configure Authentication Service to Support AWS Delegation

Enable AWS delegation in the MATLAB Online Server authentication service by setting the appropriate values in the authnz.yaml file. The file is located at this path.

<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, within the saml identity provider, add a delegation section with this structure.

identityProviders:
  - id: "saml"
    type: "saml"
    # Standard SAML Configuration
    ...

    delegation:
      aws:
        iam:
          failureMode: "halt"
          sessionProperties:
            region: "us-east-1"
            sessionDuration: 3600

For details on the standard SAML configuration, see SAML Authentication in MATLAB Online Server.

In the delegation section, configure these fields.

Field Required or Optional Description

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 end user to log in to MATLAB Online. `"halt"` — Process the failed delegation request as an error and do not log the end user in to MATLAB Online.
`region`	Required	Region of the AWS resources being accessed. Example: `"us-east-1"`
`sessionDuration`	Optional	Amount of time, in seconds, that users have access to AWS resources. If you enable delegation, when an end user logs into MATLAB Online, AWS grants the user access to AWS resources for a fixed session duration. When this session expires, to access AWS resources again, the user must sign out and sign back in to MATLAB Online. MATLAB Online Server sets the session duration based on these rules. If specified, the server sets the duration to the `sessionDuration` value set in `authnz.yaml`. If `sessionDuration` is not specified, the server sets the duration to this session duration field in the identity provider configuration: `https://aws.amazon.com/SAML/Attributes/SessionDuration` If the session duration of the identify provider is not configured, the server sets the duration to the default value specified by the security token service that AWS uses to access the resource. `sessionDuration` must not exceed the `MaxSessionDuration` value set in your IAM role in AWS. For more details, see Update `MaxSessionDuration` (AWS).

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 end user to log in to MATLAB Online.
"halt" — Process the failed delegation request as an error and do not log the end user in to MATLAB Online.

region Required Region of the AWS resources being accessed. Example: "us-east-1"

sessionDuration

Optional

Amount of time, in seconds, that users have access to AWS resources.

If you enable delegation, when an end user logs into MATLAB Online, AWS grants the user access to AWS resources for a fixed session duration. When this session expires, to access AWS resources again, the user must sign out and sign back in to MATLAB Online.

MATLAB Online Server sets the session duration based on these rules.

If specified, the server sets the duration to the sessionDuration value set in authnz.yaml.
If sessionDuration is not specified, the server sets the duration to this session duration field in the identity provider configuration: https://aws.amazon.com/SAML/Attributes/SessionDuration
If the session duration of the identify provider is not configured, the server sets the duration to the default value specified by the security token service that AWS uses to access the resource.

sessionDuration must not exceed the MaxSessionDuration value set in your IAM role in AWS. For more details, see Update MaxSessionDuration (AWS).

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>
```

Enable AWS Support on Server

Enable AWS support across all services by setting the appropriate values in the all.yaml file. The file is located at this path.

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

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

global:
  tls:
    enabled: true
 
  delegation:
    providers:
      - type: "awsiam"
        enabled: true
    secretFile:
      mountPath: "/etc/credentials-secret-volume/"
      name: "credentials-secret"

Configure these fields.

Field Required or Optional Description

Field	Required or Optional	Description
`providers`	Required	Delegation provider. To enable AWS delegation, `type` must be `"awsiam"` and `enabled` must be `true`.
`secretFile`	Optional	Full path to the secret file used for securely transmitting AWS credentials within the MATLAB Online Server cluster. `mountPath` specifies the location to which you deployed the secret. The default mount path is `"/etc/credentials-secret-volume"`. `name` is the name of the secret file, as determined by the name field of `credentials-secret.yaml`. The default name is `credentials-secret`, as shown in the `name` field specified in the Deploy Kubernetes Secret for User Credentials step. If you do not change the default values, then you can omit the `secretFile` section.

providers

Required

Delegation provider. To enable AWS delegation, type must be "awsiam" and enabled must be true.

secretFile

Optional

Full path to the secret file used for securely transmitting AWS credentials within the MATLAB Online Server cluster.

mountPath specifies the location to which you deployed the secret. The default mount path is "/etc/credentials-secret-volume".
name is the name of the secret file, as determined by the name field of credentials-secret.yaml. The default name is credentials-secret, as shown in the name field specified in the Deploy Kubernetes Secret for User Credentials step.

If you do not change the default values, then you can omit the secretFile section.

Deploy Changes to Server

To apply your changes, undeploy and redeploy the server.

./mosadm undeploy
./mosadm deploy

These changes take effect for each user the next time they sign in to MATLAB Online with their single sign-on credentials.

For an example of how end users can access their remote data, see Work with Remote Data. When delegation is enabled, end users do not have to follow the instructions on setting up access and setting environment variables for their credentials.