SAS Viya 3.5 OpenID Connect with OKTA
SAS Viya has supported integration with a third-party OpenID Connect provider since SAS Viya 3.3. SAS Viya 3.5 adds some additional options to make integration with OKTA using OpenID Connect possible. Prior to SAS Viya 3.5 or SAS Viya 3.4 with hotfixes OKTA integration was only available using SAML. In this article we’ll examine integrating SAS Viya 3.5 with OKTA using OpenID Connect.
What is OKTA
Okta is a cloud-based identity/access management provider. As they state on their website:
Unlike legacy Federation and Access Management systems, Okta Single Sign-on is a light weight, easy to deploy solution that securely connects your employees, contractors, and customers across any of their devices to all their cloud and on-premises applications.
Further details on OKTA can be found at https://www.okta.com, and further details on the Single Sign-On solution can be found at https://www.okta.com/sites/default/files/SSO_Datasheet.pdf.
Okta supports both OpenID Connect and SAML to provide Single Sign-On into other applications. Here we are only concerned with one of the options: OpenID Connect.
OKTA Configuration
We will start by looking at the configuration that is required in Okta to setup the OpenID Connect provider. In Okta terms we add the SAS Viya 3.5 environment as an application. There is no existing definition for SAS Viya in the list of applications within the Okta administration interface. Instead, a new application integration definition must be created by creating a new app. The platform for the new app definition is "Web" and the sign on method is OpenID Connect, as shown below.
Okta next prompts for the general properties of the new application. Here the Okta administrator defines the name and icon for the application. The SAS Viya specific item entered in this section is the login redirect URI. For SAS Viya this URI is https://<<SAS_VIYA_HOST>>/SASLogon/login/callback/external_oauth, as shown below.
Saving the general settings creates the new application definition. The following screen in the Okta interface then displays the general settings for the application. The important information displayed on this page is the client credentials, shown below.
These client credentials will need to be entered in the SAS Environment Manager configuration settings for the OpenID Connect provider. The Client ID and Client Secret can be copied to the clipboard by selecting the buttons at the end of each field.
The new application must then be assigned to users or groups so that they are able to use Okta to authenticate. On the application screen in the Okta administration interface this is controlled on the Assignments pane. The application can be assigned to all users in the organization, as shown below. Or the application can be assigned to just specific groups or collections of end-users. Only those end-users assigned to the application will be able to use it.
Normally, when using Okta the username for the end-users is their email address. This can cause complications when using Okta with SAS Viya. Since SAS Viya will still require the end-users to be loaded from an LDAP Provider the usual setup for SAS Viya would not define the username to be the email address of the end-user. There are two alternatives, first the SAS Viya Identities microservice settings could be updated so that SAS Viya uses the end-user’s email address as the username. This means that any end-users still using the login form to authenticate will now need to use their email address instead of their username.
Or the mapping in Okta for the new application can be updated to present the username to SAS Viya. This is completed in the Profile Editor within the Okta administrative interface. Each application defined in Okta can have its own different set of mappings. The username is the first field listed on the mappings, and initially will have the option "Override with mapping". Selecting the "Override with mapping" allows the Okta administrator to change what is provided to SAS Viya as the username.
For example, if the first part of the end-user’s email address matches their username then the following mapping rule can be used:
String.substringBefore(user.login,'@')
More details on the functions available for the mapping rules is available in the Okta documentation. This email to username mapping is shown below.
Alternatively, to using the first part of the email, any other attributes of the end-user’s profile within Okta can be used with the string functions to form the username. Perhaps the nickName attribute holds the end-user’s LDAP username. Or perhaps the firstName and lastName can be combined to provide the LDAP username.
Finally, to be able to configure SAS Viya, we require the correct values of several URLs. Okta makes all this information available at a single URL: https://<<OKTA_DOMAIN>>/.well-known/openid-configuration. For example, this URL will output the following:
{"issuer":"https://<<OKTA_DOMAIN>>",
"authorization_endpoint":"https://<<OKTA_DOMAIN>>/oauth2/v1/authorize",
"token_endpoint":"https://<<OKTA_DOMAIN>>/oauth2/v1/token",
"userinfo_endpoint":"https://<<OKTA_DOMAIN>>/oauth2/v1/userinfo",
"registration_endpoint":"https://<<OKTA_DOMAIN>>/oauth2/v1/clients",
"jwks_uri":"https://<<OKTA_DOMAIN>>/oauth2/v1/keys",
"response_types_supported":["code","id_token","code id_token","code token","id_token token","code id_token token"],
"response_modes_supported":["query","fragment","form_post","okta_post_message"],
"grant_types_supported":["authorization_code","implicit","refresh_token","password"],
"subject_types_supported":["public"],"id_token_signing_alg_values_supported":["RS256"],
"scopes_supported":["openid","email","profile","address","phone","offline_access","groups"],
"token_endpoint_auth_methods_supported":["client_secret_basic","client_secret_post","client_secret_jwt","private_key_jwt","none"],
"claims_supported":["iss","ver","sub","aud","iat","exp","jti","auth_time","amr","idp","nonce","name","nickname","preferred_username","given_name","middle_name","family_name","email","email_verified","profile","zoneinfo","locale","address","phone_number","picture","website","gender","birthdate","updated_at","at_hash","c_hash"],
"code_challenge_methods_supported":["S256"],
"introspection_endpoint":"https://<<OKTA_DOMAIN>>/oauth2/v1/introspect",
"introspection_endpoint_auth_methods_supported":["client_secret_basic","client_secret_post","client_secret_jwt","private_key_jwt","none"],
"revocation_endpoint":"https://<<OKTA_DOMAIN>>/oauth2/v1/revoke",
"revocation_endpoint_auth_methods_supported":["client_secret_basic","client_secret_post","client_secret_jwt","private_key_jwt","none"],
"end_session_endpoint":"https://<<OKTA_DOMAIN>>/oauth2/v1/logout",
"request_parameter_supported":true,
"request_object_signing_alg_values_supported":["HS256","HS384","HS512","RS256","RS384","RS512","ES256","ES384","ES512"]}
SAS Viya Configuration
The SAS Viya configuration is completed within SAS Environment Manager. The settings are all contained within the sas.logon.oauth.providers.external_oauth definition. The following table provides the settings that are required for integration with Okta:
| Attribute | Value |
|---|---|
| addShadowUserOnLogin: | True |
| attributeMappings.user_name: | preferred_username |
| authUrl: | https://<<OKTA_DOMAIN>>/oauth2/default/v1/authorize |
| clientAuthInBody: | True |
| discoveryUrl: | https://<<OKTA_DOMAIN>>/.well-known/openid-configuration |
| emailDomain: | <<Customer email domain(s)>> |
| issuer: | https://<<OKTA_DOMAIN>> |
| linkText: | Sign-in with Okta |
| passwordGrantEnabled: | False |
| relyingPartyId: | <<CLIENT ID>> |
| relyingPartySecret: | <<CLIENT SECRET>> |
| responseType: | (not set) |
| scopes: | openid,profile |
| showLinkText: | True |
| tokenKey: | (not set) |
| tokenKeyUrl: | (not set) |
| tokenUrl: | https://<<OKTA_DOMAIN>>/oauth2/default/v1/token |
| type: | oidc1.0 |
| userInfoUrl: | (not set) |
The <<CLIENT ID>> and <<CLIENT SECRET>> will need to be copied from the Okta administrative interface. The authUrl, discoveryUrl, issuer, and tokenUrl values will have the standard form shown in the table above, also all these values can be discovered from the https://<<OKTA_DOMAIN>>/.well-known/openid-configuration URL.
The attribute clientAuthInBody must be set to true for Okta. This attribute controls how SAS Logon Manager authenticates to Okta, as a client application, to exchange the OpenID Connect Code for the ID Token. Setting clientAuthInBody to true causes the SAS Logon Manager CLIENT ID and CLIENT SECRET to be sent in the request body rather than in a BASIC authentication header. The request is made over HTTPS, so this content is encrypted.
The other two specific properties, for Okta, control the username that SAS Viya will obtain from the ID Token provided by Okta. The attributeMappings.user_name attribute is set to preferred_username which will return the username from the ID Token. However, to ensure that Okta includes the preferred_username claim in the ID Token the scopes attribute must be set to "openid,profile". If profile is not included in the scopes then the preferred_username will not be added to the claims in the ID Token, and so the username will not be available to SAS Viya.
With this configuration complete SAS Logon Manager can be restarted, for example on RedHat with:
systemctl restart sas-viya-saslogon-default
Then when end-users access the SAS Viya environment the SAS Logon Manager form will now include the link to authenticate with Okta. If you want to provide true Single Sign-On where the SAS Logon Manager form is not displayed, you’ll need to follow the steps we’ve discussed before leveraging the login_hint parameter.
Remember, for the end-users to be correctly authenticated to the SAS Viya environment the value returned by preferred_username from Okta must match the value returned from your LDAP provider as sas.identities.providers.ldap.user.accountID, by default sAMAccountNAme.
Conclusion
Okta is a popular cloud-based authentication provider. With SAS Viya 3.5 customers can configure authentication and single sign-on with Okta using OpenID Connect. Getting the correct configuration setup in Okta will be key to successfully implementing this authentication mechanism. The setup within SAS Viya 3.5 is straight-forward so long as you are aware of and have planned for the correct format of username.
