Control Secrets Access in MATLAB Web App Server

Since R2024a

You can avoid exposing sensitive information, such as passwords, in your application code by storing it as a secret. A secret can be any sensitive information that you would like to store securely in an encrypted form. Each secret consists of a name, value, and optional metadata. Retrieve secrets using the getSecret (MATLAB) function in a web app. For more information on using secrets in deployment, see Handle Sensitive Information in Deployed Applications.

You can store secrets on the MATLAB^® Web App Server™ in a secured vault. To add and manage secrets on MATLAB Web App Server, use one of the following options:

Manage secret keys at the command line using webapps-secrets.
If you're using the development version of MATLAB Web App Server, use the graphical interface to manage secrets. For details, see Configure the Development Version of MATLAB Web App Server in MATLAB Compiler (MATLAB Compiler).

Enabling policy-based secret access on the server lets you create attribute-based rules that permit authenticated subjects to access secrets stored in the server vault. Ensure that only the server admin has the key of the vault and access to the vault location.

Prerequisites

An instance of MATLAB Web App Server. For information, see Set Up MATLAB Web App Server.
To control access to secrets with user authentication, you must enable authentication on the server. For more information, see Authentication.
Authentication is supported in the standalone MATLAB Web App Server product and not the development version included in MATLAB Compiler™. For details, see MATLAB Web App Server Differences.

Control Access to Secrets

The secrets access control file lets you specify which authenticated users or groups can access secrets stored on the server.

If server authentication is enabled, then secret access control is enabled by default, and an authenticated user will have no access to any secrets unless specified with a policy. To enable authentication on the server, see Authentication.

To enable access control, create a file named webapps_secrets_acc_ctl.json and place it in the webapps_private folder, which is located within the config folder.

The webapps_private folder can be found in:

Operating System	Folder Location
Windows^®	`%ProgramData%\MathWorks\webapps\R2024a\config\webapps_private`
Linux^®	`/local/MathWorks/webapps/R2024a/config/webapps_private`
macOS	`/Library/Application Support/MathWorks/webapps/R2024a/config/webapps_private`

webapps_secrets_acc_ctl.json must use the following JSON schema.

{
    "version": <version_string>,
    "policy": [
      {
        "id": <id_string>,
        "description": <description_string>,
        "rule": [
            {
                "id": <rule_id_string>,
                "description": <rule_description_string>,
                "subject": { 
                    "uid": [<user_string>, <user_string>] 
                },
                "resource": { 
                    "secret": [<secret_key_string>, <secret_key_string>]
                },
                "action": <action_string>
            }
        ]     
    }
  ]
}

version: Specify the version of the JSON schema. Default value for R2024a is: 1.2.0.
id: Specify a policy ID for the policy. The policy ID must be a set of alphanumeric characters. Any leading or trailing white space is removed. For example:
```
"id" : "policy420"
```
description: Specify a description for the policy. For example:
```
"description" : "Company policy for accessing web app secrets."
```
id: Specify a unique rule ID for each rule. The rule ID must be a set of alphanumeric characters. Any leading or trailing white space is removed. For example:
```
"id" : "rule1"
```
description: Specify a description for each rule. For example:
```
"description": "Only user id 'mluser' can access secret 'app1.*'"
```
subject: Specify one or more attribute name-value pairs to grant an authenticated subject access to the specified secrets.
For example:
```
"subject": { "memberOf": ["CN=Middle,OU=middle,ou=groups,DC=school,DC=com"] }
```
```
"subject": { "groups": ["Sales"] }
```
```
"subject": { "uid": ["fbueller", "cfrye"]  }
```
If you are using an Azure^® Active directory and need to retrieve group IDs, see Using Azure Active Directory.
secret: Specify the names of one or more secrets that can be accessed by the specified subject.
For example:
```
"secret": ["mypassword"] 
```
Wildcards (*) are supported at the end of the secret name. For example, "myapp1.*".
action: Specify the type of action the specified subject can perform. The only action supported is read, which grants the subject read access to the secrets.
For details, see Role-Based Access.

Example `webapps_secrets_acc_ctl.json` File

{
    "version": "1.0.0",
    "policy": [
      {
        "id": "secretPolicyID01",
        "description": "Secret Access Policy for user access",
        "rule": [
            {
                "id": "rule101",
                "description": "Only allow user 'mluser' to access secret 'app1.*' ",
                "subject": { "uid": ["mluser"] },
                "resource": { 
                    "secret": ["app1.*"] 
                },
                "action": ["read"]
            },
            {
                "id": "rule102",
                "description": "Only allow 'mluser' to access 'myusername' and 'password_for_all' ",
                "subject": {"uid": ["mluser"]},
                "resource": { 
                    "secret": ["myusername","password_for_all"]
                },
                "action": ["read"]
            },
            {
                "id": "rule103",
                "description": "Allow admin group to access secrets 'username_for_admin','password_for_admin' ",
                "subject": { "group": ["admin"]    },
                "resource": {
                    "secret":["username_for_admin","password_for_admin"]   
                },
                "action": ["read"]
          }
        ]     
      }
  ]
}

Configure Secrets Scope of Access

A secrets configuration file lets you organize the hierarchy of secret keys stored on the server. For instance, you can limit the scope of a specific key name in order to use the same secret key name with different secret values for different users or web apps.

To configure the scope of your secrets, create a file named webapps_secrets_config.json and place it in the webapps_private folder.

webapps_secrets_config.json must use the following JSON schema.

{
    "version" : <version_string>
    "description" : <policy_description_string>
    “secretKeyMap” : [ 
        {
            "id" : <rule_id_string>,
            "description" : <rule_description_string>,
            "secretKey": [<secret_key_string>, <secret_key_string>, ...],
            "scope" : <scope_string>
        }
    ]
}

version: Specify the version of the JSON schema. Default value for R2024a is: 1.2.0.
description: Specify a description for the policy. For example:
```
"description" : "Company policy for accessing web app secrets."
```
secretKeyMap: The secret key map block contains a list of rule objects. Multiple rules can exist in the block. The rules apply in order, with the first rule having the highest priority. A unique ID is required for each rule.
id: Specify a unique rule ID for each rule. The rule ID must be a set of alphanumeric characters. Any leading or trailing white space is removed. For example:
```
"id" : "rule101"
```
description: Specify a description for each rule. For example:
```
"description": "Only user id 'mluser' can access secrets 'app1.*'"
```
secretKey: Specify the names of the secrets that can be accessed.
For example:
```
"secretKey": ["mypassword"] 
```
Wildcards (*) are supported at the end of the secret name. For example, "myapp1.*".
scope: Specify users, groups, or specific web apps to allow access to the designated secret. The scope can be any static string or a string with macros. The following macros are supported:
- $UserID—the log on session User ID
- $AppName—the web app name, which includes the CTF file name and folder name

Note

In order to use the $UserID macro, you must include userinfo.json in the config/webapps_private directory. For details, see Customize Web App Behavior Based on User.

Example `webapps_secrets_config.json` File

{
    "version": "1.2.0",
    "description": "Configure secret key mapping rules",
    "secretKeyMap": [
        {
            "id"          : "rule01",
            "description" : "Limit db_password only to app testapp1",
            "secretKey"   : "db_password",
            "scope"       : "testapp1"
        },     
        {
            "id"          : "rule02",
            "description" : "Ensure unique password per user for app testapp1",
            "secretKey"   : "testapp1.password",
            "scope"       : "$UserID"
        },
        {
            "id"          : "rule03",
            "description" : "Prevent secret name collision between multiple apps",
            "secretKey"   : "database_name",
            "scope"       : "$AppName"
        }
    ]
}