SAS Viya 2023.07 Run As Authentication Update
SAS Viya Stable release 2023.07 makes a significant change to how the authentication of scheduled jobs and job flows operates when they are configured to run as a specific user. This change requires anyone updating their SAS Viya environment to the 2023.07 or later release to make updates to any existing scheduled jobs and flows that make use of the Run As feature. In this blog we will present the changes that are introduced in SAS Viya 2023.07 and discuss what you need to do when updating to this release or a later one.
Since the SAS Viya 2023.11 release the security posture of SAS Viya has been improved with respect to how Access Tokens are leveraged internally. These Access Tokens are now more closely coupled with the specific application or service that obtains them. As such, from this release it is no-longer possible to use a scheduled job to refresh the Group-Managed Service Account credential.
The New Model
We will start by presenting the new model for how scheduling using the Run As feature is undertaken in SAS Viya 2023.07. A scheduling job can now be defined by a user who does not need to be a member of SAS Administrators to run as another user. However, the jobs and flows can only be run as a group-managed service account, rather than any user who has logged into the SAS Viya environment. A group-managed service account does not have any special privileges or unique features other than it enables a group of users to share responsibility for jobs and job flows. The users who share the responsibility for executing, scheduling, and monitoring jobs and job flows are associated with the group-managed service account by being given access to the Token Authentication Domain created by the group-managed service account.
The following diagram illustrates the parts that make up the new model:
Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.
A member of the SAS Administrators group needs to setup the following:
- Adds the group-managed service account, that must exist in the external Identity Provider, to the automatically created Service Account Users for Schedule custom group.
- Creates a new custom group and adds the end-users who share the responsibility for executing, scheduling, and monitoring jobs and job flows to the group.
A user with access to the credentials for the group-managed service account needs to do the following to prepare the group-managed service account for use:
- Creates a new Token Authentication Domain. This Token Authentication Domain will be used to store the credentials for the group-managed service account. This needs to be created by the group-managed service account to ensure that account can update the credential in future. With SAS Viya 2023.07 the SAS Viya CLI should be used to create the Token Authentication Domain. From SAS Viya 2023.08 and later either the SAS Viya CLI or SAS Environment Manager can be used to create the Token Authentication Domain.
- Store a credential for the group-managed service account in the new Token Authentication Domain and allow access to this credential by the custom group containing the users who will schedule jobs and flows as the group-managed service account. To work with the Jobs and Flows feature, the Restrict applications check box must be selected when adding the credential. This task must be completed in SAS Environment Manager as the group-managed service account.
This last step completed as the group-managed service account, is essentially authorizing the members of the custom group to run jobs and flows as the group-managed service account.
With this complete the members of the custom group can now schedule jobs and flows using the group-managed service account. Details of these steps are covered in the SAS Viya Platform Administration documentation.
Authorization Rules Underpinning the New Model
The Service Account Users for Schedule custom group is created automatically and includes a series of pre-defined authorization rules. Just as with the custom group itself, these authorization rules are automatically defined in the SAS Viya 2023.07 environment. The following four authorization rules are automatically created:
The rules for the Object URIs "/credentials/domains/*/*/*" and "/SASEnvironmentManager/domains" are straight-forward grants of the given permissions. The first allowing the group-managed service account to read, create, update, and delete credentials. Then the second allowing the group-managed service account to access the domains section from within SAS Environment Manager.
The other two authorization rules have conditional grants applied. The first of these for the Object URI "/credentials/domains/*" allow the group-managed service account to create, update, and delete the Token Authentication domains that they have created. Where the condition is:
(currentUser() == #domain?.createdBy) OR (#domain != null AND #domain?.creationTimeStamp == null)
Which means that the permissions of delete, and update are only applied to domains where the user has created the domain, or where the domain does not exist yet. Then for the Object URI "/credentials/domains/*/credentials" the rule will allow the group-managed service account to list the credentials in the domain they have created. Where the condition is:
currentUser() == #domain?.createdBy
It is these four authorization rules applied to the Service Account Users for Schedule custom group that enable the group-managed service account to store a credential and make this credential available to others.
In addition, the Credentials microservice only allows access to the stored secret for the assigned Identity, in this case the Refresh Token. As we described above the assigned Identity in the case of the group-managed service account is the custom group the SAS Administrator has created. This custom group contains the end-users who share the responsibility for executing, scheduling, and monitoring jobs and job flows. So only members of this custom group will be able to access the stored Refresh Token.
Other Permissions
So far, we have only discussed the authorization required for the jobs and job flows to be scheduled as the group-managed service account. In addition to this, the group-managed service account will also require the authorizations and permissions to complete the tasks in the scheduled job or job flow. If the job or job flow accesses other SAS Viya services, the group-managed service account will require the authorization to interact with these services. For example, if the job will write content to the Folders microservice the group-managed service account will require authorization to the folder location. Equally, if the job or job flow will access data in a caslib, the group-managed service account will require the authorization to access the given caslib.
These authorizations and permissions for the group-managed service account may also extend beyond the SAS Viya environment to the underlying data sources whether those are file system directories or databases. For credentials needed to access the databases, these can be stored in an Authentication Domain and only the group-managed service account will require access to them. This means that you do not need to make those database credentials available to the users scheduling the job or job flow as the group-managed service account.
Example
Next, we will look at an example to hopefully make these concepts easier to apply to your own environment. Let’s say that our SAS Viya environment is shared between the Sales and HR departments. Delilah is a data administrator in the HR department and needs to be able to schedule regular jobs to process HR data. The other members of the HR department need to be able to monitor the jobs Delilah has scheduled. While Douglas is a data administrator in the Sales department, and he needs to be able to schedule jobs to process the Sales data. Again, the other members of the Sales department also need to monitor the jobs that Douglas has scheduled.
In our example organization we then create two users who will be running the scheduled jobs and flows for the two departments. We will call these users scheduler-sales and scheduler-hr. These two users must exist in our external Identity Provider, whether that is an LDAP Provider or SCIM Provider and these two users must be able to log into SAS Viya. It does not matter how the users log in; authentication could use any supported mechanism such as LDAP, OpenID Connect, or SAML.
George, a member of SAS Administrators logs into SAS Environment Manager and opts in to the SAS Administrator role. George, as a SAS Administrator, then completes the following:
- Adds the scheduler-sales user and scheduler-hr user to the Service Account Users for Schedule custom group.
- Creates a new custom group called Scheduling HR and adds Delilah and other members of the HR department as members.
- Creates a new custom group called Scheduling Sales and adds Douglas and other members of the Sales department as members.
Delilah, knowing the credentials for the scheduler-hr account, now completes the following as the scheduler-hr user:
- Creates a new Token Authentication Domain called Scheduling_HR_TokenAuth
- If using SAS Viya 2023.07 this is performed using the SAS Viya CLI
- If using SAS Viya 2023.08 and later this can be performed either in SAS Environment Manager or using the SAS Viya CLI
- Uses SAS Environment Manager to store a new credential on the Scheduling_HR_TokenAuth domain and assigns this credential to the custom group Scheduling HR. To work with the Jobs and Flows feature, the Restrict applications check box must be selected when adding the credential.
Douglas, knowing the credentials for the scheduler-sales account, now completes the following as the scheduler-sales user:
-
- Creates a new Token Authentication Domain called Scheduling_SALES_TokenAuth
- If using SAS Viya 2023.07 this is performed using the SAS Viya CLI
- If using SAS Viya 2023.08 and later this can be performed either in SAS Environment Manager or using the SAS Viya CLI
- Creates a new Token Authentication Domain called Scheduling_SALES_TokenAuth
Uses SAS Environment Manager to store a new credential on the Scheduling_SALES_TokenAuth domain and assigns this credential to the custom group Scheduling Sales. To work with the Jobs and Flows feature, the Restrict applications check box must be selected when adding the credential.
With this complete Delilah and Douglas can log into SAS Environment Manager as themselves and now schedule jobs and job flows as their respective group-managed service accounts. In addition, the other members of their departments will also be able to monitor the jobs the two of them have scheduled within SAS Environment Manager. However, remember the scheduler-sales and scheduler-hr users will not be able to access other SAS Viya services and data sources until they are granted the authorizations and permissions to do so.
What Happens when Upgrading to SAS Viya 2023.07 and later
When a SAS Viya platform deployment is upgraded to release 2023.07 or later, the prior Run As function is removed and the group-managed service account function becomes available. See the SAS Viya Platform Administration documentation for further details. Essentially, when your SAS Viya environment is updated to release 2023.07 or later you have the following choices:
- Update the existing jobs to use the group-managed service account feature.
- Leave existing scheduled jobs as is.
To update the jobs, you will first need to unscheduled the existing job, then you need to configure a group-managed service account, and then the job can be rescheduled. You could complete all steps with a single account if they are both a member of SAS Administrators and a member of the custom group associated with the group-managed service account Token Authentication domain. Otherwise, a member of SAS Administrators could unscheduled the job and a different user, from our example above either Delilah or Douglas, could then reschedule the job.
If you do not want to update the scheduled job requests that use the prior Run As functionality, you have these choices:
- Leave the existing scheduled job as is. Then have a member of SAS Administrators or the creator monitor the status of the scheduled job. The scheduled jobs and flows will continue to run under the original Run As user. If the schedule needs to be updated, you will need to configure a group-managed service account.
- Alternatively, rather than updating the scheduled job you could simply recreate the scheduled job using a group-managed service account. A member of SAS Administrators would be able to unscheduled the existing job and delete the job definition, after it has been recreated.
Refresh Token Lifetime
The Refresh Token stored by the group-managed service account will by default expire after 90 days. The Refresh Token is embedded in the schedule information and an automated process updates the embedded Refresh Token every seven days. Embedded Refresh Tokens are only replaced if they are within 45 days of their expiry. However, this process does not replace the Refresh Token stored with the Credentials microservice. You could address the expiry of the Refresh Token stored with the Credentials microservice in the following ways:
- You could manually authenticate to SAS Environment Manager as the group-managed service account and edit the stored credential to replace it.
- You could schedule a job to run every 30 days to replace the Refresh Token stored with the Credentials microservice.
- You could extend the default lifetime of Refresh Tokens within the SAS Viya environment. The properties policy.refreshTokenValiditySeconds and policy.global.refreshTokenValiditySeconds under sas.logon.jwt define these lifetimes. This process is covered in the SAS Viya Platform Administration documentation.
Since the SAS Viya 2023.11 release the security posture of SAS Viya has been improved with respect to how Access Tokens are leveraged internally. These Access Tokens are now more closely coupled with the specific application or service that obtains them. As such, from this release it is no-longer possible to use a scheduled job to refresh the Group-Managed Service Account credential. The example below will only work for SAS Viya releases prior to 2023.11.
We will explore this second option here . For the group-managed service account to be able to replace the Refresh Token with the Credentials microservice inside a scheduled job it will need to be added to the custom group assigned to the stored credential. Since the Credentials microservice will only allow access to the secret (i.e. the Refresh Token) to the Identity assigned to it. You would then create a scheduled job with the following SAS code:
options set=myToken="%sysget(SAS_CLIENT_TOKEN)";
%let ViyaIngress=%sysfunc(getoption(SERVICESBASEURL));
filename resp temp;
PROC HTTP
url="&ViyaIngress./credentials/domains/{REPLACE_WITH_TOKEN_AUTH_DOMAIN}/secrets"
method='GET'
OAUTH_BEARER="%sysget(SAS_CLIENT_TOKEN)"
out=resp
query = ("lookupInGroup"="true"
"client_id"="sas.jobExecution");
run;
/*
data _null_;
infile resp;
input;
put _infile_;
run;
*/
filename resp clear;
If you get an error running the code, you can uncomment the data step at the end of the code. This will print the entire response to the log of the scheduled job, and you can investigate the error further.
You can validate that the credential has been replaced by checking the modified date for the credential, which can be viewed by either the group-managed service account or members of SAS Administrators in SAS Environment Manager.
Other Considerations
Finally, a couple of other items to consider with the new model for the Run As feature. First, being a member of the SAS Administrators group no-longer provides the ability to use the Run As feature. A member of the SAS Administrators group is still able to view the execution history, but without being a member of one of the custom groups giving access to the group-managed service account the Run As feature cannot be used.
Second, if a user is a member of multiple custom groups providing access to different group-managed service accounts they will be able to execute, schedule, and monitor jobs and job flows for any of the group-managed service accounts. So, looking again at our example if we add the user Alex to both Scheduling HR and Scheduling Sales groups. Then Alex in SAS Environment Manager will be presented with both group-managed service accounts in the Monitoring screen. Alex will be able to select either of the group-managed service accounts in the View as property as shown here:
When Alex selects one of the group-managed service accounts, he will then be able to see the execution history for that account. Equally, Alex will be able to select either of the group-managed service accounts when using the Run As feature. However, Alex will not be able to see the job created by either Delilah or Douglas, because Alex is not a SAS Administrator, and he did not create those jobs.
If it is necessary to edit the schedule or unscheduled the jobs created by Delilah or Douglas, then either Alex must be added to SAS Administrators. Or a custom authorization rule will be required to give Alex access to the jobs created by Delilah or Douglas. In general terms you can only maintain jobs and job flows if you are a SAS Administrator, creator, or a custom authorization rule has been defined. Where maintain means; edit the schedule, unschedule, delete the job, copy the job, edit the job flow, view the job flow, and delete the job flow.
Conclusion
As we have seen the introduction of group-managed service accounts makes the Run As feature with SAS Viya 2023.07 and later more secure and much easier to securely open to a wider group of users. The technical parts might initially seem a bit confusing, but the general premise of logging into SAS Viya as the account that will run the scheduled jobs and authorizing that other specific users can use that account to run the scheduled jobs and flows makes a great deal of sense. There can be some initial effort to reschedule existing jobs when updating to SAS Viya 2023.07 and later, but the improved functionality makes this worthwhile.
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.
