This article will guide you through setting up MATLAB Web App Server authentication and authorization through Okta.
Contents
This guide assumes MATLAB Web App Server has already been installed and you were able to successfully deploy and run a web app on it. To learn more about initial setup, see:
In order to be able to work with any form of authentication in MATLAB Web App Server, SSL needs to be enabled. Follow the instructions in the documentation to enable SSL on your MATLAB Web App Server:
After having configured this, please verify that you can indeed successfully access your Apps over HTTPS.
On the Okta side you will need to configure an app registration. In this example we will create a new app with the most basic settings commonly needed for MATLAB Web App Server integration. Please do review all (other) app configuration options by yourself and consult the Okta documentation where needed to ensure your App configuration meets your own security standards.
In your Okta admin portal, select Applications > Applications from the side bar and click "Create App Integration."
In the resulting popup, select "OIDC - OpenID Connect" as the sign-in method and "Web Application" as the application type. Then, click Next.
In the general settings, choose a name for your app and ensure that the Authorization Code grant is checked.
For the redirect URI, this should be of the form:
https://<MATLABWebAppServer_hostname>:<port>/webapps/extauth/callback
where you replace <MATLABWebAppServer_hostname> with the actual fully qualified hostname of your MATLAB Web App Server host and <port> with the main port as used by MATLAB Web App Server -- for example, https://myhost.mydomain.com:9988/webapps/extauth/callback.
You can leave the sign-out redirect URIs and trusted origins blank.
For Assignments, select "Allow everyone in your organization to access" to allow all users in your organization to sign in. You can restrict access later on the MATLAB Web App Server side using role-based access and policy-based access.
Click Save.
In the next section we will need some key points of information about the app which you created and your Okta account:
- Your Okta account's domain (to find the OIDC discovery endpoint URL).
- The application's client ID.
- The application's client secret.
To find your Okta account's domain, click the dropdown in the upper-right of the Okta admin portal. This should display your name, email, and your Okta account's domain -- this is often a URL of the form <account>.okta.com. The discovery endpoint URL can then be found by appending /.well-known/openid-configuration to this domain, for example:
https://<account>.okta.com/.well-known/openid-configuration
Use a browser to confirm that this URL takes you to a JSON document with information about this identity provider.
Then, go to the app you just created (Applications > select from the list of Active applications). In the general tab, you should be able to view and copy the client ID and secret (2 and 3).
We will use these values in the next step.
Now let's set up MATLAB Web App Server using the information from the client app registration.
To enable authentication on MATLAB Web App Server, navigate to the webapps_private directory on your server machine as documented here:
Then, create a new file webapps_authn.json with the based on the following content:
{
"version": "1.3.0",
"type": "oidc",
"authnConfig": {
"issuer": "The discovery endpoint URL from (1) in previous section",
"clientId": "The application's client ID from (2) in previous section",
"clientSecret": "The application's client secret from (3) in previous section",
"scope": ["openid profile email groups"]
},
"appConfig": {
"displayName": "name",
"tokenExpirationMin": "60",
"prompt": "false"
}
}
Save this file and restart your MATLAB Web App Server (webapps-restart). Then, attempt to access the webapps homepage and log in -- once logged in, your name should show in the upper-right corner of the webapps homepage:
Confirm that you are able to successfully log in to the webapps homepage via Okta before enabling role- or policy-based access.
For configuring user roles, see the "Role-Based Access" section in the documentation:
The below example assigns the user with the email admin@mydomain.com and any users in the WebAppAuthors group the Author role, and any users in the WebAppUsers group the User role. Note that you will need to configure the groups attribute to use group membership for roles (see Configuring Attributes).
{
"version": "1.0.0",
"appRoles": [
{
"id": "Author",
"description": "An Author can upload, delete, and execute web apps.",
"groups": { "groups": [ "WebAppAuthors" ] },
"users": { "email": [ "admin@mydomain.com" ] }
},
{
"id": "User",
"description": "A User can only execute web apps.",
"groups": { "groups": [ "WebAppUsers" ] }
}
]
}
To customize the apps and folders available to different users with policy-based access, refer to the documentation:
Ensure that you also set the userAttributeName and groupAttributeName in your webapps_authn.json file.
You can customize app behavior based on the logged-in user's attributes with the compiler.UserInfo() function in your code. See the following documentation:
The attributes that you can use for role-based access, policy-based access, and userinfo are limited to those that are made available to the registered client application by Okta. This guide covers the two simplest ways to manage this, but you can consult Okta documentation for other ways to include additional token claims.
To use group membership for role- or policy-based access, we will need to ensure the correct groups are included in the token claims.
In the Okta portal, go to Applications and select the client application you created for your MATLAB Web App Server. Then, in the "Sign On" tab under "OpenID Connect ID Token," configure a groups claim filter that includes the groups you would like to use with your MATLAB Web App Server. You can use the filter settings shown below to include all groups.
Now, you should be able to use groups for role-/policy-based access in MATLAB Web App Server with the group attribute name "groups".
If you encounter issues, ensure that the group names in your webapps_app_roles.json and/or webapps_acc_ctl.json files match the group names in Okta exactly (including case), and that your webapps_authn.json file includes the "groups" scope.
One way you can customize which user attributes are made available to MATLAB Web App Server is using profile mappings. You can also check existing mappings to see which attributes are currently available, and what the correct names for these attributes are.
In the Okta portal, go to Directory > Profile Editor > Apps and select the "Mappings" button for your registered MATLAB Web App Server client app.
The mappings show how user attributes in Okta (left) map to the attributes made available to the MATLAB Web App Server (right). For example, if you want to customize web app behavior based on a user's last name, you would use the user attribute named "family_name" in your web app.
You can add and map additional custom attributes in the profile editor for the registered MATLAB Web App Server client application. Note that certain claims may require specific scopes (groups, profile, email, etc.) -- for example, when using custom claims, ensure your webapps_authn.json file contains the 'profile' scope. See Okta documentation for more details.
If you encounter issues with any of these steps, here are some troubleshooting steps that may help:
- Confirm that you are using the correct scopes for the attributes you would like to use in MATLAB Web App Server.
- Confirm that all attribute names or values used for role-/policy-based access exactly match the attribute in Okta (case-sensitive).
- To check what attribute value MATLAB Web App Server is receiving for a specific user, you can set the displayName in webapps_authn.json to this value. For example, if you are having issues specifying a user role with the 'name' attribute, try:
- Disable role-based access by removing or renaming the webapps_app_roles.json file.
- Set the displayName in webapps_authn.json to "name".
- Save your changes and restart the MATLAB Web App Server.
- Have the user log in and check what name displays in the upper-right corner of the webapps homepage. This is the correct value to use for this user's name.
- Note that if the given displayName attribute is not available, the displayed name will default to the 'sub' claim, which appears as a random string of numbers and letters.
- To troubleshoot issues with role-/policy-based access, use the following MATLAB Answer to help capture and decode tokens during a sign-in attempt: https://www.mathworks.com/matlabcentral/answers/2168673-how-can-i-capture-and-decode-tokens-to-troubleshoot-oidc-authorization-with-matlab-web-app-server
- Note that not all attributes available to MATLAB Web App Server will appear in the token, as some may be made available at a userinfo endpoint instead.
- The token is typically helpful for troubleshooting issues related to groups.
- If you experience issues after enabling multiple new configurations at the same time (e.g. role-based access and policy-based access), try troubleshooting each new configuration separately until issues are resolved.
- To disable role-based access, remove or rename the webapps_app_roles.json file.
- To disable policy-based access, remove or rename the webapps_acc_ctl.json file.
