We’re smarter together. Learn from this collection of community knowledge and add your expertise.

SAS Viya 3.2 External OAuth for SAS Logon

by SAS Employee StuartRogers ‎06-30-2017 07:05 AM - edited ‎06-30-2017 07:14 AM (688 Views)

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.



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.



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:


  1. The client browser connects to SAS Logon Manager.
  2. 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.
  3. The client authenticates to the OAuth/OpenID Connect Identity Provider and obtains an OAuth Authorization code and is redirected to SAS Logon.
  4. The client connects to SAS Logon Manager including the OAuth Authorization code in query string.
  5. 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.
  6. SAS Logon connects to the identities microservice to fetch custom and LDAP group information for the validated End-User.
  7. 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.



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

  1. Configure the OAuth Provider (Third-Party not covered here)
  2. Configure the OAuth Provider in SAS Environment Manager
  3. 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:




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:


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:


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

Your turn
Sign In!

Want to write an article? Sign in with your profile.