As a follow on from my previous post, where we looked at the three different use cases for using Kerberos in SAS Viya 3.2, in this blog I want to delve into more details on configuring Kerberos for initial authentication. SAS Viya 3.2 supports the use of Kerberos or Integrated Windows Authentication to authenticate with SAS Logon Manager, as we mentioned before.
In this blog we’ll examine:
Why would we want to configure Kerberos configuration for SAS Viya 3.2? Kerberos will provide us with a strong authentication mechanism for the Visual interfaces in SAS Viya 3.2. With Kerberos enabled no end-user credentials will be sent from the browser to the SAS Viya 3.2 environment. Instead Kerberos relies on using a number of encrypted tickets and a trusted third party to provide authentication. You can find out more about how Kerberos works in a series of videos:
Once we configure Kerberos for authentication of SAS Logon Manager it replaces the default LDAP provider for end-users. This means that the only way for end-users to authenticate to SAS Logon Manager will be with Kerberos. In SAS Viya 3.2 there is no concept of fall-back authentication. Kerberos will be our only option for end-user authentication and we will be unable to use the sasboot account to still access the environment. Configuring Kerberos authentication will be an all-or-nothing approach.
While the web clients will be using Kerberos for authentication any client using the OAuth API directly will still use the LDAP provider. This means when we connect to SAS Cloud Analytic Services from SAS Studio (which does not integrate with SAS Logon) we will still be obtaining an OAuth token using the username and password of the user accessing SAS Studio.
If we make any mistakes when we configure Kerberos, or if you have not managed to complete the prerequisites correctly, the SAS Logon Manager will not start correctly. The SAS Logon Manager bootstrap process will error and SAS Logon Manager will fail to start. If SAS Logon Manager fails to start then there is no way to gain access to the SAS Viya 3.2 visual interfaces. In such a case the SAS Boot Strap configuration tool must be used to repair or change the configuration settings, we’ll cover this in the last section of the blog.
Note: Using the SAS Boot Strap configuration tool is like making manual changes to the Windows registry - take care!
Finally remember using Kerberos for SAS Logon Manager does not change the requirement for the identities microservice to connect to an LDAP provider. Since the identities microservice is retrieving information from LDAP about users and groups we need to ensure the username part of the Kerberos principal for the end-users match the username returned from LDAP. SAS Logon Manager will strip the realm from the user principal name and use this value in the comparison.
To be able to use Kerberos authentication for SAS Logon Manager a number of prerequisites need to be completed.
First a Kerberos Service Principal Name (SPN) needs to be registered for the HTTP service class. This will take the form HTTP/<HOSTNAME>, where the <HOSTNAME> is the value that will be used by clients to request a Kerberos Service Ticket. In most cases <HOSTNAME> will just be the fully qualified hostname of the machine where the Apache HTTP Server is running. But if you are using aliases or alternative DNS registrations then finding the correct name to use might not be so straightforward.
Next by registering we mean that this Service Principal Name must be provided to the Kerberos Key Distribution Center (KDC). If we are using Microsoft Active Directory the SPN must be registered against an object in the Active Directory database. Objects that can have a SPN registered against them are users or computers. We recommend using a user object in Active Directory to register the SPN against.
So we have a service account in Active Directory and we register the SPN against this service account. There are different ways the SPN can be registered in Active Directory. Your administrator could perform this tasks manually using the GUI, using an LDAP script, PowerShell script, using the setspn command, or using the ktpass command. Using these tools multiple SPNs can be registered against the service account, which is useful if there are different hostnames the end-users might use to access SAS Logon Manager. In most cases using these tools will only register the SPN; however using the ktpass command will also change the User Principal Name for the service account. More on this shortly.
Alternatively to Microsoft Active Directory you could be using a different Kerberos KDC. You could use MIT Kerberos or Heimdal Kerberos. For these implementations of Kerberos there is no difference between a user and a service. The database used by these KDCs just stores information on principals and does not provide a distinction between a User Principal Name and a Service Principal Name.
Once you have registered the SPN you need to create a Kerberos keytab. Again there are multiple tools available to create the Kerberos keytab. We recommend using the ktutil command on Linux since this is independent of the KDC and makes no changes to the Kerberos database when creating the keytab. Some tools like ktpass will make changes when generating the keytab.
In the Kerberos keytab we need to have the User Principal Name (UPN) and associated Kerberos keys for that principal. The Kerberos keys are essentially encrypted versions of the password for the principal. As we have discussed above, about the SPN, depending on the tools used to register it the UPN for the Kerberos keytab could take different forms.
When using ktpass to register SPN and create the keytab in a single step the UPN of the account in Active Directory will be set to the same value as the SPN. Whilst using the setspn command or performing the task manually will leave the UPN unchanged. Equally for MIT Kerberos or Heimdal Kerberos since there is no differentiation between principals the UPN for the keytab will be the SPN registered with the KDC.
Once the Kerberos keytab has been created it will need to be made available to any hosts with SAS Logon Manager deployed.
Finally as far as prerequisites are concerned we might need to provide a Kerberos configuration file for the host where SAS Logon Manager is deployed. This configuration should identify the default realm and other standard Kerberos settings. The Kerberos implementation in Java should be able to use network queries to find the default realm and Kerberos Key Distribution Center. However, if there are issues with the network discovery then providing a Kerberos configuration file will allow us to specify these options.
The Kerberos configuration file should be placed in the standard location for the operating system. So on Linux this would be /etc/krb5.conf. If we want to specify a different location we can also specify a JVM option to point to a different location. This would be the java.security.krb5.conf option. Equally if we cannot create a Kerberos configuration file we could set the java.security.krb5.realm and java.security.krb5.kdc options to identify the Kerberos Realm and Kerberos Key Distribution Center. We’ll show how to set JVM options below.
The process of authenticating an end-user is shown in the figure below:
Where the steps are:
Kerberos authentication is configured in SAS Environment Manager.
Note: Before attempting any configuration ensure at least one valid LDAP user is a member of the SAS Administrators custom group.
The configuration settings are within the Definitions section of SAS Environment Manager. For the sas.logon.kerberos definition you need to set the following properties:
|debug||On – causes debug,messages to be output in log|
|keyTabLocation||Java URL reference to the file, e.g.
|servicePrincipal||Principal Name from keytab|
|stripRealmForGss||On – causes realm to be
removed from User Principal
As shown here:
For more information see the SAS Viya 3.2 Administration Guide.
Additionally Kerberos must be added to the active SAS Logon profiles. To complete this again within SAS Environment Manager open All services and update SAS Logon Manager:
As shown here:
This completes the configuration and the operating system process for the SAS Logon Manager must be restarted.
The debug option for the sas.logon.kerberos definition does not produce much information to assist in troubleshooting. If we need more detailed information for troubleshooting we need to set two JVM options to get Java to produce debug messages for Kerberos and JGSSS. We can set the additional JVM arguments via SAS Environment Manager. Within SAS Environment Manager open All services and update SAS Logon Manager:
As shown here:
SAS Logon Manager will need to be restarted for these new JVM options to be picked up. The same method can be used to set the JVM options for identifying the Kerberos Realm and KDC where we would add the following:
Or for setting the location of the Kerberos configuration file where we would add:
Any issues with the configuration properties will mean that you:
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:
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 set the value of stripRealmForGss 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 stripRealmForGss 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.