Customize Web App Behavior Based on User

Note

The ability to customize web app behavior based on the user 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 `userinfo.json` File

You can customize the behavior of a web app based on which user is logged in. To customize behavior:

Create a file named userinfo.json and place it in the webapps_private folder on the server.

The webapps_private folder is in:

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

While authoring your web app using App Designer in MATLAB, use the compiler.UserInfo (MATLAB Compiler) function in your app code to retrieve user-specific details from the userinfo.json file.

The JSON schema for userinfo.json is:

{
    "version": "<major>.<minor>.<patch>",
    "userInfo.doc": "Property values to be fetched during login from IdP",
    "userInfo": {
      "UserID": "<uid_or_upn>",
      "DisplayName": "<user_name_that_is_displayed>",
      "Groups": "<group_membership_of_user>",
      "<propertyName1>": "<value1>",
      "<propertyName2>": "<value2>",
      "<propertyName3>": "<value3>",
      ...      
    },
    "appAccess.doc": "Policy for allowing access to user properties within an app or group of apps",
    "appAccess": {
      "<appName>": ["<userInfo_propertyName>","<userInfo_propertyName>", ...],
      ...
      "*": "*"
    }
  }

version: Specify the version of the JSON schema. The default value for R2024b is 1.0.0.
userInfo.doc: Text describing the purpose of the userInfo block.
userInfo: The userInfo block contains a list of property names and values that help identify users. The property names UserID, DisplayName, and Groups are required in every userinfo.json file. Other property names and values can be included as necessary. Property names and values correspond to LDAP or OIDC attributes. For example, if you want to use an email address as part of a user's information, you can specify Email as a property name and attribute value for the EmailAddress as the property value.
UserID: Specify the LDAP or OIDC attribute type that corresponds to a user's ID as a property value. UserID is a required property name. For example:
```
"UserID": "uid"
```
If you do not specify an attribute type as a property value to the UserID property name, compiler.UserInfo (MATLAB Compiler), which queries user details, returns <missing> as a property value.
DisplayName: Specify the LDAP or OIDC attribute type that corresponds to a user's preferred name. For example:
```
"DisplayName": "displayName"
```
Groups: Specify the LDAP or OIDC attribute type that corresponds to the group that the user belongs to. For example:
```
"Groups": "groups"
```
Note
UserID, DisplayName, and Groups property names are required in every userinfo.json file. You can add custom property names to the userInfo block and assign property values based on LDAP or OIDC attribute types. For example, if you want to use an email address as part of a user's information, you can specify Email as a property name and the LDAP attribute type EmailAddress (or mail if using OIDC) as a property value.
appAccess.doc: Text describing the purpose of the appAccess block.
appAccess: The appAccess block contains a list of property names that correspond to app names hosted on the server and property values that correspond to property names from the userInfo block. You can set access to an app by specifying a combination of property names from the userInfo block to identify a unique set of users.
<appName>: Specify an app name as the property name and a combination of property names from the userInfo block as property values to uniquely identify a set of users who can access the app. For example:
```
"BloodPressure": ["UserID", "Email"]
```

Tip

You can use an asterisk (*) wildcard character as both a property name and property value to indicate that all apps can be accessed by all users. For example:
```
"*": "*"
```
The property names WebAppsRole and WebAppsDisplayName are reserved and cannot be used in the userInfo block. However, they can be used in the appAccess block as property values. For example:
```
 "Mystery": ["UserID", "Email", "WebAppsRole", "WebAppsDisplayName"]
```
- WebAppsRole corresponds to the user's role: Author and User. For details, see Role-Based Access.
- WebAppsDisplayName corresponds to the name displayed on the apps home page.
If you make any changes in the userInfo block, you must restart the server. For details, see webapps-restart.

Example Using the `userinfo.json` File and `compiler.UserInfo` Function

In the following sample userinfo.json file the userInfo block contains the required property names: UserID, DisplayName, and Groups. In addition, it contains two custom property names, LastName and Email. All property names are assigned OIDC attributes as property values.

The appAccess block contains three apps: BloodPressure, Mortgage, and Mystery.

Access to the BloodPressure app is restricted based on UserID and DisplayName properties from the userInfo block.
Access to the Mortgage app is restricted based on UserID and LastName properties from the userInfo block.
Access to the Mystery app is restricted based on UserID and DisplayName, and the reserved property names WebAppsRole and WebAppsDisplayName.

{
    "version": "1.0.0",
    "userInfo.doc": "Property values to be fetched during login from IdP",
    "userInfo": {
      "UserID": "upn",
      "DisplayName": "displayName",
      "Groups": "groups",
      "LastName": "surname",
      "Email": "mail"
    },
    "appAccess.doc": "Policy for allowing access to user properties within an app or group of apps",
    "appAccess": {
      "BloodPressure": ["UserID","Email"],
      "Mortgage": ["UserID","LastName"],
      "Mystery": ["UserID","Email","WebAppsRole","WebAppsDisplayName"]
    }
  }

Given the userinfo.json file above, the BloodPressure app can use the compiler.UserInfo function within the app code as follows:

function startupFcn(app)
try
    user = compiler.UserInfo();
catch me
    error(me.message);
    return
end

if ~ismissing(user.UserID)
    % app code
    % Example:
    % app.userIDLabel.Text = [app.userIDLabel.Text user.UserID];
end
if isprop(user, 'Email')
    % app code
    % Example:
    % app.EmailLabel.Text = [app.EmailLabel.Text user.Email];
end
...

Given the userinfo.json file above, the Mystery app can use the compiler.UserInfo function within the app code as follows:

function startupFcn(app)
try
    user = compiler.UserInfo();
catch me
    error(me.message);
    return
end

if isprop(user, 'WebAppsDisplayName')
    % app code
    % Example:
    % app.DisplayNameLabel.Text = [app.DisplayNameLabel.Text user.WebAppsDisplayName];
end
if isprop(user, 'WebAppsRole')
    % app code
    % Example:
    % app.RoleLabel.Text = [app.RoleLabel.Text user.WebAppsRole];
end
...