How can I capture and decode tokens to troubleshoot OIDC authorization with MATLAB Web App Server?

I am working on configuring authentication, role-based access and/or policy-based access for MATLAB Web App Server using OIDC. I am encountering issues, but there is minimal information in the logs to help troubleshoot this. I'd like to inspect the information the Web App Server is receiving from the authentication server (identity provider) to get more insight on this issue.

How can I do this?

Answer 1

[MathWorks Support Team]

You can gain more information on the information the Web App Server is receiving from the Identity Provider (IdP) by inspecting the token that is returned after login. This can also be useful for validating the app registration when you do not have direct access to view this in the IdP.

The following steps were validated with R2023b using Azure Active Directory as the IdP. The instructions are based on Google Chrome, but may be adapted for other browsers if necessary. Note that for some issues, you may need to disable role-/policy-based access (while leaving authentication enabled) to successfully capture the token. 

 

To capture the token:

1. Open a new browser tab (preferably Google Chrome). If your IdP uses SSO and you are already signed in in this browser, you may need to use an incognito window.
2. Open Chrome Developer Tools and set it to capture network traffic:
   1. Right-click and select "Inspect" to open the console.
   2. Switch to the network tab.
   3. Ensure the "Preserve Log" checkbox is checked. 
      
3. Access your webapps homepage and sign in.
4. In the network tab, look for a request named "auth" -- there will likely be multiple. Select the request where the payload includes a token (it should have a blue icon). 
   
5. Copy this token.

To decode the token:

1. Open Microsoft's jwt.ms tool. (You can use any base64 or JSON Web Token decoder, but this tool offers improved readability and additional context on the token fields.)
2. Paste the token from the request into the text area. The decoded token should appear below, with 4 claims: "sub", "id_token", "iat", and "exp". 
3. From this output, copy the value of "id_token" and paste this into the text area, replacing the existing token. The new claims should appear below (toggle between the "Decoded Token" and "Claims" tabs for readability). An example is included below. 
   

To troubleshoot using this information:

1. Validate the decoded claims against your webapps_authn.json contents. If any of these fields are incorrect, consult the documentation and alter the webapps_authn.json file to correct this:
   1. The "aud" claim should match the "clientId".
   2. The "iss" claim should match the first part of the "issuer".
2. Verify that the token claims are configured correctly (i.e. that the Web App Server can access all of the information it needs). If any necessary claims are not present, consult the IdP's documentation to permit additional user/group claims:
   1. The "given_name" in your webapps_authn.json file should appear within the available claims. For the above example, the "given_name" is set to "upn".
   2. If using role-based access, the user and group attribute names used in your webapps_app_roles.json file should appear within the available claims.
   3. If using policy-based access, the "userAttributeName" and "groupAttributeName" used in your webapps_auth.json file should appear within the available claims. 

For example, the token above was captured from a server where policy-based access was not working correctly when using a group attribute. The "groupAttributeName" was set to "groups", which does not appear in the above token claims. To resolve this, we configured the app registration to include group claims as per the Configuring Token Claims section here. This resolved the issue, and the ID token now contains a claim with the signed-in user's groups: