Authenticate Machine Learning Server users against LDAP AD or Azure Active Directory

Article
2/16/2018

Important

This content is being retired and may not be updated in the future. The support for Machine Learning Server will end on July 1, 2022. For more information, see What's happening to Machine Learning Server?

Applies to: Machine Learning Server, Microsoft R Server 9.x

Machine Learning Server's offers seamless integration with authentication solutions when configured to operationalize analytics.

Screenshot that shows machine learning's seamless integration with authentication solutions.

To secure connections and communications, you have several options:

Authentication Method	When to Use
Local 'admin' account	For one-box configurations
Active Directory / LDAP	For enterprise on-premises configurations
Active Directory / LDAP-S	For enterprise on-premises configurations with SSL/TLS enabled
Azure Active Directory	For enterprise cloud configurations

Local Administrator Account Authentication

During configuration, a default administrator account, 'admin', is created to manage the web and compute nodes for In Machine Learning Server (and R Server). This account allows you to use the CLI or administration utility to configure this feature, edit ports, restart nodes, and so on.

This account might be sufficient when trying to operationalize with a one-box configuration since everything is running within the trust boundary. However, it is insufficient for enterprise configurations.

To set or change the password for the local administrator account after the configuration script has been run, follow these steps.

To log in to Machine Learning Server with this user for remote execution or web service functionalities, use remoteLogin() as described in the article "Connecting to Machine Learning Server with mrsdeploy."

Warning

If you enable Azure Active Directory or Active Directory/LDAP authentication, this 'admin' account can no longer be used to authenticate with Machine Learning Server.

Active Directory and LDAP/LDAP-S

Active Directory (AD) and LDAP are a great authentication option for on-premises configurations to ensure that domain users have access to the APIs.

LDAP is the standard protocol for reading data from and writing data to Active Directory (AD) domain controllers. AD LDAP traffic is unsecured by default, which makes it possible to use network-monitoring software to view the LDAP traffic between clients and domain controllers.

By default, the LDAP security provider is not configured. To enable LDAP authentication support, update the relevant properties in your configuration file. The values you assign to these properties must match the configuration of your LDAP Directory Information Tree (DIT).

You can make LDAP traffic confidential and secure using Secure Sockets Layer (SSL) / Transport Layer Security (TLS) technology. This combination is referred to as LDAP over SSL (or LDAP-S). To ensure that no one else can read the traffic, SSL/TLS establishes an encrypted tunnel between an LDAP client and a domain controller. Learn more about enabling SSL/TLS. Reasons for enabling LDAP-S include:

Organizational security policies typically require that all client/server communication is encrypted.
Applications use simple BIND to transport credentials and authenticate against a Domain Controller. As simple BIND exposes the users’ credentials in clear text, using SSL/TLS to encrypt the authentication session is recommended.
Use of proxy binding or password change over LDAP, which requires LDAP-S. Bind to an AD LDS instance Through a Proxy Object
Applications that integrate with LDAP servers (such as Active Directory or Active Directory Domain Controllers) might require encrypted LDAP communications.

Warning

You cannot have both Azure Active Directory and Active Directory/LDAP enabled at the same time. If one is set to "Enabled": true, then the other must be set to "Enabled": false.

On each web node:

Enable LDAP/LDAP-S in the external JSON configuration file, appsettings.json:

Open the configuration file, <web-node-install-path>/appsettings.json.
Search for the section starting with "LDAP": {
Enable this section and update the properties so that they match the values in your Active Directory Service Interfaces Editor.

For better security, we recommend you encrypt the password before adding the information to appsettings.json.

LDAP Properties	Definition
Host	Address of the Active Directory server
Port	(version 9.1+) Used to override the default LDAP port. By default, the LDAP port is 389 and the LDAP-S port is 636.
UseLDAPS	Set 'true' for LDAP-S or 'false' for LDAP Note: If LDAP-S is configured, an installed LDAP service certificate is assumed so that the tokens produced by Active Directory/LDAP can be signed and accepted by Machine Learning Server.
BindFilter	(version 9.0.1 only) The template used to do the Bind operation. For example, "CN={0},CN=DeployR,DC=TEST,DC=COM". {0} is the user's DN.
QueryUserDn	Distinguished name of user with read-only query capabilities with which to authenticate
QueryUserPassword	Password for that user with which to authenticate (value must be encrypted). We highly recommend that you encrypt LDAP login credentials before adding the information to this file.
QueryUserPasswordEncrypted	True/False. If 'True', it means the value of QueryUserPassword is an encrypted string.
SearchBase	Context name to search in, relative to the base of the configured ContextSource, for example, 'ou=users,dc=example,dc=com'.
SearchFilter	The pattern to be used for the user search. "SearchFilter": "cn={0}" is for each user's DN. In legacy systems, some use "SearchFilter": "sAMAccountName={0}"
UniqueUserIdentifierAttributeName	(Version 9.1) The attribute name that stores the unique user ID for each user. If you are configuring roles, you must ensure that the username returned for this value matches the username returned by SearchFilter. For example, if "SearchFilter": "cn={0}" and "UniqueUserIdentifierAttributeName": "userPrincipalName", then the values for cn and userPrincipalName must match.
DisplayNameAttributeName	(Version 9.1) The attribute name that stores the display name for each user.
EmailAttributeName	(Version 9.1) The attribute name that stores the email address for each user.

Important

The entities created by the users, specifically web services and session snapshots, are tied to their usernames. For this reason, you must be careful to prevent changes to the user identifier over time. Otherwise, pre-existing web services and snapshots cannot be mapped to the users who created them.

For this reason, we strongly recommend that you DO NOT change the unique LDAP identifier in appsettings.json once users start publishing service or creating snapshots.

Similarly, if your organization changes its usernames, those users can no longer access the web services and snapshots they created unless they are assigned to the Owner role.

Warning

For 9.0.1 Users! The unique identifier is always set to the userPrincipalName in version 9.0.1. Therefore, make sure that a value is defined for the userPrincipalName in the Active Directory Service Interfaces Editor or the authentication may fail. In the Explorer, connect to the domain controller, find the user to authorize, and then make sure that the value for the UserPrincipalName (UPN) property is not null.

For example, with R Server 9.1:

"LDAP": {
        "Enabled": true,
        "Host": "<host_ip>",
        "Port": "<port_number>"
        "UseLDAPS": "True",
        "QueryUserDn": "CN=deployradmin,CN=DeployR,DC=TEST,DC=COM",
        "QueryUserPasswordEncrypted": true,
        "QueryUserPassword": "ABCD00000123400000000000mnop00000000WXYZ",
        "SearchBase": "CN=DeployR,DC=TEST,DC=COM",
        "SearchFilter": "cn={0}"  
        "UniqueUserIdentifierAttributeName": "userPrincipalName",
        "DisplayNameAttributeName": "name",
        "EmailAttributeName": "mail"     
}

Note

Need help figuring out your Active Directory/LDAP settings? Check out your LDAP settings using the ldp.exe tool and compare them to what you’ve declared in appsettings.json. You can also consult with any Active Directory experts in your organization to identify the correct parameters.

To set different levels of permissions for users interacting with web services, assign them roles.
If using a certificate for access token signing, you must:

Important

You must use a certificate for access token signing whenever you have multiple web nodes so the tokens are signed consistently by every web node in your configuration.

In production environments, we recommend that you use a certificate with a private key to sign the user access tokens between the web node and the LDAP server.

Tokens are useful to the application developers who use them to identify and authenticate users who are sending API calls within their application. Learn more...

Every web node must have the same values.
1. On each machine hosting the Web node, install the trusted, signed access token signing certificate with a private key in the certificate store. Take note of the Subject name of the certificate as you need this information later. Read this blog post to learn how to use a self-signed certificate in Linux for access token signing. Self-signed certificates are NOT recommended for production usage.
2. In the appsettings.json file, search for the section starting with "JWTSigningCertificate": {
3. Enable this section and update the properties so that they match the values for your token signing certificate:
```
"JWTSigningCertificate": {
    "Enabled": true,
    "StoreName": "My",
    "StoreLocation": "CurrentUser",
    "SubjectName": "CN=<subject name>"
    "Thumbprint": "<certificate-thumbprint>"
}
```
  Note
  
  Use "Thumbprint" to ensure that the correct certificate is loaded if there are multiple certificates on the same system with same name used for different purposes such as IPsec, TLS Web Server Authentication, Client Authentication, Server Authentication, and so on. If you do not have multiple certificates with same name, you can leave the Thumbprint field empty.
Save changes to appsettings.json.
Restart the web node using the administration utility so that the changes can take effect.
Run the diagnostic tests to ensure all tests are passing in the configuration.

Important

If you run into connection issues when configuring for Active Directory/LDAP, try the ldp.exe tool to search the LDAP settings and compare them to what you declared in appsettings.json. To identify the correct parameters, consult with any Active Directory experts in your organization.
Repeat these steps on each machine hosting the web node.
Share the connection details with any users who authenticate with Machine Learning Server either to make API calls directly or indirectly in R using remoteLogin() function in the mrsdeploy package.

Azure Active Directory

Azure Active Directory (AAD) can be used to securely authenticate in the cloud when the client application and Web node have access to the internet.

Step 1: Log in to the Azure portal

Sign in to the Azure portal.
Select the upper-right hand corner and select the Active Directory account from the list. If the Azure Active Directory has not been set up yet, contact your system administrator. In our example, that directory is MyMLServer.
Select Azure Active Directory from the left-hand side.
Select App registrations tab at the top. The application list appears. You may not have any applications yet.

Step 2: Create a web application

Now, create a web app that is tied to the Azure Active Directory as follows:

Select New application registration at the top.
Enter a Name for your application, such as Machine Learning Server Web app.
For the Application type, select the Web app / API.
In the Sign-on URL box, enter https://localhost:12800. This is the port that R Client and R Server listen on.
Select Create to create the new web application.

The application is created and its details appear onscreen.
Copy the Application ID for the web application. You use this later when you configure your Native application and Machine Learning Server using this ID.
Select Settings . The Settings pane appears on the right.
Select Keys from the Settings pane. The Keys pane appears.
In the Password area, add a client key. Provide a description of your choosing and select a key duration.
Select Save to save the key.
Be sure to copy the key.

Important

Take note of this key as it is needed to configure roles to give web services permissions to certain users.
Also, take note of the application's tenant ID. The tenant ID is the domain of the Azure Active Directory account, for example, myMLServer.contoso.com.

Step 3: Create a native application

Now, let's create a native application. This application links the web application to the Machine Learning Server web node.

In the Azure portal, select Azure Active Directory from the left-hand side.
Select App registrations.
Select New application registration at the top.
Enter a Name for your application, such as Machine Learning Server native app.
For the Application type, select the Native.
In the Redirect URI field, enter:
```
urn:ietf:wg:oauth:2.0:oob
```
Select Create to create the new native application.

The application is created and its details appear onscreen.
Copy the Application ID for the web application. You use this ID later to enable AAD in Machine Learning Server.
Select Settings . The Settings pane appears on the right.
Select Required permissions.
Select Add at the top.
Select Select an API.
In the search field at the top, type the name of the web application you created. In our example, we use the name Machine Learning Server Web app.
Select the web application name.
Select the Select button. The Select permissions > Enable Access fields appear.
Select the checkmark next to the name of the web application.
Select the Select button. The pane closes.
Select Done at the bottom to finish adding the permissions.

Step 4: Enable Azure AD on each web node

Open the configuration file, <web-node-install-path>/appsettings.json.
Search for the section starting with:
```
"AzureActiveDirectory": {
   "Enabled": false,
```
Warning

You cannot have both Azure Active Directory and Active Directory/LDAP enabled at the same time. If one is set to "Enabled": true, then the other must be set to "Enabled": false.
Enable Azure Active Directory as the authentication method: "Enabled": true,

Update the other properties in that section so that they match the values in the Azure portal. Properties include:

Azure AD Properties	Definition
Enabled	To use AAD for authentication, set to 'true'. Else, set to 'false'.
Authority	Use 'https://login.windows.net/<URL to AAD login>' where <URL to AAD login> is the URL to the AAD login. For example, if the AAD account domain is myMLServer.contoso.com, then the Authority would be 'https://login.windows.net/myMLServer.contoso.com'
Audience	Use the Application ID value for the WEB app you created in the Azure portal.
ClientId	Use the Application ID value for the NATIVE app you created in the Azure portal.
Key	This is the key for the WEB application you took note of before.
KeyEncrypted	We highly recommend that you encrypt login credentials before adding the information to this file. Set KeyEncrypted to 'true' if using encrypted information. For plain text, set to 'false'.

For example:

"AzureActiveDirectory": {
   "Enabled": true,
   "Authority": "https://login.windows.net/myMLServer.contoso.com",
   "Audience": "00000000-0000-0000-0000-000000000000",
   "ClientId": "00000000-0000-0000-0000-000000000000",
   "Key": "ABCD000000000000000000000000WXYZ", 
   "KeyEncrypted": true
 }

To set different levels of permissions for users interacting with web services, assign them roles.
Restart the web node for the changes to take effect.
Authorize this machine for Azure Active Directory Test by running a diagnostic test of the configuration.

Important

You must run the diagnostic tests once on each web node to authorize this device for Azure Active Directory. You will not be able to log in using AAD until this has been done.
Repeat these steps on each machine hosting a web node.

Step 5: Share the required AAD connection details with your users

Share the connection details, such as the Authority and Audience, with any users who need to authenticate with Machine Learning Server to make API calls directly or indirectly in R using remoteLoginAAD() function in the mrsdeploy package.

If you do not specify a username and password as arguments to the login call or R functions, you are prompted for your AAD username (@) and password.

Important

Learn how to authenticate with AAD using the remoteLoginAAD() function in the mrsdeploy R package as described in this article: "Connecting to Machine Learning Server with mrsdeploy."

Share via

Authenticate Machine Learning Server users against LDAP AD or Azure Active Directory

Local Administrator Account Authentication

Active Directory and LDAP/LDAP-S

Azure Active Directory

See also

Additional resources