Enable Access to Google Cloud Platform Storage 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™, giving them immediate access to their remote data.

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/namespace/authnz.yaml

server_root is the root folder of your MATLAB Online Server installation.
cluster is the name of your Kubernetes^® cluster.
namespace is the Kubernetes namespace you used to deploy MATLAB Online Server.

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 provide users with delegated access to remote data, MATLAB Online Server must transmit 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. If you already deployed a Kubernetes secret object for user credentials to the cluster, skip this step.

Generate a random 64-bit-encoded string that the cluster can use to encrypt the data. For example, this Linux^® bash script generates a random string of alphanumeric characters, wrapped in lines of 32 characters each, and encodes this string using base-64 encoding.
#!/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. Then, set the credentials-secret field to the value of the base-64-encoded string generated earlier. 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 your-namespace with your MATLAB Online Server namespace.
```
kubectl apply -f credentials-secret.yaml --namespace your-namespace
```

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/namespace/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.