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 unable to successfully log in after enabling role-based access:

This typically 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. Note that the below steps assume that the user is able to successfully log in prior to enabling role-based access.

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. Check for common errors:
   1.  users attribute <attribute> value cannot be empty - This indicates that the server was unable to obtain a value for the attribute for the given user. Confirm that the attribute you are using exists for all users.
   2. users attribute <attribute> value cannot be an array - This indicates that the attribute used has multiple values for the given user. Ensure that the attribute you are using for user authorization returns a singular value or use a different attribute.
3. Confirm with your IdP that the attribute name and value for the user that is logging in matches what is in the webapps_app_roles.json file exactly, including case. 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. Note that if the displayName attribute is invalid or not available, the name displayed will default to the username entered in the sign-in page (LDAP) or the "sub" attribute (OIDC).
4. Confirm with your IdP that the attribute you are using for role-based access exists for all users and returns a single, distinct value.
5. (OIDC only) Ensure that the MATLAB Web App Server application is authorized to access the given attribute. 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
   1. If you are unable to authorize additional claims, consider using another attribute that has already been authorized. 
   2. To view which claims are being sent by the IdP, use an external tool to decode the returned "id_token" from the "token" value in the payload of the IdP's auth response. You can typically view this in the "Network" tab of your browser console during a sign-in attempt.