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 an external OAuth/OpenID Connect provider for initial authentication. Whilst SAS Logon Manager provides OAuth authentication within the environment this blog will look at configuring a third-party OAuth/OpenID Connect provider for logging into the SAS Viya 3.2 web interfaces.
In this blog we’ll examine:
Why would we want to configure an external OAuth provider for SAS Viya 3.2? OAuth or OpenID Connect will provide us with a single sign-on mechanism to many other third-party providers. These third-party providers could be internal to the customer or external to the customer. An example of an external provider would be Google accounts interaction. Using this method we could successfully have end-users access the SAS Logon Manager with their Google accounts.
Equally configuring OAuth or OpenID Connect 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 OAuth provider and then re-used by SAS Logon Manager. For example if we integrate with Google accounts and you have 2-factor authentication configured for your Google account we will now have two-factor authentication for SAS Logon Manager.
OAuth/OpenID Connect is seen by many as the next step beyond SAML authentication. OpenID Connect is the industry approved mechanism for federated authentication. It has several enhancements over standard OAuth and SAML authentication.
Configuring SAS Logon Manager to offer OAuth/OpenID Connect does not replace the default LDAP provider. End-users will be able to select to either login with their LDAP credentials or to use OAuth/OpenID Connect. 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 OAuth/OpenID Connect 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 OAuth/OpenID Connect 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 OAuth/OpenID Connect 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 OAuth/OpenID Connect Provider. This provider is the entity actually performing the authentication of the end-users. This third-party provider could be something like Google or an open source provider internal to your organization 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.
As we will see in the next section when we look at how authentication is processed sensitive information will be transmitted between the OAuth/OpenID Connect provider and the SAS Viya 3.2 environment. As such, Transport Layer Security (TLS) should be used for connections to both the OAuth/OpenID Connect 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 OAuth/OpenID Connect authentication we need to complete the following:
The key information from configuring the third-part OAuth Provider will be:
The redirect URLS are valid URLs used to redirect clients back to the SAS Viya 3.2 environment after they have authenticated.
SAS Viya 3.2 OAuth authentication is configured in SAS Environment Manager. The configuration settings are within the Definitions section of SAS Environment Manager. The example values shown below come from my own testing using the Keycloak open source project from RedHat. For the sas.logon.oauth.providers.default definition you need to set the following properties:
|addShadowUserOnLogin||On – add a local shadow,user upon successful authentication
Note: Should always be on.
|attributeMappings.user_name||Example = preferred_username
The attribute from the provider containing the user name
|authURL||Example = https://example.com/auth/realms/TestRealm/protocol/openid-connect/auth
The URL to the authorization endpoint of the third-party
|emailDomain||Example = example.com
The email address domain of users that can sign on with this provider
|issuer||Example = https://example.com/auth/realms/TestRealm
The principal that issued to the token, as a case-sensitive string or URI
|linkText||Example = Log-in with OpenID
The text that should be displayed on the Viya SAS Logon sign-in page
|relyingPartyId||Example = TestClientID-OAuth
The client ID registered in the provider
|relyingPartySecret||Example = <<PASSWORD>>
The secret registered in the provider for the client ID
|scopes||Example = openid
The comma-delimited list,of scopes for the authorization request. For OIDC providers, always specify openid here to indicate authentication.
|showLinkText||On – Show the lint text on the sign-in page|
|tokenKey||Example = blank
The HMAC key or RSA public key used to sign tokens. Specify either this value or tokenKeyURL, but not both.
|tokenKeyURL||Example = blank
The URL to obtain the token key. Specify either this value or tokenKey, but not both.
|tokenURL||Example = https://example.com/auth/realms/TestRealm/protocol/openid-connect/token
The URL to the token endpoint
Either ‘oidc1.0’ or ‘oauth2.0’
Transport Layer Security (TLS) trust is important since SAS Logon Manager must be able to complete a TLS handshake with the OAuth Provider. This means that the Certificate Authority chain for the OAuth Provider must be available to the Java service running the SAS Logon Manager. For most external third-parties this will be included in the default Mozilla Bundle shipped as part of the SAS Security Certificate Framework. However, for internal OAuth Providers this CA cert chain will need to be manually added to the trusted bundle.
This completes the configuration and the operating system process for the SAS Logon Manager must be restarted. Now when users are sent to the SAS Logon Manager to sign into SAS Viya 3.2 they can either enter their LDAP credentials or select the link to log in with the OAuth/OpenID Connect provider:
Any issues with the configuration properties could 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 set the value of the username mapping 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 incorrectly set the username mapping 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.