Enable SSO Access to Google Cloud Platform Resources Using Delegation

Since R2024a

In MATLAB^® Online Server™, end users can run MATLAB functions in the MATLAB Interfaces for Google Cloud Platform support package to access data stored remotely in Google Cloud Platform™ resources such as Google Cloud Storage. These functions require end users to acquire their GCP credentials in advance. Otherwise, MATLAB returns an error. You can provide MATLAB Online Server with delegated access to GCP. With GCP 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 are using an OpenID Connect (OIDC) identity provider (IdP) to authenticate MATLAB Online Server users. You can configure this IdP on the server using either the standard OAuth 2.0 and OIDC protocol or the MSAL implementation of this protocol. For details on configuring authentication in MATLAB Online Server using these protocols, see:
- OAuth 2.0 and OIDC Authentication in MATLAB Online Server
- MSAL Authentication in MATLAB Online Server
The GCP application being accessed has workload identity federation enabled and is configured to work with your MATLAB Online Server IdP. Workload identity federation is a keyless authentication method that enables applications to access data from Google^® applications remotely. For more details, see Workload identity federation (Google).

Configure GCP in MATLAB

MathWorks^® provides multiple application programmer interfaces for working with GCP services. To enable users to access these interfaces, build them into your MATLAB resource pool.

Open the MATLAB Interfaces for Google Cloud Platform support package repository on GitHub^®.
Install this support package in your MATLAB support package root folder by following the instructions in the README.md file. If you do not have a support package root folder, create one by following the instructions in the "Change Support Package Root" section of Install Support Packages for MATLAB on MATLAB Online Server.
Build the executable into the MATLAB resource pool by rebuilding the MATLAB image. Follow the instructions in the "Build MATLAB Image" section of Install Support Packages for MATLAB on MATLAB Online Server.

Configure Authentication Service to Support GCP Delegation

Enable GCP 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 id section for your IdP, add a delegation section with this structure. The supported identity providers are MSAL (see MSAL Authentication in MATLAB Online Server) and OAuth 2.0 and OIDC (see OAuth 2.0 and OIDC Authentication in MATLAB Online Server).

MSAL — Sample Delegation Configuration

identityProviders:
  - id: "msal"
    type: "msal"

    # standard MSAL configuration
    ...

    delegation:
      gcp:
        workloadIdentityFederation:
          groupBasedAccessControl: true
          configurations:
            identityProvider: "<IdP name in workload identity federation pool>"
            projects:
            - projectId: "<GCP project ID>"
              name: "<GCP project name>"
              pools:
                - poolName: "<GCP pool name>"
                  serviceAccounts:
                  - accountName: "<service account name>"
                    allowedGroups: ["<groups>"]

OAuth 2.0 and OIDC — Sample Delegation Configuration

identityProviders:
  - id: "oauth"
    type: "oauth"
    oidc:
      enabled: true

    # standard OAuth 2.0 and OIDC configuration
    ...

    delegation:
      gcp:
        workloadIdentityFederation:
          groupBasedAccessControl: true
          configurations:
            identityProvider: "<IdP name in workload identity federation pool>"
            projects:
            - projectId: "<GCP project ID>"
              name: "<GCP project name>"
              pools:
                - poolName: "<GCP pool name>"
                  serviceAccounts:
                  - accountName: "<service account name>"
                    allowedGroups: ["<groups>"]

These YAML fields configure access to resources within a GCP project (projectID and name fields). The authentication process is as follows:

The MATLAB Online Server identity provider (identityProvider) authenticates the user and verifies that the user can be trusted.
The GCP workload identity pool (poolName) authenticates the identity provider and verifies that it can be trusted. The pool also specifies the permissions that the identity provider has for accessing resources.
The service account (accountName) authenticates the user groups (allowedGroups) allowed to access the resource. If the user belongs to an allowed group, the service account grants the user access to the resource.

Note

You can configure access to only one project, pool, and service account. The server recognizes only the first project, the first pool in that project, and the first service account in that pool. Additional specified projects, pools, and service accounts are ignored.

The table describes the fields you can configure.

Field	Default	Required or Optional	Description
`groupBasedAccessControl`	`false`	Optional	Set this field to `true` to enable the `allowedGroups` field, which specifies the user groups that can access GCP resources. If you omit `groupBasedAccessControl` or specify it as `false`, then the `allowedGroups` field is ignored and all groups listed in your identity provider can access GCP resources.
`identityProvider`	`""`	Required	Name of the IdP that authenticates MATLAB Online Server users. Specify the name exactly as it appears in the workload identity federation pool of your GCP application. Example: `"myIdP"`
`projectId`	`""`	Required	ID of the GCP project. Specify the project ID exactly as it appears in your GCP application. Example: `"123456"`
`name`	`""`	Required	Name of the GCP project. Specify the project name exactly as it appears in your GCP application. Example: `"myProjectName"`
`poolName`	`""`	Required	Name of the workload identity federation pool. Specify the pool name exactly as it appears in your GCP application. Example: `"myWIFPool"`
`accountName`	`""`	Required	Name of the service account. Specify the service account exactly as it appears in your GCP application. Example: `"myServiceAccount"`
`allowedGroups`	`[]` (allow all groups)	Optional	List of groups that can access GCP resources. Specify the group names exactly as they appear in your identity provider application. Example: `["group1","group2"]`

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 GCP Support on Server

Enable GCP 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: "gcpworkloadidentity"
        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 GCP delegation, you must specify `type` as `"gcpworkloadidentity"` and `enabled` as `true`.
`secretFile`	Optional	Full path to the secret file used for securely transmitting user 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 GCP delegation, you must specify type as "gcpworkloadidentity" and enabled as true.

secretFile

Optional

Full path to the secret file used for securely transmitting user 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.

If all.yaml already contains a delegation section, then add a new entry for GCP delegation to the providers list.

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. Each user's MATLAB session now includes an access token, issued by Google, that grants the user access to data stored in their GCP project. The duration of this token is limited and set by Google. For details, see Token Lifetime documentation (Google). When the token expires, to access their GCP data again, the user must sign out of MATLAB Online and sign back in again.

For details on the functions that users can specify to access their remote data, see the README.md file in MathWorks Google Cloud Platform on GitHub.