This article will guide you through setting up MATLAB Web App Server authentication and authorization through Azure AD.
Prerequisites
MATLAB Web App Server - Initial Installation
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:
MATLAB Web App Server - SSL
In order to be able to work with any form of authentication in MATLAB Web App Server, SSL needs to be enabled. In order to be able to enable SSL you will need a server certificate and corresponding private key in PEM format. These are not provided by MathWorks nor does MathWorks offer any tools for generating (self-signed) certificates. You will need to obtain these by yourself. In a corporate environment your IT department might be able to generate certificates which are valid within your company for you. Alternatively certificates can be acquired from online certificate authorities. Or self-signed certificates can be generated using third-party tools. In any case, it usually makes sense to discuss with your internal networking (security) specialists on what makes sense for your setup within your company.
Once you have obtained the certificate and key 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.
Choosing a redirect port (releases prior to R2021a)
The authorization flow with Azure AD involves first directing your users to Azure where they login and then Azure redirecting your users back to the so called "callback endpoint" on MATLAB Web App Server. In MATLAB Web App Server releases prior to R2021a this endpoint must run on a port which is different from the main MATLAB Web App Server port. If you are working with such a release, choose a port and make sure it is accessible by your end-users (and is for example not blocked by a firewall). In the remainder of this example we assume you chose port 3000 and that your main server port is 9988. As of release R2021a the callback endpoint uses the same port as the main server, again in the remainder of this example we assume 9988 is the main port.
Azure Setup
On the Azure end 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 Azure documentation where needed to ensure your App configuration meets your own security standards.
Create a new App
In your Azure portal go to your "Azure Active Directory" and then "App registrations"; use the "New registration" button to start creating a new App:
Choose a name for your App and configure your "Supported account types", it is entirely up to you what you want to configure here; it all depends on who you want to be able to give access. Under "Redirect Uri (optional)", do enter MATLAB Web App Server's callback end point as "Web" options.
For MATLAB Web App Server releases prior to R2021a:
This URI should be:
https://<MATLABWebAppServer_hostname>:<port>/oidc/callback
Where you replace <MATLABWebAppServer_hostname> with the actual fully qualified hostname of your MATLAB Web App Server host name and <port> with the redirect port chosen in the prerequisites section (i.e. in our example here 3000).
For MATLAB Web App Server releases R2021a and newer:
This URI should be:
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 name and <port> with the main port as used by MATLAB Web App Server (i.e. in our example here 9988).
If you made a mistake in the URI, or if you need to add more URIs (in order to support multiple hosts) or you ever need to change hosts, these settings can be edited later under "Authentication":
Add a client secret
When MATLAB Web App Server interacts with Azure to verify your login, it needs to identify itself as a valid/trusted client to Azure. It does this by providing a "secret" (which is similar to a "password") to Azure when communicating with it. You need to configure such secret(s) for your server(s). Go to "Certificates & secrets" and create a "New client secret". The description can be chosen freely, expiration is entirely up to you (setting an expiration means you will need to create a new secret and update the server after this period has expired which might be a minor inconvenience, if the token never expires and is leaked/stolen without your knowledge it can be abused until the secret is manually revoked and it is never automatically revoked which could be a security concern):
NOTE the actual secret is shown immediately after it has been created and only then; you cannot later look it up again. So note this down for usage later in the MATLAB Web App Server Setup section. If you forgot to do this, or lost the secret, you will have to delete the old one and create a new one.
Configuring Token Claims
Purely for authentication, your setup is pretty much complete now, but for authorization (i.e. creating different User and Author roles and in R2021a and newer configuring access on a per App or groups of Apps basis) you will also need ways in which you can uniquely identify (groups of) users. We need to make sure that Azure actually provides us with information based upon which we can do that. In the documentation and the MATLAB Web App Server section below we will be referring to 'upn' and 'groups'; to make sure these are in fact available, go to "Token configuration" and use "Add optional claim" to add an "ID" claim for "upn":
If this indicates additional "scopes" need to be configured, you can make use of the offer to configure these for you automatically:
Similarly use "Add group claim" to add a group claim, which exact "group types" to enable depends on what kind of groups you want to be able to distinguish on:
Gather information for the next section
In the next section we will need some key points of information about the App which you created and your Azure AD:
- The Application (client) ID.
- The application secret which you noted down in the "Add a client secret" section above.
- Azure's OpenID configuration URL.
1 can be found at the top of your App "Overview":
For 3, click on "Endpoints" and find the "OpenID Connect metadata document":
MATLAB Web App Server Setup
Now let's configure MATLAB Web App Server to make use of the App which we have configured.
Authentication
Find your "webapps_private" directory as documented on:
And in this directory create a file "webapps_authn.json" based on the following content:
{
"version": "1.1.0",
"type": "oidc",
"authnConfig": {
"issuer": "Azure's OpenID configuration URL as found as (3) in previous section",
"clientId": "The Application (client) ID as found as (1) in previous section",
"clientSecret": "The application secret as found as (2) in previous section",
"scope": ["openid profile email"]
},
"appConfig": {
"port": "The redirect port as chosen during prerequisites",
"displayName": "upn",
"tokenExpirationMin": "60"
}
}
If working with MATLAB Web App Server R2021a or newer, you can completely omit the whole "port" line:
"port": "The redirect port as chosen during prerequisites",
Authorization
Role-Based Access
For configuring user roles, see the "Role-Based Access" section in the documentation:
An Azure specific example "webapps_app_roles.json" is shown at the very bottom of the page:
{
"version": "1.0.0",
"appRoles": [
{
"id": "User",
"description": "A User can only execute web apps.",
"groups": {
"groups": [
"1a23456-ab2c-4444-a123-12345b3a81af",
"2b3456cd-e8ed-4fcf-ac55-6b79b0781eed "
]
}
},
{
"id": "Author",
"description": "An Author can upload, delete, and execute web apps.",
"users": { "upn": [
"bishop@myboston.com",
"queen@myboston.com"
]
}
}
]
}
As we can see, this example uses those "groups" and "upn" attributes for which we configured token claims. You can also choose to make use of other attributes like "email". For some of those attributes you may need to add additional token claims in your Azure App. Further customize this such that you indeed assign the correct roles to the users/groups which you want to assign them to.
Policy-Based Access (R2021a and newer)
With Role-based access all Users can access all Apps and all Authors can modify all Apps or upload new App for everyone. MATLAB Web App Server R2021a adds more control and allows you to configure which (groups of) users can access which (groups of) Apps exactly and which (groups of) Apps can be managed by which (groups of) user. See the following section in the documentation to learn more:
