Policy-Based Access

Note

Policy-based access 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.

Prerequisites

Enable SSL on the server. For more information, see Enable SSL.
Enable authentication on the server. For more information, see Authentication.

Create `webapps_acc_ctl.json` File

Enabling policy-based access on the server lets you create attribute-based rules that permit authenticated subjects to access web apps on the server.

To enable policy-based access:

Check if SSL is enabled. For more information, see Enable SSL.
Check if authentication is enabled and verify that either or both the userAttributeName and groupAttributeName values have been specified in the webapps_authn.json file. For details, see Authentication.
Check if folders exist within the apps root folder on the server. While folders are not necessary to enable policy-based access, having folders lets you organize web apps and specify them as a resource that can be accessed. For details, see Create Folders to Organize Web Apps.

Create a file named webapps_acc_ctl.json and place it in the webapps_private 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`

The JSON schema for webapps_acc_ctl.json is:

{
  "version": "<major>.<minor>.<patch>",
  "policy": [
    {
      "id": "<policy_id>",
      "description": "<policy_description>",
      "rule": [
        {
          "id": "<rule_id>",
          "description": "<rule_description>",
          "subject": { "<attribute_name_of_auth_subject>": [ "<attribute_value_of_auth_subject>" ] },
          "resource": { "<app OR folder>": [ "<app_name OR folder_name>" ] },
          "action": [ "<action_type>" ]
        },
        {
          "id": "<rule_id>",
          "description": "<rule_description>",
          "subject": { "<attribute_name_of_auth_subject>": [ "<attribute_value_of_auth_subject>" ] },
          "resource": { "<app OR folder>": [ "<app_name OR folder_name>" ] },
          "action": [ "<action_type>" ]
        }
      ]
    }
  ]
}

version: Specify the version of the JSON schema. The default value for R2024a is 1.0.0.
policy: The policy block contains a list of policies required for policy-based access. Only a single policy can be specified in a policy file.
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 apps."
```
rule: The rule block contains a list of rule objects. Multiple rules can exist in a rule block. An ID is required for each rule and <rule_id> must be unique 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 the Hercules group can run the BloodPressure app."
```
subject: Specify an attribute name-value pair of an authenticated subject that can access resources.
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.
resource: Specify the type and name of the resources that can be accessed. Only resources of type app or folder are supported. If you do not specify a resource, then an authenticated subject will not have access to the app or folder even if it exists on the server. For information on how to create folders, see Create Folders to Organize Web Apps.
For example, to specify access to an app at the root level:
```
"resource": { "app": ["BloodPressure"] }
```
For example, to specify access to an app in a particular folder:
```
"resource": { "app": ["MagicFolder/CardTricks"] }
```
For example, to specify access to all apps in a particular folder:
```
"resource": { "folder": ["MagicFolder"] }
```
For example, to specify access to all apps in the root folder:
```
"resource": { "folder": ["/"] }
```
action: Specify the type of action the authenticated subject can perform. If the resource type is app, the action supported is execute, which lets the subject run a web app. If the resource type is folder, the actions supported are execute and modify. The execute action, in this case, lets the subject run all the web apps in a specified folder. The modify action lets the subject upload or delete a web app to or from a folder if the subject is assigned the role of Author in the webapps_app_roles.json role-based access file. A subject assigned the role of User in the webapps_app_roles.json role-based access file cannot upload or delete a web app to or from a folder even if they are assigned a modify action. For example:
```
"action": ["execute", "modify"]
```
For details, see Role-Based Access.

Example `webapps_acc_ctl.json` File for LDAP Authentication

{
  "version": "1.0.0",
  "policy" : [
    {
      "id": "policy1001",
      "description": "Web Apps Access Control Policy",
      "rule": [
        {
          "id": "rule101",
          "description": "Sales group can run the BloodPressure app.",
          "subject": { "memberOf": ["cn=Sales,ou=sales,ou=groups,dc=example,dc=com"] },
          "resource": { "app": ["BloodPressure"] },
          "action": ["execute"]
        },
        {
          "id": "rule102",
          "description": "Specified subjects can run the CardTricks app in the MagicDir folder.",
          "subject": { "uid": ["erooney"]  },
          "resource": { "app": ["MagicDir/CardTricks"] },
          "action": ["execute"]
        },
        {
          "id": "rule103",
          "description": "Specified subjects can run all apps in the MagicDir folder and modify (upload or delete) apps in MagicDir folder.",
          "subject": { "uid": ["fbueller"]  },
          "resource": { "folder": ["MagicDir"] },
          "action": ["execute", "modify"]
        },
        {
          "id": "rule104",
          "description": "Specified subjects can run all apps under the DayOff folder.",
          "subject": { "uid": ["cfrye", "psloane"]  },
          "resource": { "folder": ["DayOff"] },
          "action": ["execute"]
        },
        {
          "id": "rule105",
          "description": "Specified subjects can run all apps in the apps root folder and modify (upload or delete) apps in the apps root folder.",
          "subject": { "uid": ["jbueller"]  },
          "resource": { "folder": ["/"] },
          "action": ["execute", "modify"]
        }
      ]
    }
  ]
}

Caution

The JSON schema syntax for webapps_acc_ctl.json is strictly enforced. Errors in the schema syntax may result in the server not starting, or you being denied access to the server when you try to log in.

Using Policy-Based Access with Authentication and Role-Based Access

Policy-Based Access with Authentication

If you use policy-based access, you must include the following properties in the appConfig block of the webapps_authn.json authentication file and set appropriate values:
- userAttributeName
- groupAttributeName
A failure to include and set values for these properties results in the server not starting. For details, see Authentication.

If you use policy-based access, and set values for userAttributeName and groupAttributeName in the webapps_authn.json authentication file, then the attributes specified for the subject property in the webapps_acc_ctl.json policy-based access file must match the values you set in the authentication file.

Authentication File (webapps_authn.json) Policy-Based Access File (webapps_acc_ctl.json)

Authentication File (webapps_authn.json)	Policy-Based Access File (webapps_acc_ctl.json)
`"userAttributeName": "<value>", "groupAttributeName": "<value>"`	`"subject": { "<attrib>": ["..."] } "subject": { "<attrib>": ["..."] }`

"userAttributeName": "<value>",
"groupAttributeName": "<value>"

"subject": { "<attrib>": ["..."] }
"subject": { "<attrib>": ["..."]  }

For example, if you set the following values in the webapps_authn.json authentication file:

"userAttributeName": "uid",
"groupAttributeName": "memberOf"

Then, the webapps_acc_ctl.json policy-based access file must use the same values:

"subject": { "uid": ["..."] }

"subject": { "memberOf": ["..."]  }

A mismatch of attributes in the JSON files results in the server not starting. For details, see Policy-Based Access.

Note

You can use policy-based access with authentication independent of role-based access. However, this type of access results in authenticated subjects being able to only execute web apps but not modify them.

Policy-Based and Role-Based Access with Authentication

If you use policy-based access and role-based access simultaneously, and set values for userAttributeName and/or groupAttributeName in the webapps_authn.json authentication file, then the attributes specified for the subject property in the webapps_acc_ctl.json policy-based access file and the attributes specified for the groups and users properties must match the values you set in the authentication file.

Authentication File (webapps_authn.json) Policy-Based Access File (webapps_acc_ctl.json) Role-Based Access File (webapps_app_roles.json)

Authentication File (`webapps_authn.json`)	Policy-Based Access File (`webapps_acc_ctl.json`)	Role-Based Access File (`webapps_app_roles.json`)
`"userAttributeName": "<value>", "groupAttributeName": "<value>"`	`"subject": { "<attrib>": ["..."] } "subject": { "<attrib>": ["..."] }`	`"users": { "<attrib>": ["..."] } "groups": { "<attrib>": ["..."] }`

"userAttributeName": "<value>",
"groupAttributeName": "<value>"

"subject": { "<attrib>": ["..."] }
"subject": { "<attrib>": ["..."]  }

"users": { "<attrib>": ["..."]  }
"groups": { "<attrib>": ["..."] }

For example, if you set the following values in the webapps_authn.json authentication file:

"userAttributeName": "uid",
"groupAttributeName": "memberOf"

Then, the webapps_app_roles.json role-based access file must use the same attributes:

"appRoles": [
		{
		  "id": "User",
		  "description": "User role info",
		  "groups": { "memberOf": ["..."] },
		  "users": { "uid": ["..."] }
		},
		{
		  "id": "Author",
		  "description": "Author role info",
		  "groups": { "memberOf": ["..."] },
		  "users": { "uid": ["..."] }
		}
	   ]

And, the webapps_acc_ctl.json policy-based access file must use the same values:

"subject": { "memberOf": ["..."]  }

"subject": { "uid": ["..."] }

A mismatch of values results in the server not starting. For details, see Role-Based Access.

Note

When you use policy-based access and role-based access with authentication, an authenticated subject must be assigned the role of Author in the webapps_app_roles.json role-based access file and have modify as an action in the webapps_acc_ctl.json policy-based access file in order for the subject to be able to modify web apps.