Application Access Control

MATLAB^® Production Server™ integrates with OAuth2 providers such as Azure^® Active Directory (Azure AD) and PingFederate^®, and uses JSON Web Tokens (JWTs) to restrict user access to applications or archives deployed to the server. Application access control is available only for clients that use the MATLAB Production Server RESTful API for MATLAB Function Execution to communicate with the server. Clients must send an access token in the HTTP authorization header when they make a request to the server. The format for this header is Authorization:Bearer <access token>. To set up access control for an on-premises server instance, you must define an access control configuration file and an access control policy file, and set the access-control-provider property to OAuth2 in the main_config server configuration file.

Access Control Configuration File

To help verify the identity of each user that sends requests to an on-premises server instance, the server administrator must define an access control configuration file in JSON format. The server uses the parameters in the access control configuration file to validate the JWT that a client request contains. The default path and name for the configuration file is ./config/jwt_idp.json. You can change the path and name of the configuration file by setting the access-control-config property. If you change the path, name, or contents of the configuration file, you must restart the server for the changes to take effect.

The access control configuration file contains the following parameters:

Parameter	Required or Optional	Description
version	Required	Version number of the configuration file schema. The version number is a JSON string that has the format `major#`.`minor#`.`patch#`, where each number is a nonnegative integer. Set `version` to `1.0.0`.
jwtIssuer	Required	JWT issuer metadata of the identity provider. Specify the metadata as a JSON string. The metadata string must match the `iss` claim in the JWT. For example, for Azure AD, set the `jwtIssuer` to `https://sts.windows.net/Azure AD tenant id/`.
appId	Required	Intended recipient of the JWT. Specify the recipient as a JSON string. The recipient helps in validating the `aud` claim in the JWT. For example, for Azure AD, the `appId` is the application ID of the registered MATLAB Production Server server app. For information on registering apps on Azure, see Quickstart: Register an application with the Microsoft identity platform.
jwksUri	Required	URI to retrieve the JSON Web Key Set (JWKS). Specify the URI as a JSON string. The JWKS stores public keys that are used to verify the JWT. For example, for Azure AD, set the `jwksUri` to `https://login.microsoftonline.com/common/discovery/keys`.
jwksStrictSSL	Optional	Flag to verify the peer certificate of the server specified by jwksUri during HTTPS communication with the JWKS server. Specify the choice as a JSON boolean. The default selection is `true`. Specifying `true` verifies the peer certificate. If the JWKS server uses a self-signed certificate, set this value to `false`.
jwksTimeOut	Optional	Maximum time allowed for a request to retrieve the JWKS. Specify the time as nonnegative JSON integer. The default timeout value is 120 seconds.
userAttributeName	Optional	JWT claim name that uniquely identifies a user. Specify the claim name as a JSON string. The default value for `userAttributeName` is `sub`.
groupAttributeName	Optional	JWT claim name that lists the groups that a user belongs to. Specify the claim name as a JSON string. The default value for `groupAttributeName` is `groups`.

You can specify the userAttributeName, the groupAttributeName, or both. If you want to configure access control for specific users, specify the userAttributeName. If you want to configure access control for groups of users, specify the groupAttributeName.

An example of a configuration file for which Azure AD is the identity provider follows.

{
  "version": "1.0.0",
  "jwtIssuer": "https://sts.windows.net/54ss4lk1-8428-7256-5fvh-d5785gfhkjh6/",
  "appId": "j21n12bg-3758-3r78-v25j-35yj4c47vhmt",
  "jwksUri": "https://login.microsoftonline.com/common/discovery/keys",
  "jwksStrictSSL": true,
  "jwksTimeOut": 120,
  "userAttributeName": "sub",
  "groupAttributeName": "groups" 
}

Access Control Policy File

To set up application access control for MATLAB Production Server, the server administrator must define an access control policy file in JSON format. The default path and name for the policy file is ./config/ac_policy.json. You can change the default values by setting the access-control-policy property.

When the server starts, it tries to read the policy file. If the file does not exist or contains errors, the server does not start, and writes an error message to the main.log file present in the directory that the log-root property specifies.

After the server starts, it scans the policy file every five seconds, if application access control is enabled. If the policy file is absent or contains errors, the server continues to run, but denies all requests and writes an error message to the main.log file.

The policy file has a single JSON object that defines the schema version and a policy block. The policy block consists of a list of policies. Each policy contains a rule block that defines a set of rules for a policy. The rule block consists of a subject block, a resource block, and an action block.

Outline of a policy file with a policy block, rule block, subject block, resource block, and action block.

The schema version is a JSON string in the format major#.minor#.patch#, where each number is a nonnegative integer. Set the schema version to 1.0.0.

Policy Block

The policy block contains a list of policies required for application access control. Currently, the policy file supports specifying only a single policy.

"policy" : [
   {
     "id": "policy_id",
     "description": "policy_description",
     <rule_block>
   }
]

Each policy requires an id value. policy_id is a JSON string and must be unique for each policy. Any leading or trailing white spaces are removed.

The description is optional for a policy.

Rule Block

The rule block contains a list of rule objects.

"rule":[
  {  
    "id": "rule_id",
    "description": "rule_description",
    <subject_block>,
    <resource_block>,
    <action_block>
  }
]

The rule block supports multiple rules, for example, "rule": [<rule>, <rule>, ...].

Each rule requires an id value. rule_id is a JSON string and must be unique for each rule. Any leading or trailing white spaces are removed.

The description is optional for a rule.

Subject Block

The subject block of a rule defines who can access the resources. You can control access for a list of users, user groups, or both.

"subject" : {"groups": ["group_id", "group_id", ...],
             "users": ["user_id", "user_id", ...]}

Use the users attribute to specify a list of users identified by their unique user_id values. Use the groups attribute to specify user groups identified by their unique group_id values. You can specify the users attribute, groups attribute, or both.

Resource Block

The resource block of a rule specifies the resource that a server request wants to access. Currently, the only resource that a server request can access is a deployable archive (CTF file). You can specify multiple deployable archives.

"resource" : {"ctf": ["archive_name", "archive_name", ...]}

You can use the wildcard character * to specify multiple archives. For example, if you want to access all archives whose names start or end with test, specify archive_name as test* or *test, respectively. Use * as the archive_name to access all archives deployed to the server.

Action Block

The action block of a rule describes the action that a server request wants to perform on the resource. Currently, execute is the only supported action.

"action" : ["execute"]

Example of JSON Policy File

The following example defines an access control policy with three rules.

Users aaa@xyz.com and bbb@xyz.com can execute the deployable archive magic.
All users that belong to groups with IDs aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa and bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb, as well as user ccc@xyz.com, can execute the deployable archives monteCarlo and fastFourier.
All users that belong to quality engineering group cccccccc-cccc-cccc-cccc-cccccccccccc can execute all deployable archives that have names that start with test.

The server denies access for all other requests.

{
  "version": "1.0.0",
  "policy" : [
    {
      "id": "policy1",
      "description": "Access Control policy for XYZ Corp.",
      "rule": [
        {
          "id": "rule1",
          "description": "Users aaa@xyz.com and bbb@xyz.com can execute deployable archive magic",
          "subject": { "users": ["aaa@xyz.com", "bbb@xyz.com"] },
          "resource": { "ctf": ["magic"] },
          "action": ["execute"]
        },
        {
          "id": "rule2",
          "description": "Group A and B and user ccc@xyz.com can execute deployable archives monteCarlo and fastFourier",
          "subject": { "groups": ["aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"],
                        "users": ["ccc@xyz.com"]  },
          "resource": { "ctf": ["monteCarlo", "fastFourier"] },
          "action": ["execute"]
        },
        {
          "id": "rule3",
          "description": "QE group C can execute any deployable archive whose name starts with test",
          "subject": { "groups": ["cccccccc-cccc-cccc-cccc-cccccccccccc"] },
          "resource": { "ctf": ["test*"] },
          "action": ["execute"] 
        }
      ]
    }
  ]
}

External Websites

Microsoft Graph API