SAS Viya 3.2 External OAuth for SAS Logon

4 Likes

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:

The implications of using external OAuth authentication
The prerequisites
How authentication is processed
How to configure external OAuth authentication
What to do if the configuration is wrong

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.

Implications

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.

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 OAuth/OpenID Connect Provider. This would remove the ability to use the sasboot account to access SAS Environment Manager.

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.

Prerequisites

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.

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 already have an active HTTP session the SAS Logon Manager displays the logon form; containing a link to perform OAuth/OpenID Connect authentication and the form to do LDAP authentication. If the end-user selects OAuth/OpenID Connect, SAS Logon constructs an authentication request and redirects the client browser to the OAuth/OpenID Connect Provider.
The client authenticates to the OAuth/OpenID Connect Identity Provider and obtains an OAuth Authorization code and is redirected to SAS Logon.
The client connects to SAS Logon Manager including the OAuth Authorization code in query string.
SAS Logon Manager received the OAuth Authorization code and contacts the OAuth/OpenID Connect Identity Provider to exchange it for an access token. SAS Logon Manager receives information about the end-user from the OAuth/OpenID Connect Identity Provider.
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 or LDAP using the LDAP Service Account to update the cache.

Configuration

To configure OAuth/OpenID Connect authentication we need to complete the following:

Configure the OAuth Provider (Third-Party not covered here)
Configure the OAuth Provider in SAS Environment Manager
Configure TLS Trust

The key information from configuring the third-part OAuth Provider will be:

Client ID: a unique identifier that identifies the SAS Viya 3.2 environment
Client Secret: a unique password for the client ID shared between SAS Viya 3.2 and OAuth Provider
Redirect URLS: https://<hostname>/SASLogon/login/callback/default

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:

Attribute	Value
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
Type	oidc1.0 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:

Issues

Any issues with the configuration properties could 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 set the value of the username mapping 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.oauth.providers.default/attributeMappings.user_name preferred_username

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:

/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