Leveraging shared accounts with SAS Viya means storing credentials for an account in an authentication domain and using those credentials to launch a SAS Compute Server session or a SAS Cloud Analytic Services session. The credentials can be shared by members of a group or just a list of individual users. The same credentials will be used SAS Compute Server and SAS Cloud Analytic Services so that any host-based access controls will apply to the shared account rather than the end-users. However, both SAS Compute Server and CAS will also have access to the end-user internal ID tokens so access to other SAS Viya services will still be as the end-user. Previously, only username/password credentials could be stored which will not work in an environment configured for SCIM. Starting with the SAS Viya 2022.1.4 Stable release Token credentials can now be stored, and with the SAS Viya 2023.03 Stable release these stored token credentials can be leveraged by both SAS Cloud Analytic Services and SAS Compute Server. In this blog we’ll look at this in more detail.
When SAS Viya is configured for SCIM the only accounts that are available to use as shared accounts are those that have been provisioned by your SCIM version 2.0 client. For example, this might be your Azure Active Directory tenant or your OKTA tenant. So just to be clear these shared accounts that will be used to run sessions for SAS Compute Server and SAS Cloud Analytic Services must exist in your third-party Identity Provider, must be provisioned into SAS Viya using SCIM, and you must be able to authenticate as the shared account using either OpenID Connect or SAML.
First where will these Token credentials be stored? These Token credentials will be stored in a Token Authentication domain. The Token Authentication domain can be created using SAS Environment Manager, the SAS Viya CLI, or the Python Tools for SAS Viya (pyviyatools). If using the SAS Viya CLI or pyviyatools the type is oauth2.0, while in SAS Environment Manager the type is Authentication (token). The SAS Viya authorization rules control which users have access to place credentials in the Token Authentication domain. When credentials are placed in the Token Authentication domain these are assigned to one or more identities, which could be users, groups, or custom groups. A single Token Authentication domain can have multiple credentials stored within it. Users, groups, and custom groups can be assigned to the Token Authentication domain which enables the credentials stored in the Token Authentication domain to be used by these users or members of the groups or custom groups. Assigning users, groups, or custom groups to the Token Authentication domain does not grant the ability to change the credentials, just to use those credentials. Care should be taken by the SAS Administrator to ensure that a single end-user is only assigned one credential in one authentication domain.
For example, using the SAS Viya CLI we could create a Token Authentication domain with the following command:
sas-viya credentials domains create --domainId DefaultToken --label DefaultToken --type oauth2.0 --description "DefaultAuth using token credentials"
You would previously need to authenticate as a member of SAS Administrators before running this command.
As we stated above SAS Viya authorization rules must be created to allow the shared account to have access to the new Token Authentication domain. This is required so that the shared account will be able to store their token in this Token Authentication domain. If you are going to use a series of shared accounts, perhaps a different shared account for different groups, it makes sense to create a custom group for your shared accounts. You can then set the authorization rules for the group rather than individually for each shared account. You can use the SAS Viya CLI to create such a custom group with the following commands:
sas-viya identities create-group --id SharedAccounts --name SharedAccounts --description 'Group for shared accounts'
sas-viya identities add-member --group-id SharedAccounts --user-member-id sharedaccnt1@customer.com
sas-viya identities add-member --group-id SharedAccounts --user-member-id sharedaccnt2@customer.com
You would previously need to authenticate as a member of SAS Administrators before running these commands. This creates the group SharedAccounts and assigns two users to the new custom group.
The documentation covers adding the authorization rules using SAS Environment Manager. Alternatively, with the custom group created you could then again use the SAS Viya CLI to define the authorization rules to allow the shared accounts to store their tokens in the Token Authentication domain:
sas-viya authorization create-rule -o '/SASEnvironmentManager/domains' -g 'SharedAccounts' -p READ
sas-viya authorization create-rule -o '/credentials/domains/DefaultToken/groups/*' -g 'SharedAccounts' -p 'Create,Read,Update,Delete'
sas-viya authorization create-rule -o '/credentials/domains/DefaultToken/users/*' -g 'SharedAccounts' -p 'Create,Read,Update,Delete'
sas-viya authorization create-rule -o '/credentials/domains/DefaultToken/credentials' -g 'SharedAccounts' -p 'Read'
You would previously need to authenticate as a member of SAS Administrators before running these commands. These authorization rules enable members of the SharedAccounts custom group to store a token assigned to either groups or individual users.
With the Token Authentication domain created and the authorization rules created, you can now use the shared accounts to store their token. Specifically, you will be storing a Refresh Token for the shared account. This will allow the SAS Launcher service or SAS Cloud Analytic Services to request a new Access Token during the session launch and so launch the session as the shared account. Since we are looking at an environment configured for SCIM, where LDAP has been disabled, we need to authenticate the shared account using the third-party OpenID Connect or SAML authentication provider. Then once authenticated to SAS Viya the token can be stored. This could be performed in SAS Environment Manager. Or this could be performed using pyviyatools.
If you are going to use pyviyatools you still need to authenticate the shared account using the OpenID Connect or SAML authentication provider. You can do this using the SAS Viya CLI using the auth loginCode option:
sas-viya auth loginCode
This will prompt you to open a URL in a browser and complete the login process. Once you have logged in, the browser will display an Authorization Code that the SAS Viya CLI will use to obtain the Access Token and Refresh Token for the shared account. You can then use pyviyatools to store the Refresh Token:
python ~/admin/pyviyatools/modifydomain.py oauth2.0 --name DefaultToken\
--identitytype group \
--identity Finance
This will make the Refresh Token for the shared account you authenticated the SAS Viya CLI with available to the Finance group. So, any users in the Finance group will be able to use the stored Token.
At this stage we have the Token Authentication domain created and at least one Refresh Token for a shared account stored in the Token Authentication domain. However, SAS Compute Server and SAS Cloud Analytic Services will not yet make use of the credential. Both SAS Launcher and SAS Cloud Analytic Services will look in the Authentication domain defined by the sas.compute.domain.default property. The documentation covers changing the default authentication domain using SAS Environment Manager. Or the same change can be performed using the SAS Viya CLI:
mkdir -p ~/custom_JSON
tee ~/custom_JSON/UpdateDomainDefault.json > /dev/null << EOF
{
"name": "updateDomainDefault",
"items": [
{
"version": 1,
"metadata": {
"allowUserProperties": true,
"isDefault": false,
"mediaType": "application/vnd.sas.configuration.config.sas.compute+json;version=1"
},
"domain.default": "DefaultToken"
}
]
}
EOF
sas-viya auth login
sas-viya configuration configurations update --file ~/custom_JSON/UpdateDomainDefault.json
sas-viya auth logout
For SAS Compute Server this completes all the required changes to make use of the shared account. Once the configuration for sas.compute.domain.default has been updated it will be picked up automatically after a couple of minutes. Then, for our example, any members of the Finance group who launch a SAS Compute Server will have the host process running as the shared account. For example, this can be validated in SAS Studio by running the following three statements:
%put &_CLIENTUSERID;
%put &_CLIENTUSERNAME;
%put &SYSUSERID;
The first two macro variables will reference the end-user, while &SYSUSERID will show the shared account.
However, for SAS Cloud Analytic Services a further step is required. SAS Cloud Analytic Services will need to be configured to enable Host Launch sessions. Then any users in our Finance group who request a Host Launch session would use the shared account to launch the SAS Cloud Analytic Services session.
The Refresh Token that has been stored for a shared account will be automatically refreshed each time it is used. This means that so long as the shared account is used at least once before the Refresh Token expires there is no need to manually replace the token. The default lifetime of the Refresh Token is 90 days.
Using shared accounts enables you to configure your environment such that your end-users running both SAS Compute Server and SAS Cloud Analytic Services sessions leverage those shared accounts for host-based access control. The introduction of the Token Authentication domain, and updates to SAS Viya enable this feature to operate in environments with SCIM configured. Previously, this feature was only available when using LDAP as the Identity Provider and with storing a username and password for the shared accounts. The SAS documentation provides details on how to configure shared accounts using SAS Environment Manager, and here we have presented alternative ways to configure the same settings using the SAS Viya CLI and pyviyatools.
It should be noted that this feature is not limited to only operating in SCIM configured environments. The same feature applies in an environment configured with LDAP, and the benefit in an LDAP environment is that the token will automatically refresh. So you would not need to remember to update the password for the shared account when it changes in the LDAP provider.
If you want to explore this topic in more detail, you can refer to Course: Advanced Topics in Authentication on SAS Viya.
Find more articles from SAS Global Enablement and Learning here.
Neat! I do have two questions, which I am sure are simply confusion on my part:
Storing the Refresh Token
With regards to storing the refresh token, how does one do this using the CLI or SAS Environment Manager? Am I misunderstanding the what this code is doing? From looking at the code for modifydomain.py, it looks like it just associates the group or user identity to the token domain.
python ~/admin/pyviyatools/modifydomain.py oauth2.0 --name DefaultToken\
--identitytype group \
--identity Finance
Am I misunderstanding what is really going on? I expected to see the refresh token as another input parameter.
Changing the compute server default domain
In this example, what happens to users who are not in the Finance group? And is there a way for Finance group members to run as themselves as well? Would this be a situation where this default domain maybe should be defined for a separate compute context?
Carl
Are you ready for the spotlight? We're accepting content ideas for SAS Innovate 2025 to be held May 6-9 in Orlando, FL. The call is open until September 25. Read more here about why you should contribute and what is in it for you!
Data Literacy is for all, even absolute beginners. Jump on board with this free e-learning and boost your career prospects.