SAS Viya 3.2 SAML 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 post I want to delve into more details on configuring an external SAML provider for initial authentication. SAS Logon Manager will still provide internally an OAuth/OpenID Connect interface, but here will we be configuring an additional option for end-users. The end-users will be able to use SAML to authenticate to the web interfaces provided by SAS Viya 3.2.
In this blog we’ll examine
- The implications of using SAML authentication
- The prerequisites
- How authentication is processed
- How to configure SAML authentication
- What to do if the configuration is wrong
Why would we want to SAML authentication in SAS Viya 3.2? SAML will provide us with a single sign-on mechanism to many other third-party providers. This third-party provider could be a central enterprise wide authentication provider. An example of such provider would be Microsoft Active Directory Federation Services or an alternative.
Equally configuring SAML is a simple approach to adding 2-factor authentication to the web interfaces for SAS Viya 3.2. The 2-factor authentication can be easily added to the third-party SAML provider and then re-used by SAS Logon Manager.
There are two key terms when talking about SAML. First is the SAML Identity Provider – this is the part that actually authenticates the end-user. Second is the SAML Service Provider – this is the part that uses the authentication performed by the Identity Provider. The third-party will be the SAML Identity Provider and SAS Logon Manager will be the SAML Service Provider.
Implications
Configuring SAS Logon Manager to offer SAML does not replace the default LDAP provider. End-users will be able to select to either login with their LDAP credentials or to use SAML. This means that the sasboot user can still be used to access SAS Environment Manager and update the configuration.
If you do not want to offer the default LDAP provider you will need to provide some custom code in the default logon screen. You could place some simple JavaScript in the custom logon content to automatically redirect to the SAML Provider. This would remove the ability to use the sasboot account to access SAS Environment Manager.
Mistakes in the configuration of the SAML Provider can either prevent SAS Logon Manager starting correctly or prevent users logging into the SAS Viya 3.2 environment. If you are unable to access SAS Environment Manager you will need to use the SAS Bootstrap Config tool to manually resolve the issues. Once this is complete you will be able to access SAS Environment Manager and complete any further steps. More details on the SAS Bootstrap Config tool are given below.
Note: Using the SAS Boot Strap configuration tool is like making manual changes to the Windows registry - take care!
Finally, adding SAML as an authentication option for end-users via the web interfaces does not replace the default LDAP provider. LDAP will still be used by the identities microservice and this means that any users in the third-party SAML Provider will still need to exist in the LDAP Provider. Otherwise the SAS Viya 3.2 environment will fail to perform the identities lookup and the users will be unable to log in.
Prerequisites
Obviously the first prerequisite is to have a configured third-party SAML Provider. This provider is the entity actually performing the authentication of the end-users. This third-party provider could be something like Microsoft Active Directory Federation Services or an open source provider such as RedHat’s Keycloak. The third-party provider will need to be configured with details of the SAS Viya 3.2 environment. This is beyond the scope of this current post and will be a topic I’ll look at in later materials. The SAML Provider should publish or send a link that provides metadata about the SAML Identity Provider.
As we will see in the next section when we look at how authentication is processed sensitive information will be transmitted between the SAML provider and the SAS Viya 3.2 environment. As such, Transport Layer Security (TLS) should be used for connections to both the SAML provider and the SAS Viya 3.2 environment. More details on configuring TLS for SAS Viya 3.2 can be found in the official documentation.
Authentication Process
The process of authenticating an end-user is shown in the figure below:
Where the steps are:
- The client browser connects to SAS Logon Manager.
- If the request to SAS Logon does not contain a SAML Request the SAS Logon Manager displays the logon form containing a link to perform SAML authentication and the form to do LDAP authentication. If the end-user selects SAML, SAS Logon constructs a SAML authentication request and redirects the client browser to the SAML Identity Provider.
- The end-user authenticates to the SAML Identity Provider and obtains a SAML Request and is redirected to SAS Logon.
- The client connects to the HTTP Proxy for SAS Logon to send the request to SAS Logon including the SAML Assertion in the headers.
- SAS Logon Manager received the SAML Assertion and validates the SAML Assertion.
- SAS Logon connects to the identities microservice to fetch custom and LDAP group information for the validated End-User.
- The identities microservice either looks up the validated End-User in its cache or connects to Active Directory using the LDAP Service Account to update the cache.
Configuration
To configure SAML Authentication you must complete the following:
- Configure the Service Provider in SAS Environment Manager
- Configure the Identity Provider properties in SAS Environment Manager
- Configure the Identity Provider (Third-Party)
SAML authentication is configured in two parts within SAS Environment Manager. The first set is to configure the SAML Service Provider. The configuration settings are within the Definitions section of SAS Environment Manager. For the sas.logon.saml definition you need to set the following properties:
As you can see we need to provide the TLS certificate and associated private key for the access point to SAS Logon Manager. In most SAS Viya 3.2 environments SAS Logon Manager will be accessed via the Apache HTTP Server. The Apache HTTP Server is configured out-of-the-box for HTTPS connections. However, it does use a self-signed TLS certificate. Therefore before completing the configuration of the SAML Service Provider the Apache HTTP Server could be configured with a site-signed or third-party signed TLS certificate, more details can be found in the official documentation.
In testing the SAML Service Provider configuration I had issues with the OpenSSL generated private key. As you can see above the serviceProviderKey field must contain a RSA private key. I hit the issue described in this UAA article. So I needed to convert the private to the correct RSA form. I used the following OpenSSL command to perform this:
openssl rsa -inform PEM -outform PEM -in /etc/pki/tls/private/Server_key.pem -out /etc/pki/tls/private/Server_key_RSA.pem
The SAS Viya 3.2 environment also needs to be configured with information about the SAML Identity Provider. The configuration settings are within the Definitions section of SAS Environment Manager. For the sas.logon.saml.providers.default definition you need to set the following properties:
From my testing I was able to complete the information for the SAML Identity Provider with the single idpMetadata setting. The SAML Identity Provider I was using provided a simple URL for the SAML metadata.
The final configuration change is made outside SAS Environment Manager. The SAS Logon Manager requires the password for the default truststore. Or else you will get a lot of warnings/errors in the log (although it still works). This property is already defined and is commented out. So all we need to do is remove the comment. The file that needs changing is:
/opt/sas/viya/config/etc/sysconfig/sas-javaesntl/sas-java-services
On the host where SAS Logon Manager is deployed. Within the file we uncomment the line:
export java_global_option_truststore_password="-Djavax.net.ssl.trustStorePassword=changeit"
For more information on the configuration see the SAS Viya 3.2 Administration Guide. This completes the configuration and the operating system process for the SAS Logon Manager must be restarted.
Once SAS Logon Manager has been restarted the metadata for the Service Provider can be downloaded from the following URL: https://<hostname>/SASLogon/saml/metadata. This metadata for the SAML Service Provider can then be imported into the SAML Identity Provider. Importing the metadata into the SAML Identity Provider should be sufficient to provide all the configuration settings about the SAML Service Provider to the SAML Identity Provider.
Issues
Issues with the configuration properties may mean that you:
- Will not be able to access SAS Environment Manager
- Cannot correct any configuration values in SAS Environment Manager
- Must use the SAS Bootstrap Config Tool to correct configuration
- Then restart SAS Logon operating system process
- Use SAS Environment Manager to correct/remove values
The SAS Bootstrap Config tool is available as:
/opt/sas/viya/home/bin/sas-bootstrap-config.
This tool allows administrators to directly interact with stored configuration in the SAS Configuration Server. The SAS Configuration Server requires a form of authentication before you can interact with the key/value store. This authentication takes the form of providing an authentication token. The token can be obtained from the file:
/opt/sas/viya/config/etc/SASSecurityCertificateFramework/tokens/consul/default/client.token
Using a command like the following will enable an environment variable containing the token for our current shell session:
export CONSUL_TOKEN=$(cat /opt/sas/viya/config/etc/SASSecurityCertificateFramework/tokens/consul/default/client.token)
This means that we do not need to specify the token everytime we run the SAS Bootstrap Config tool.
So for example to read all the SAS Logon Manager Configuration settings you can use the following command:
/opt/sas/viya/home/bin/sas-bootstrap-config kv read --recurse config/SASLogon/
And to change the value of setProxyParams if you have forgotten to set this in SAS Environment Manager you can use the following command:
/opt/sas/viya/home/bin/sas-bootstrap-config kv write --force config/SASLogon/sas.logon.saml/setProxyParams true
Once you set a key/value property this will be available to the service next time it starts. So for example if you forget to slide the option setProxyParams SAS Logon Manager would still start but you’d be unable to log into SAS Environment Manager. Therefore, use the example command above to set the property value and restart SAS Logon Manager. Now you should be able to log into SAS Environment Manager.
Once you can log into SAS Environment Manager you should check the saved configuration options and correct anything that might be wrong. If you restart SAS Logon Manager a second time you may find the properties you changed with the SAS Bootstrap Config tool have reverted to their SAS Environment Manager saved values.
If you want to remove an entire set of saved configuration values in SAS Environment Manager this can also be completed with the SAS Bootstrap Config tool. When you examine a set of options in SAS Environment Manager you’ll notice each one has a unique GUID, as shown here:
This GUID value can be used with the SAS Bootstrap Config tool to remove the saved configuration using the following command:
/opt/sas/viya/home/bin/sas-bootstrap-config kv delete configurationservice/configurations/<<GUID>>
So you can see the SAS Bootstrap Config tool is very powerful and will help you get out of difficulties if you enter incorrect values within SAS Environment Manager.
Stuart Rogers
