Role-Based Access

Note

Role-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_app_roles.json` File

Enabling role-based access on the server lets you decide which users can author apps and which ones can use them.

MATLAB Web App Server supports two roles for role-based access: Author and User.

An Author can add, delete, and run web apps from MATLAB Web App Server. An Author sees a Manage Apps button on the server home page.
A User can only run web apps from the MATLAB Web App Server home page. A User sees a Diagnostics button on the server home page.

You can use role-based access along with policy-based access to finely determine who can run apps on the server and who can modify them. For details, see Policy-Based Access.

To enable role-based access:

Check if SSL is enabled. For more information, see Enable SSL.
Check if authentication is enabled. For more information, see Authentication.

Create a file named webapps_app_roles.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_app_roles.json is:

{
  "version": "1.0.0",
  "appRoles": [
    {
      "id": "User",
      "description": <Text describing the User role>,   
      "users":  { <Attribute name and values to identify end-users assigned to User role> },       
      "groups": { <Attribute name and values to identify groups assigned to User role> }
    },
    {
      "id": "Author",
      "description": <Text describing the Author role>, 
      "users":  { <Attribute name and values to identify end-users assigned to Author role> },
      "groups": { <Attribute name and values to identify groups assigned to Author role> }
    }
  ]
}

version: Specify the version of the JSON schema. The default value for R2024a is: 1.0.0.
id: Specify the role name. You can specify either User or Author. Only these two roles are supported.
description: Specify a description for each role. For example:
```
"description" : "An Author can upload, delete, and execute web apps."
```
users: Specify an attribute that uniquely identifies the set of authenticated end users who can assume the role of an Author or a User.
The attribute names depend on the type of authentication you are using.
For example, if you are using LDAP for authentication, you can fill in the JSON schema as follows:
```
"users":{ "email": ["bishop@example.com", "queen@example.com"] }
```
In the above schema, once an end-user is authenticated, MATLAB Web App Server checks if the authenticated user has email as an attribute, and checks to see if the attribute value (email address in this case) is listed in the schema. When both checks succeed, the end-user will be assigned a role.
groups: Specify an attribute name and corresponding values that uniquely identify the group of authenticated end users who can assume the role of an Author or a User.
The attribute names depend on the type of authentication you are using. Using groups lets you assign entire sets of end-users a role at once.
For example, if you are using LDAP for authentication, you can fill in the JSON schema as follows:
```
"groups": { "memberOf": [ "CN=Marketing,OU=Mail,DC=ldap,DC=example,DC=com",
                                 "CN=Development,OU=Mail,DC=ldap,DC=example,DC=com"] }
```
In the above schema, once an end-user is authenticated, MATLAB Web App Server checks if the authenticated user has memberOf as an attribute, and checks to see if the attribute's values are listed in the schema. When both checks succeed, the end-user will be assigned a role.
Attributes specified in the schema need to be collective or group attributes.

Tip

You do not need to specify both users and groups in the schema for each role unless that is the only way to obtain a unique set of end users.
If you use an attribute in the users field in the User role to identify a set of users, you need use the same attribute in the users field in the Author role to identify a set of users. The same condition applies to groups as well.

MATLAB Web App Server first checks if an authenticated user can assume the role of an Author before checking the User role. If checks against both roles fails, the end-user is denied access to the server.

Example `webapps_app_roles.json` File for LDAP Authentication

{
    "version": "1.0.0",
    "appRoles": [
        {
            "id": "User",
            "description": "A User can only execute web apps.",
            "groups": {
                "memberOf": [
                    "CN=Marketing,OU=Mail,DC=ldap,DC=example,DC=com",
                    "CN=Development,OU=Mail,DC=ldap,DC=example,DC=com"
                ]
            }
        },
        {
            "id": "Author",
            "description": "An Author can upload, delete, and execute web apps.",
            "users": { "email": [
                    "bishop@example.com",
                    "queen@example.com"
                ]
            }
        }
    ]
}

Example `webapps_app_roles.json` File for Azure AD Authentication

{
    "version": "1.0.0",
    "appRoles": [
        {
            "id": "User",
            "description": "A User can only execute web apps.",
            "groups": {
                "groups": [
                    "1a23456-ab2c-4444-a123-12345b3a81af",
                    "2b3456cd-e8ed-4fcf-ac55-6b79b0781eed "
                ]
            }
        },
        {
            "id": "Author",
            "description": "An Author can upload, delete, and execute web apps.",
            "users": { "email": [
                    "bishop@example.com",
                    "queen@example.com"
                ]
            }
        }
    ]
}

Caution

The JSON schema syntax for webapps_app_roles.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.