How do I troubleshoot role-based access for MATLAB Web App Server?

I have successfully enabled authentication on my MATLAB Web App Server and would like to move forward with configuring user authorization using role-based access. I am encountering some difficulties in this process.

Answer 1

[MathWorks Support Team]

The following information may help to troubleshoot common issues related to user authorization with role-based access for MATLAB Web App Server.

 

If you are unable to start the server after enabling role-based access:

This is typically due to some kind of syntax error in the JSON files. For example:

• Missing commas.
• Missing end quotes or mismatched brackets.
• User attribute in webapps_app_roles.json does not match userAttributeName in webapps_authn.json.

Refer to the logs listed in the failed start command for more details. 

If you are immediately redirected to the post-logout screen ("You have logged out. To access MATLAB web apps, log back in.") after logging in:

This indicates that role mapping has failed. That is, the user was able to successfully authenticate, but when the server attempted to match the user's attributes to one of the roles in webapps_app_roles.json, no match was found.

To troubleshoot this:

1. Set the logging level to "verbose" and restart the Web App Server for changes to take effect. Attempt to log in again to reproduce the issue.
2. Locate the latest webapps_<timestamp>.log file captured when reproducing this issue.
3. Search for the term "Role" to locate the failed mapping. The line should be:

   Role mapping failed. Redirecting to logout page: /webapps/home/logout.html?afterlogout=/webapps/home/

4. Check the lines immediately before this error. You may see errors regarding the attribute used to map users to roles:
   1. If you see "users attribute <attribute> value cannot be empty", the server was unable to obtain a value for that attribute. Try the following troubleshooting:
      1. Ensure that the attribute exists for all users.
      2. Check that the Web App Server application is authorized to request this information. This is configured on the IdP side, typically when registering the Web App Server application with the IdP. For an example of how to add additional claims, see the "Configuring Token Claims" section here: https://www.mathworks.com/matlabcentral/answers/784521-how-do-i-setup-matlab-web-app-server-authentication-and-authorization-with-azure-ad
      3. If you are unable to authorize additional claims, consider using another attribute that has already been authorized. You may use an external tool to decode the token to observe available attributes.
   2. If you see "users attribute <attribute> value cannot be an array", ensure that the attribute you are using for user authorization returns a singular value or use a different attribute.
5. If no additional errors appear about the role mapping error, this typically indicates that the attribute value was obtained successfully but did not match any role.
   1. Confirm with your IdP that the attribute value for the user that is logging in matches what is in the webapps_app_roles.json file.
   2. For some attributes, you may test the value being returned by doing the following:
      1. Disable role-based access by renaming the webapps_app_roles.json file.
      2. In the webapps_authn.json file, set the displayName to be the attribute you are using for user authorization.
      3. Restart the Web App Server.
      4. Log in as the user you are attempting to authorize.
      5. Observe the name displayed in the upper-right corner to determine the correct value for that attribute for this user.