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
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.
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.
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.
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.
The process of authenticating an end-user is shown in the figure below:
Where the steps are:
To configure SAML Authentication you must complete the following:
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:
|entityBaseURL||The URL for SAS Logon Manager|
|entityID||A unique name for the SAS Logon Manager Service Provider|
|serviceProviderCertificate||Base-64 encoded certificate|
|serviceProviderKey||Base-64 encoded RSA private key|
|serviceProviderKeyPassword||Password for the private key (can be left blank if no password)|
|setProxyParams||Enable if SAS Logon is accessed via a reverse proxy. This is true for most SAS Viya 3.2 environments.|
|signMetaData||The local service provider should sign metadata. Default,Off.|
|signRequest||The local service provider should sign SAML requests. Default Off.|
|socket.connectionManagerTimeout||The number of milliseconds before the connection pooling times out for HTTP requests for SAML metadata. Default = 10000.|
|socket.soTimeout||The number of milliseconds before the read times out for HTTP requests for SAML metadata. Default = 10000.|
|wantAssertionSigned||The assertions must be signed. Default Off.|
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:
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:
|assertionConsumerIndex||The index of the assertion consumer service to use from identity provider metadata. The value must be a positive integer. Default = 0.|
|idpMetadata||The identity provider metadata or the URL to the metadata.|
|linkText||The hyperlink to display on the sign-in page. Default “Use your corporate credentials”.|
|metadataTrustCheck||The identity provider certificate must be trusted. Default Off.|
|nameID||The default name ID format. Default “urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified”.|
|showSamlLoginLink||Display a link to the identity provider on the sign-in page. Default On.|
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:
On the host where SAS Logon Manager is deployed. Within the file we uncomment the line:
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 with the configuration properties may mean that you:
The SAS Bootstrap Config tool is available as:
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:
Using a command like the following will enable an environment variable containing the token for our current shell session:
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:
And to change the value of setProxyParams if you have forgotten to set this in SAS Environment Manager you can use the following command:
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:
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.