SAS Viya 3.2 LDAP for SAS Logon
As a follow on from my previous post, where we looked at the different authentication options for SAS Viya 3.2, in this blog I want to delve into more details on configuring LDAP for initial authentication.
In this blog we’ll examine
- The implications of using LDAP authentication
- The prerequisites
- How authentication is processed
- How to configure LDAP authentication
- What to do if the configuration is wrong
LDAP Authentication is the default authentication provider for the SAS Viya 3.2 Visual Interfaces. We must configure a connection to a LDAP Provider for the SAS Viya 3.2 environment to be useable. There are two main types of LDAP provider:
- Microsoft Active Directory
- OpenLDAP based Providers
The configuration properties for the two different types of LDAP provider are different.
Implications
The main implication of using LDAP is the way in which the SAS Viya 3.2 environment connects to LDAP. The LDAP connection from both SAS Logon Manger and the identities microservice are made as a SIMPLE BIND. This means that the credentials used to make that SIMPLE BIND are exposed on the network.
Multiple connections are made between SAS Logon Manager and the LDAP provider. When an end-user logs into SAS Logon Manager using their LDAP credentials; two SIMPLE BINDS are made. The first SIMPLE BIND is performed as the LDAP service account and the second as the end-user. This means that the LDAP service account credentials are sent over the network for every login to the SAS Viya 3.2 environment. Whilst the end-user credentials are only sent when they log in.
The SIMPLE BIND in itself does not contain any network security. Therefore, you should look to encrypt this connection by using Transport Layer Security (TLS).
TLS can be used on LDAP connections in two different ways. The traditional mechanism is similar to how a web server would be configure for TLS. The TLS is negotiated initially and the connection URI for the LDAP provider changes. In this mechanism we connect to ldaps://hostname:636, where 636 is the standard secure port compared to the default unsecured port of 389. This is very similar to changing a website address to HTTPS from HTTP and the port to 443 from 80. This mechanism is often referred to as LDAPS.
The second mechanism to provide TLS on LDAP connections is called startTLS. With startTLS the connection is made as normal to ldap://hostname:389 and during the initial connection the TLS handshake is performed. So startTLS has the advantage of not requiring any changes to the connection URL. However, the client needs to be able to support startTLS.
For SAS Viya 3.2 the underlying technology powering both SAS Logon Manager and the identities microservice does not support startTLS. However LDAPS is supported and recommended.
Only a single LDAP connection can be defined in SAS Environment Manager. This single connection is shared by both SAS Logon Manager and the identities microservice. This means that only one set of connection details and search filters can be applied to both connections.
Authentication Process
The process of authenticating an end-user is shown in the figure below:
Where the steps are:
- The End-User connects to the SAS Logon application and enters their username and password in the login form.
- SAS Logon connects to the LDAP provider with a simple BIND using the stored credentials for a service account to search for the Distinguished Name of the end-user.
- SAS Logon makes a second simple BIND to the LDAP provider as the end-user using the password entered in the logon form and the Distinguished Name returned from the previous search.
- SAS Logon connects to the identities microservice to fetch custom and LDAP group information for the validated End-User.
- The identities microservice connects to the LDAP provider with a simple BIND using stored credentials for a service account. Regularly connecting to refresh the cache of users and groups, which is stored in SAS Infrastructure Data Server.
Configuration
The LDAP connection properties can be configured at two points:
- As part of the deployment using the sitedefault.yml
- Post-deployment using the SAS Environment Manager
The default settings for the LDAP connection are geared towards Active Directory. This means that the majority of the defaults will work with Active Directory. While to make OpenLDAP work correctly more configuration items will need to be changed.
Sitedefault File
The sitedefault.yml can be used as part of the Ansible deployment to configure the connection to the LDAP provider. A sample sitedefault.yml is provided in roles/consul/files/sitedefault_sample.yml, within the playbook. Creating a sitedefault.yml in the roles/consul/files directory will enable the automatic configuration of the LDAP provider.
Since the majority of defaults will work for Active Directory to easily configure Active Directory as the LDAP provider you only need the following content in the sitedefault.yml:
config:
application:
sas.identities.providers.ldap.connection:
host: '<LDAP HOSTNAME>'
port: 389
userDN: '<Service Account DN>'
password: '<Service Account Password>'
sas.identities.providers.ldap.group:
baseDN: '<OU to start user search from>'
sas.identities.providers.ldap.user:
baseDN: '<OU to start group search from>'
Note: YML files do not use tab – SPACE is King!
So all we are doing with this sitedefault.yml is providing the connection definitions to Active Directory in terms of the host, port, username, and password. Then for both the groups and users we provide the baseDN which is the point in the LDAP tree where any searches will start.
For OpenLDAP things are a bit more complicated. OpenLDAP allows administrators far more freedom with the object classes and information stored against both users and groups. Also OpenLDAP does not automatically provide the memberOf information for a user. Administrators can enable the memberOf information as an additional overlay within OpenLDAP.
A sample sitedefault.yml for OpenLDAP is:
config:
application:
sas.identities.providers.ldap.connection:
host: '<LDAP HOSTNAME>'
port: '389'
userDN: '<Service Account DN>'
password: '<Service Account Password>'
sas.identities.providers.ldap.group:
accountId: 'name'
baseDN: '<OU to start group search from>'
createdDate: 'createTimestamp'
distinguishedName: 'none'
member: 'member'
modifiedDate: 'modifyTimestamp'
objectFilter: '(objectClass=groupOfNames)'
objectClass: 'groupOfNames'
searchFilter: 'dn={0}'
sas.identities.providers.ldap.user:
accountId: 'uid'
baseDN: '<OU to start user search from>'
createdDate: 'createTimestamp'
distinguishedName: 'none'
memberOf: 'memberOf'
modifiedDate: 'modifyTimestamp'
objectFilter: '(objectClass=inetOrgPerson)'
objectClass: 'inetOrgPerson'
searchFilter: 'uid={0}'
Note: YML files do not use tab – SPACE is King!
The settings provided for sas.identities.providers.ldap.connection are essentially the same as the Active Directory case. We provide the host, port, username, and password for making connections. The majority of changes are in how we search for and return group and user information.
For group information we have the following:
For user information we have the following:
Key Information: distinguishedName must be set to none for OpenLDAP
The distinguishedName attribute for both the group and user search when using OpenLDAP must always be set to none. This is required in order to force the identities microservice to behave slightly different in how it fetches the groups the user is a member of. Essentially, with Active Directory, SAS Viya uses the distinguishedName attribute to do this lookup. In Active Directory, this happens to be an explicit LDAP field. Not all LDAP servers support this (OpenLDAP included) however, so an alternative mechanism is needed and setting the distinguishedName attribute to none triggers this alternative mechanism.
The examples above will both use standard unencrypted LDAP connections. To enable LDAPS we need to change an additional property in sas.idenities.providers.ldap.connection as well as updating the port value from 389 to 636. The addition property is url and should be set as follows:
Automatically Adding an Administrator
One final useful option with the sitedefaul.yml file is to automatically add an administrator to the SAS Viya 3.2 environment. By adding the following to the end of the sitedefault.yml:
identities:
sas.identities:
administrator: '<USERNAME>'
Will add the <USERNAME> to the SAS Administrators custom group. This means that any further configuration can be performed using this LDAP account rather than the sasboot account.
SAS Environment Manager
If you do not want to use the sitedefault.yml file to automatically configure the LDAP provider you can set all of the same property values using SAS Environment Manager. At the end of the deployment you can search the SAS Logon Manager log file for the URL to set the sasboot user’s password. For example running the following command:
cat /var/log/sas/viya/saslogon/default/sas-saslogon_* |grep sasboot
Will output something similar to:
Where the code value will be different. Once you set the password for the sasboot user you will be automatically redirected to the configuration section of SAS Environment Manager. From this screen you can set all the properties for:
- sas.identities.providers.ldap.connection
- sas.identities.providers.ldap.group
- sas.identities.providers.ldap.user
The values entered in SAS Environment Manager will be the same values provided for the example sitedefault.yml files above.
Issues
Any issues with the LDAP connection properties can be corrected using SAS Environment Manager, you will need to be logged in with the sasboot user or a member of SAS Administrators. Remember to assume the SAS Administrators role to be able to make changes. Also the link to reset the sasboot password is only valid for 24 hours. If more than 24 hours have passed then SAS Logon Manager will need to be restarted.
Changes made to the LDAP connection properties should immediately take effect; at most there might be a 30 second delay. For example if the telephone number field is not being correctly returned for users, a change to the sas.identities.providers.ldap.user telephone field will immediately change the return information from the LDAP Provider. There is no need to restart any of the SAS Viya 3.2 services.
Performance
The LDAP connections for both the SAS Logon Manager and identities microservice are configured to use a pooled connection. The settings in sas.identities.providers.ldap.connection define the pool used for these connections. The default maximum number of active connections from the pool at the same time is 8. While this should be sufficient for initial deployments the pool configuration will probably need to be tuned for either a number of concurrent logins or long/complex LDAP searches.
Stuart Rogers
