Note
Authentication is only supported in the MATLAB® Web App Server™ product and not the development version of MATLAB Web App Server included in MATLAB Compiler™. For details, see MATLAB Web App Server Differences.
Note
To use authentication, you need to enable SSL on the server. For more information, see Enable SSL.
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® |
|
Linux® |
|
macOS |
|
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.0.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>"
}
}
version: Specify the version of the
JSON schema. Default value for R2020b is: 1.0.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.myboston.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=myboston,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=myboston,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.
webapps_authn.json
File for LDAP{
"version": "1.0.0",
"type": "ldap",
"authnConfig": {
"host": "myldap.myboston.com",
"port": "",
"searcherDN": "",
"searcherPassword": "",
"baseDN": "DC=myldap,DC=myboston,DC=com",
"userFilter": "(&(objectClass=User)(sAMAccountName={username}))"
},
"appConfig": {
"checkSSLCA": "false",
"trustedSSLCA": "",
"displayName": "uid",
"tokenExpirationMin": "60"
}
}
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.1.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>"
}
}
version: Specify the version of the
JSON schema. The default value for R2020b is: 1.1.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>/oidc/callback
.
For example:
https://myboston.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: Specify the port number used by
MATLAB
Web App Server for OIDC authentication. For example:
3000
.
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.
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 URI for
MATLAB Web App Server. The format of the URI is:
https://<MATLABWebAppServer_hostname>:<port>/oidc/callback
.
For example:
https://myboston.com:3000/oidc/callback
.
webapps_authn.json
File for OIDC Using Google Identity Platform{
"version": "1.0.0",
"type": "oidc",
"authnConfig": {
"issuer": "https://accounts.google.com/.well-known/openid-configuration",
"clientId": "1234567890-xxxxxxxxxxxx.apps.googleusercontent.com",
"clientSecret": "_xxxxxxxxxxxxx_Xxxxxx_xX",
"scope": ["openid profile email"]
},
"appConfig": {
"port": "3000",
"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.