Authentication

Note

Authentication is supported in the standalone MATLAB^® Web App Server™ product and not the development version included in MATLAB Compiler™. For details, see MATLAB Web App Server Differences.

Prerequisite

Enable SSL on the server. For more information, see Enable SSL.

Create `webapps_authn.json` File

Authentication lets you validate a user's credentials and helps you control which users can access web apps deployed on the server.

MATLAB Web App Server supports authentication using Lightweight Directory Access Protocol (LDAP) and OpenID Connect (OIDC).

To enable authentication:

Check if SSL is enabled. For more information, see Enable SSL.

Create a file named webapps_authn.json and place it in the webapps_private folder, which is located within the config folder. The format for webapps_authn.json depends on whether you are using LDAP or OIDC for authentication.

The webapps_private folder can be found in:

Operating System	Folder Location
Windows^®	`%ProgramData%\MathWorks\webapps\R2023a\config\webapps_private`
Linux^®	`/local/MathWorks/webapps/R2023a/config/webapps_private`
macOS	`/Library/Application Support/MathWorks/webapps/R2023a/config/webapps_private`

LDAP Authentication

An LDAP directory server stores information about users, groups, and applications. Each entry in the directory consists of three components: a distinguished name (DN), a collection of attributes, and a collection of object classes.

To use LDAP authentication, create a file named webapps_authn.json using the following JSON schema and place it in the webapps_private folder.

{
    "version": "1.2.0",
    "type": "ldap",
    "authnConfig": {
        "host": "<LDAP server host name>",
        "port": "<LDAP server port number>",
        "searcherDN": "",
        "searcherPassword": "",
        "baseDN": "<Point in LDAP from where to start search for a user>",
        "userFilter": "<Filter syntax>"
    },
    "appConfig": {
        "checkSSLCA": "<Boolean indicating whether to check for trusted SSL certificate>",
        "trustedSSLCA": "<Path to trusted SSL certificate>",
        "displayName": "<Identifier to display on MATLAB Web App Server home page>",
        "tokenExpirationMin": "<Token expiration duration in minutes>",
        "userAttributeName": "<Attribute name to identify user objects>",
        "groupAttributeName": "<Attribute name to identify group objects>"
    }
}

version: Specify the version of the JSON schema. Default value for R2023a is: 1.2.0.
type: Specify the type of authentication to use. Set this value to ldap.
host: Specify the LDAP directory server host name. For example: myldap.example.com.
port: (Optional) Specify the LDAP directory server port number. For example: 389. If a port number is not specified, the default port will be used. The MATLAB Web App Server uses SSL/STARTTLS to secure communication with the LDAP server. This ensures that usernames and passwords that are transmitted through an encrypted channel between MATLAB Web App Server and the LDAP server. By default, the server uses the standard port 636 for SSL on Windows and port 389 for STARTTLS on Linux and macOS. The LDAP server must be configured to allow SSL/STARTTLS connection over the specified (or default) LDAP port; otherwise, authentication will fail.
searcherDN: Specify the searcher account's DN in the directory. The default value is "". Searcher DN refers the account allowed to search the LDAP directory server. For example: "cn=admin,dc=example,dc=com".
searcherPassword: Searcher account's password. The default value is "".
MATLAB Web App Server uses the values for searcherDN and searcherPassword to search for a user's DN using a userFilter. The discovered DN is subsequently validated against with the entered password through LDAP. Values for searcherDN and searcherPassword are not required if the LDAP server provides access for anonymous authentication.
Since the webapps_authn.json file lives within the webapps_private folder, which is only readable by the server account, the searcher’s credentials are protected from apps or other users who log in to the server.
baseDN: Specify the base DN in the directory. The base DN is the location in the directory where the application starts searching for a user. For example: dc=myldap,dc=example,dc=com.
userFilter: Specify a filter to find a user's DN. MATLAB Web App Server uses userFilter to find the user’s DN that matches the entered username, represented as {username} in the filter. If no match is found or multiple matches are found, authentication fails. The filter can be specified using standard LDAP filter syntax. For example: (&(objectClass=User)(sAMAccountName={username})).
checkSSLCA: Check whether the LDAP server's SSL certificate was signed by a recognized certificate authority (CA). Setting this property to true checks for a valid SSL certificate and setting it to false with forgo checking. If set to true, you need to specify a value for trustedSSLCA. If set to false, usernames and passwords are still transmitted between MATLAB Web App Server and the LDAP server through an encrypted channel. However, this check is recommended for additional security.
trustedSSLCA: On Linux and macOS systems, specify the path to the root certificate issued by the certification authority (CA) that signed the site certificate. On Windows systems, you do not need to specify the path. As long as the root certificate is in the Trusted Root Certification Authorities certificate store, MATLAB Web App Server will automatically find it.
displayName: Configure how the user's identity is displayed on the MATLAB Web App Server home page by specifying an attribute of a user’s LDAP entry. For example, setting this property to uid displays the user ID. Default is the username that is entered during the authentication process.
tokenExpirationMin: Specify the token expiration duration in minutes. For example: 60. Default value is "", which means the tokens do not expire.
userAttributeName: Specify an attribute name to identify user objects. For example: uid. You must set a value for this property if you use policy-based access. Otherwise, do not include this property in your JSON file. For more information, see Policy-Based Access.
groupAttributeName: Specify an attribute name to identify group objects. For example: member. You must set a value for this property if you use policy-based access. Otherwise, do not include this property in your JSON file. For more information, see Policy-Based Access.

Example `webapps_authn.json` File for LDAP

{
    "version": "1.2.0",
    "type": "ldap",
    "authnConfig": {
        "host": "myldap.example.com",
        "port": "",
        "searcherDN": "",
        "searcherPassword": "",
        "baseDN": "DC=myldap,DC=example,DC=com",
        "userFilter": "(&(objectClass=User)(sAMAccountName={username}))"
    },
    "appConfig": {
        "checkSSLCA": "false",
        "trustedSSLCA": "",
        "displayName": "uid",
        "tokenExpirationMin": "60"
    }
}

Example `webapps_authn.json` File for LDAP When Using Policy-Based Access

{
    "version": "1.2.0",
    "type": "ldap",
    "authnConfig": {
        "host": "myldap.example.com",
        "port": "",
        "searcherDN": "",
        "searcherPassword": "",
        "baseDN": "DC=myldap,DC=example,DC=com",
        "userFilter": "(&(objectClass=User)(sAMAccountName={username}))"
    },
    "appConfig": {
        "checkSSLCA": "false",
        "trustedSSLCA": "",
        "displayName": "uid",
        "tokenExpirationMin": "60",
        "userAttributeName": "uid",
        "groupAttributeName": "memberOf"
    }
}

OIDC Authentication

OpenID Connect (OIDC) allows MATLAB Web App Server to verify the identity of an end user based on the authentication performed by a third-party identity provider (IdP). To use OIDC authentication on the server, you need to register with an IdP such as Microsoft^® Azure^® AD, or Google^® Identity Platform.

To use OIDC authentication, create a file named webapps_authn.json using the following JSON schema and place it in the webapps_private folder.

{
    "version": "1.3.0",
    "type": "oidc",
    "authnConfig": {
        "issuer": "<OIDC IdP issuer URI>",
        "clientId": "<Client ID from IdP>",
        "clientSecret": "<Client secret from IdP>",
        "redirectUrl": "<Redirection URL>",
        "scope": ["<scope1> <scope2>"]
    },
    "appConfig": {
        "port": "<OIDC authentication port number used by MATLAB Web App Server>",
        "displayName": "<Identity to display on MATLAB Web App Server home page>",
        "tokenExpirationMin": "<Token expiration duration in minutes>",
        "userAttributeName": "<Attribute name to identify user objects>",
        "groupAttributeName": "<Attribute name to identify group objects>",
        "prompt": <Boolean indicating whether to re-authenticate user>
    }
}

version: Specify the version of the JSON schema. The default value for R2023a is: 1.2.0.
type: Specify the type of authentication to use. Set this value to oidc.
issuer: Specify the OIDC IdP issuer URI. For example, if using Google Identity Platform: https://accounts.google.com/.well-known/openid-configuration.
clientId: Specify the client ID you obtained while registering your credentials with an IdP. For example, if using Google Identity Platform: 1234567890-xxxxxxxxxxxx.apps.googleusercontent.com.
clientSecret: Specify the client secret you obtained while registering your credentials with an IdP. For example, if using Google Identity Platform: _xxxxxxxxxxxxx_Xxxxxx_xX.
Since the webapps_authn.json file lives within the webapps_private folder, which is only readable by the server account, clientId and clientSecret are protected from apps or other users who log in to the server.
redirectUrl: (Optional) Specify the redirect URL you used while configuring OIDC authentication with the IdP. If left empty, the host name and port number of the computer running the MATLAB Web App Server is used as a callback. The format of the URL is: https://<MATLABWebAppServer_hostname>:<port_server_is_running_on>/webapps/extauth/callback. For example, if MATLAB Web App Server is running on port 9988, then the redirect URL is: https://example.com:9988/webapps/extauth/callback.
Prior to R2021a, the format of the redirect URL was: https://<MATLABWebAppServer_hostname>:<port>/oidc/callback. For example: https://example.com:3000/oidc/callback.
scope: Specify the identifiers for resources that an administrator wants MATLAB Web App Server to access. For example, if using Google Identity Platform: openid profile email.
port: (Optional) Specify the port number used by the MATLAB Web App Server process internally for OIDC authentication. For example: 4000. This port number must be different from the redirectUrl port number. If a port number is not specified, the MATLAB Web App Server process automatically picks a port for OIDC authentication.
displayName: Configure how the user's identity is displayed on the MATLAB Web App Server home page, by specifying an attribute name of an authenticated user object. For example, if using Google Identity Platform, given_name displays the user's name. The default is the sub attribute.
tokenExpirationMin: Specify the token expiration duration in minutes. For example: 60. The default value is "", which means the tokens do not expire.
userAttributeName: Specify an attribute name to identify user objects. For example: uid. You must set a value for this property if you use policy-based access. Otherwise, do not include this property in your JSON file. If you are not using policy-based access but decide to include this property in your JSON file, set the value to "". For more information, see Policy-Based Access.
groupAttributeName: Specify an attribute name to identify group objects. For example: member. You must set a value for this property if you use policy-based access. Otherwise, do not include this property in your JSON file. If you are not using policy-based access but decide to include this property in your JSON file, set the value to "". For more information, see Policy-Based Access.
prompt: Specify whether you want to re-authenticate a user who is already logged-in to an identity provider (IdP).
- If "prompt" is set to "true", then a user must re-authenticate even if logged-in to an IdP.
- If "prompt" is set to "false", and a user is logged-in to an IdP, then the IdP login screen is avoided. If the user is not logged-in, then a user must re-authenticate by logging-in.
- If no "prompt" field and value is specified, then the "prompt" field is taken to be "true". This is the default.

Note

If you use OIDC authentication, you need to register MATLAB Web App Server as an application with the IdP.
During the registration process, you need a redirect URL for MATLAB Web App Server. The format of the URL is: https://<MATLABWebAppServer_hostname>:<port_server_is_running_on>/webapps/extauth/callback. For example: https://example.com:9988/webapps/extauth/callback.

Example `webapps_authn.json` File for OIDC Using Google Identity Platform

{
    "version": "1.2.0",
    "type": "oidc",
    "authnConfig": {
        "issuer": "https://accounts.google.com/.well-known/openid-configuration",
        "clientId": "1234567890-xxxxxxxxxxxx.apps.googleusercontent.com",
        "clientSecret": "_xxxxxxxxxxxxx_Xxxxxx_xX",
        "redirectUrl": "https://example.com:9988/webapps/extauth/callback",
        "scope": ["openid profile email"]
    },
    "appConfig": {
        "port": "4000",
        "displayName": "given_name",
        "tokenExpirationMin": "60"
    }
}

Tip

After setting up authentication, if you are unable to login from your browser, try clearing your browser's cache and cookies, or try a different browser.

Caution

The JSON schema syntax for webapps_authn.json is strictly enforced. Errors in the schema syntax may result in the server not starting, or being denied access to the server when you try to login.

Authentication

Prerequisite

Create `webapps_authn.json` File

LDAP Authentication

Example `webapps_authn.json` File for LDAP

Example `webapps_authn.json` File for LDAP When Using Policy-Based Access

OIDC Authentication

Example `webapps_authn.json` File for OIDC Using Google Identity Platform

Related Topics

External Websites

Authentication

Prerequisite

Create webapps_authn.json File

LDAP Authentication

Example webapps_authn.json File for LDAP

Example webapps_authn.json File for LDAP When Using Policy-Based Access

OIDC Authentication

Example webapps_authn.json File for OIDC Using Google Identity Platform

Related Topics

External Websites

Create `webapps_authn.json` File

Example `webapps_authn.json` File for LDAP

Example `webapps_authn.json` File for LDAP When Using Policy-Based Access

Example `webapps_authn.json` File for OIDC Using Google Identity Platform