SAS Viya 3.5 or indeed SAS Viya 3.4 (May 2019 Upgrade) provides options to enable true single sign-on with a third-party SAML or OpenID Connect provider. This requires some manual configuration of the Apache HTTP Server. In this blog we’ll look at some considerations and what you need to configure.
Single Sign-On with either SAML or OpenID Connect will mean that end-users no-longer need to interact with SAS Logon Manager to access the SAS Viya web applications. This configuration will not impact the Mobile application or Command-Line Interfaces. Equally, this configuration will have no impact on SAS Studio 4.4 on SAS Viya 3.4 or SAS Studio 5.2 (Basic) on SAS Viya 3.5.
The configuration we will use to provide Single Sign-On relies on part of the OpenID Connect specification. Since SAS Logon Manager is an OpenID Connect provider to the rest of the SAS web applications this will function for both SAML and OpenID Connect third-party authentication. This configuration will work as-is with SAS Viya 3.5. However, with SAS Viya 3.4 you need to ensure the version you are running has the emailDomain property for the third-party SAML or OpenID Connect provider.
Since the end-user will no-longer interact with SAS Logon Manager, they will no-longer see the standard login form. This means that end-users will not be able to log in with LDAP credentials or the sasboot account. In the configuration, we will provide some options to enable certain clients to still have access to the login form. Alternatively, end-users can directly access the /SASLogon/login URL to access the login form, they will then need to enter the URL for the application they wish to use after logging in.
Configuration
First and foremost, the SAML or OpenID Connect provider must have an entry in the emailDomain property. For SAML this is under sas.logon.saml.providers.external_saml and for OpenID Connect this is under sas.logon.oauth.providers.external_oauth. The string entered in the emailDomain property does not have to be the actual email domain for the end-users. This can be any string, for example "matchme.com", since it will be provided by the configuration, we perform to the Apache HTTP Server. As such, this configuration will work well where the end-users have many different email domains. Or where the SAS Administrator is not sure what the email domains of the end-users will be.
The Single Sign-On configuration uses a login_hint parameter. The login_hint parameter is part of the OpenID Connect specification and supported by SASLogon. This query string parameter is passed in the authorize request, which is /SASLogon/oauth/authorize. SAS Logon expects to receive an email domain in the hint, and this value is compared against a list of email domains configured for each SAML or OpenID Connect identity provider. If there is a match, the user is redirected automatically to that provider, bypassing the login page.
To add the login_hint parameter to the authorize request a change must be made to the Apache HTTP Server. We will add a rewrite rule to the configuration to set the login_hint parameter on the requests to /SASLogon/oauth/authorize. In most cases the SAS Viya environment will be accessed over HTTPS. This means the changes we need to make should be made in the SSL configuration file. For RedHat Enterprise Linux this would be the /etc/httpd/conf.d/ssl.conf file. The new content will be added to the end of the file before the closing </VirtualHost> tag.
For deployments that are using HTTP, this should be placed in a new .conf file. The Apache HTTP Server processes the .conf files in alphabetical order and this one needs to occur before the proxy configuration in proxy.conf so it should be named accordingly, for example login_hint.conf. Putting the redirect rule in both places is fine too. The Apache HTTP Server must be restarted after making any changes to the configuration.
To enable the login_hint parameter for all authorize requests made to SAS Logon Manager you can use the following content:
# SSO for SAS Viya set login_hint parameter
RewriteEngine On
RewriteCond "%{QUERY_STRING}" !login_hint
RewriteRule "SASLogon/oauth/authorize" "/SASLogon/oauth/authorize?login_hint=matchme.com" [QSA,PT]
The RewriteCond statement ensures the rule is only applied when the query string, the part of the URL following a question mark, does not contain an existing login_hint. The RewriteRule then takes the request for SASLogon/oauth/authorize and appends the login_hint query parameter. Where the value of the login_hint matches the emailDomain entered in either the SAML or OpenID Connect configuration.
When the replacement URI contains a query string, the default behavior of RewriteRule is to discard the existing query string and replace it with the newly generated one. Using the [QSA] flag causes the query strings to be combined. The target (or substitution string) in a RewriteRule is assumed to be a file path, by default. The use of the [PT] flag causes it to be treated as a URI instead. That is to say, the use of the [PT] flag causes the result of the RewriteRule to be passed back through URL mapping, so that location-based mappings, such as Alias, Redirect, or ScriptAlias, for example, might have a chance to take effect. This is important for your SAS Viya environment since the URL must be redirected from the Apache HTTP Server to an instance of the SAS Logon Manager.
The example above, will add the login_hint to all authorize requests. This means that the SAS Logon Manager form will not be displayed for any users. Which means that the sasboot account cannot be used to access the environment. However, we can change the configuration slightly to enable the SAS Logon Manager form when accessed from a specific IP Address:
# SSO for SAS Viya set login_hint parameter except for specifc IP
RewriteEngine On
RewriteCond "%{QUERY_STRING}" !login_hint
RewriteCond expr "! -R '10.96.1.166'"
RewriteRule "SASLogon/oauth/authorize" "/SASLogon/oauth/authorize?login_hint=matchme.com" [QSA,PT]
The RewriteCond statements are combined using AND syntax. So, the RewriteRule will only apply when both conditions are true. This means in the example above that the request must not already contain the login_hint AND does not (!) come from the IP address 10.96.1.166, then the RewriteRule will apply. The "-R" in the second RewriteCond means the same as "%{REMOTE_ADDR} -ipmatch ...", but is more efficient according to the documentation.
So, we can provide Single Sign-On to all our end-users, but still allow our administrator on 10.96.1.166 access to the SAS Logon Manager form. But what if we want to still make the SAS Logon Manager form available to more than a single IP address? We could add more and more RewriteCond statements and add the [OR] flag to change the logic to OR from AND. However, this would soon become confusing and difficult to manage. Instead we can change the RewriteCond statement to use CIDR notation:
# SSO for SAS Viya set login_hint parameter except for specific IP Range
RewriteEngine On
RewriteCond "%{QUERY_STRING}" !login_hint
RewriteCond expr "! -R '10.96.1.0/24'"
RewriteRule "SASLogon/oauth/authorize" "/SASLogon/oauth/authorize?login_hint=matchme.com" [QSA,PT]
Now the second condition states the request must not come from any IP address in the range 10.96.1.0 – 10.96.1.255. So Single Sign-On will operate for any request that do not come from this range of IP addresses. These IP addresses will see the standard SAS Logon Manager form as normal.
Finally, as another set of examples for how you might want to add conditions to the RewriteRule, what about changing the behavior based on the browser rather than the IP address. To exclude the Microsoft Edge Browser:
# SSO for SAS Viya set login_hint parameter except for MS Edge browsers
RewriteEngine On
RewriteCond "%{QUERY_STRING}" !login_hint
RewriteCond "%{HTTP_USER_AGENT}" "!.*Edg.*"
RewriteRule "SASLogon/oauth/authorize" "/SASLogon/oauth/authorize?login_hint=matchme.com" [QSA,PT]
With these two condition statements anyone not using Microsoft Edge will get Single Sign-On. While accessing the SAS Viya environment in Microsoft Edge will result in the SAS Logon Manager form being displayed. Equally, the same could be done for the Google Chrome browser:
# SSO for SAS Viya set login_hint parameter except for Chrome Browsers
RewriteEngine On
RewriteCond "%{QUERY_STRING}" !login_hint
RewriteCond "%{HTTP_USER_AGENT}" "!.*Chrome.*"
RewriteRule "SASLogon/oauth/authorize" "/SASLogon/oauth/authorize?login_hint=matchme.com" [QSA,PT]
Conclusion
In this post we’ve demonstrated how you can easily enable Single Sign-On with either a third-party SAML or OpenID Connect provider. We’ve also demonstrated how you can simply extend the configuration to disable Single Sign-On for specific users, based either on IP address or browser type. You could even combine these example rules to enable one group of users to have Single Sign-On with SAML and another group of users with OpenID Connect.
Update: June 2024
It was pointed out to me that it might be necessary to restart the SAS Studio V operating system process to pick-up these changes.
