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 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. ... View more

In the last post we discussed defining a custom application within SAS Viya and using the client_credentials grant type to authenticate. One of the use cases we presented in that post was connecting from SAS 9.4 to SAS Viya. I want to explore this use case in more detail in this post. As such, we will define a new custom application with SAS Logon Manager in SAS Viya and use the client_credentials grant type to obtain an Access Token. We will then use this Access Token to connect from SAS 9.4 to SAS Viya. This use case is a good fit for SAS 9.4 batch sessions that need to interact with SAS Viya when the end-user for the SAS 9.4 batch session does not exist in the Identity provider of our SAS Viya environment. Which could easily be the case when our SAS 9.4 environment is running on-premises and our SAS Viya environment is running in the cloud with more modern cloud-native Authentication and Identity providers such as OpenID Connect and SCIM.   Defining the Custom Application   To be able to register the custom application with SAS Logon Manager you need to first obtain an Access Token as a member of the SAS Administrators group. You can do this by calling the SAS Logon Manager API. Or you can obtain an Access Token using the SAS Viya CLI.   Once you have this Access Token you can register the custom application using the following call to the SAS Logon Manager API:   curl -k -X POST "${INGRESS_URL}/SASLogon/oauth/clients" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $BEARER_TOKEN" \ -d '{ "client_id": "cust1.app", "client_secret": "myclientsecret", "scope": ["uaa.none"], "authorities": ["CustomApps"], "authorized_grant_types": ["client_credentials"], "access_token_validity": 900 }'   Note: You should specify a complex random string as the client_secret, a simple value is shown here to make the examples easy to read.   You should see something like the following for a successful response, we have split this output onto multiple lines to make it easier to read:   {"scope":["uaa.none"], "client_id":"cust1.app", "resource_ids":["none"], "authorized_grant_types":["client_credentials"], "autoapprove":[], "access_token_validity":900, "authorities":["CustomApps"], "lastModified":1673609094057, "required_user_groups":[]}   Notice that the authorized_grant_types only include client_credentials; this means that this client will never be able to obtain an Access Token for an end-user. Since this custom application will never obtain credentials for an end-user we have also set the scope to uaa.none. In addition, for our example the access_token_validity has been set to 900, which is 10 minutes, so we will need to reauthenticate every 10 minutes. You can define the access_token_validity to whatever value makes sense for your custom application, the value is the number of seconds that the Access Token will be valid for.   When using the client_credentials grant the authorities will represent the custom group, so our custom application will be in the CustomApps custom group.   You can then refer to the previous post if you need to update or delete the custom application.   Obtaining the Access Token   You could obtain the Access Token for the custom application by directly calling the SAS Logon Manager API outside of your SAS 9.4 environment and then provide this as a file to be used by the SAS 9.4 code. For example, you could obtain the Access Token using CURL with the following:   APP_TOKEN=`curl -skX POST "${INGRESS_URL}/SASLogon/oauth/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -u 'cust1.app:myclientsecret' \ -d 'grant_type=client_credentials' |jq -r '."access_token"'`; \ echo "Custom Application Access Token is: ${APP_TOKEN}"   You should see something like the following:   Custom Application Access Token is: eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbG9jYWxob3N0L1NBU0xvZ29uL3Rva2VuX2tleXMiLCJraWQiOiJsZWdhY3ktdG9rZW4ta2V5IiwidHlwIjoiSldUIn0. eyJqdGkiOiI1MWMyYWEzYTMyY2E0MTI1OGM1OTUxZGM4NmEwYzk2OSIsInN1YiI6ImN1c3QxLmFwcCIsImF1dGhvcml0aWVzIjpbIkN1c3RvbUFwcHMiXSwic2NvcGUiOlsiQ3VzdG9tQXBwcyJdLCJjbGllbnRfaWQiOiJj dXN0MS5hcHAiLCJjaWQiOiJjdXN0MS5hcHAiLCJhenAiOiJjdXN0MS5hcHAiLCJncmFudF90eXBlIjoiY2xpZW50X2NyZWRlbnRpYWxzIiwicmV2X3NpZyI6IjY3N2U2YWI0IiwiaWF0IjoxNjc0NTc4NjUwLCJleHAiOjE2 NzQ2NjUwNTAsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3QvU0FTTG9nb24vb2F1dGgvdG9rZW4iLCJ6aWQiOiJ1YWEiLCJhdWQiOlsiY3VzdDEuKiIsImN1c3QxLmFwcCJdfQ.ULMvGUBnQh_c3SnZCds0ePdq9le8KOcxtUZ2l S398Fkqmu7cusU46IBFenqsSNYr1OlA5Z1eZT0qaSQQLiWeYVphyXq8EQv0YwLLW0_CaQN-rlhZvf-Thg0H-AmPpL-OFU08GQ8m8g6UboO4KZPR-e17P2qKBo18Rc8QvE2B1hcf-tbod0AN5Q62MkqLBTTajmnxNep4qJ1YP 0b6RhnnoriZsxN_PMm1Wytolq4UU69t0Drmn9s4brrPECG00FNaKV3TWkuwvqzJXB352doZ2-s8NVARELmqyZb5WdzYPL_5GkHsDAlZ76Dt3JBGlvnGWtZEdO9O_2ocH7GispCwTA   Alternatively, you could obtain the Access Token inside the SAS code that will be making connections to your SAS Viya environment. This requires that you have network connectivity to the Ingress Controller for your SAS Viya environment. For example, you could create a new group in the SAS 9.4 Metadata, for example "Viya Service Users", and assign the client_id and client_secret as credentials in a new authentication domain. The SAS 9.4 Authentication Domain would be configured for Outbound only.   Select any image to see a larger version. Mobile users: To view the images, select the "Full" version at the bottom of the page.   Then any of your SAS 9.4 users who will need to obtain an Access Token for the custom application would be added to this new group, for example "Viya Service Users".   You can then create a SAS Macro which will obtain the Access Token using the credentials from the SAS 9.4 Authentication Domain. You could place something like the following code into a file called get_custom_token.sas:   %macro get_custom_token(webauthdomain=); %global custom_token; %let ViyaIngress=%sysfunc(getoption(SERVICESBASEURL)); filename resp temp; PROC HTTP url="&ViyaIngress./SASLogon/oauth/token" in="grant_type=client_credentials" ct="application/x-www-form-urlencoded" method='POST' WEBAUTHDOMAIN="&webauthdomain" AUTH_BASIC out=resp; run; %put &=SYS_PROCHTTP_STATUS_CODE; libname auth json fileref=resp; data _null_; set auth.root; call symputx('custom_token',access_token); run; filename resp clear; %put &=custom_token; %mend;   For more information on PROC HTTP see the documentation. The PROC HTTP statement is performing a HTTP POST to SAS Logon Manager in SAS Viya using the credentials from the authentication domain in SAS 9.4. This returns the Access Token for the custom application in the JSON response which is then processed to extract the Access Token and make it available as a global variable. If the macro was placed in a directory such as /opt/sas/macros, you can make this available by using the following either in you SAS Code:   options insert=(sasautos=('/opt/sas/macros'));   Or in the sasv9_usermods.cfg:   -insert sasautos '/opt/sas/macros'   For more details on the INSERT System Option see the documentation.   Notice, that to make the code in the macro as portable as possible we have used the SERVICEBASEURL System Option. The SERVICEBASEURL System Option specifies the root URL for calls to SAS Viya Services. The SERVICEBASEURL is only valid in the SAS 9.4 configuration file, SAS invocation, or SASV9_OPTIONS environment variable (UNIX only). You cannot specify the SERVICEBASEURL System Option inside a running SAS 9.4 session. Also, the SERVICEBASEURL option can be restricted by a site administrator. For more information, see Restricted Options.   With the macro defined, the SAS 9.4 configuration file updated to include the SERVICEBASEURL and addition to the sasautos, and the group defined in the SAS 9.4 Metadata,for example "Viya Service Users"; we can then call the macro with the following:   %get_custom_token(webauthdomain=ViyaCustomClient);   So long as we have network connectivity between SAS 9.4 and the Ingress Controller for the SAS Viya environment, we should see the Access Token displayed in the SAS 9.4 log. If we want to remove showing the Access Token in the log, we will just remove the final %put statement in the macro code shown above. If there is an issue with the network connectivity the macro will run until the connection times out and the message "ERROR: Unable to connect to Web server" will be returned.   Accessing SAS Viya Services   Now that the Access Token is available to the SAS 9.4 session, this session can interact with the SAS Viya services as the custom application. For example, PROC HTTP can be used to call the SAS Viya REST APIs. Specifically, using the OAUTH_BEARER option sends the Access Token along with the HTTP call. To demonstrate this, the following code calls the Folders service and obtains the top-level links:   %let ViyaIngress=%sysfunc(getoption(SERVICESBASEURL)); filename resp temp; PROC HTTP url="&ViyaIngress./folders/folders/" method='GET' OAUTH_BEARER="&custom_token." out=resp; run; data _null_; infile resp; input; put _infile_; run; filename resp clear;   This is just a very simple example of what can be done by calling the SAS Viya services.   If you have assigned a credential in the SAS Viya DefaultAuth Authentication Domain, then the custom application will be able to launch a SAS Compute Server instance in SAS Viya. This requirement to provide a credential for launching the SAS Compute Server was discussed in the previous post. The following example code uses PROC HTTP to do the following:   Find the Compute Context ID for the SAS Studio compute context. Uses the Compute Context ID to launch a SAS Compute Server session. Submits some sample code to the SAS Compute Server session. Returns the listing for the SAS Compute Server job once it completes. Terminates the SAS Compute Server session.   %let ViyaIngress=%sysfunc(getoption(SERVICESBASEURL)); filename resp temp; PROC HTTP url="&ViyaIngress./compute/contexts?filter=eq(createdBy,'sas.studio')" ct="application/x-www-form-urlencoded" method='GET' OAUTH_BEARER="&custom_token." out=resp; run; libname output json fileref=resp; data _null_; set output.items; call symput('my_contextID',id); run; filename resp clear; libname output clear; filename resp temp; PROC HTTP url="&ViyaIngress./compute/contexts/&my_contextID/sessions" ct="application/vnd.sas.compute.session.request+json" method='POST' OAUTH_BEARER="&custom_token." in='{"version": 1,"name": "MySession","description": "This is my session for doing some simple work.","attributes": {},"environment": {"options": ["memsize=4g","fullstimer"]}}' out=resp; run; libname output json fileref=resp; data _null_; set output.root; call symput('my_ComputeSessionID',id); run; filename resp clear; libname output clear; filename resp temp; PROC HTTP url="&ViyaIngress./compute/sessions/&my_ComputeSessionID/jobs" ct="application/vnd.sas.compute.job.request+json" method='POST' OAUTH_BEARER="&custom_token." in='{"version": 2,"name": "MyOptions","description": "Getting the options for my session.", "code": ["proc print data=sashelp.class;","run;","%put &SYSUSERID;","cas mysession;", "proc cas; action listnodes result=res;print res;run;","data _null_;call sleep(10,1); run;", "cas mysession terminate;"],"attributes": {"resetLogLineNumbers": false}}' out=resp; run; libname output json fileref=resp; data _null_; set output.root; call symput('my_jobID',id); run; filename resp clear; libname output clear; filename resp temp; PROC HTTP url="&ViyaIngress./compute/sessions/&my_ComputeSessionID/jobs/&my_jobID/state?wait=60" ct="application/vnd.sas.compute.job.request+json" method='GET' OAUTH_BEARER="&custom_token." out=resp; headers "If-None-Match"="completed"; run; data _null_; infile resp; input; put _infile_; run; filename resp clear; filename resp temp; PROC HTTP url="&ViyaIngress./compute/sessions/&my_ComputeSessionID/jobs/&my_jobID/listing" ct="application/vnd.sas.compute.job.request+json" method='GET' OAUTH_BEARER="&custom_token." out=resp; run; libname output json fileref=resp; proc print data=output.items; var line; run; filename resp clear; libname output clear; filename resp temp; PROC HTTP url="&ViyaIngress./compute/sessions/&my_ComputeSessionID" ct="application/vnd.sas.compute.job.request+json" method='DELETE' OAUTH_BEARER="&custom_token." out=resp; run; filename resp clear;   This demonstrates what can be easily achieved once the Access Token is available to the SAS 9.4 session. This code sample was produced based on the examples provided at https://developer.sas.com.   Accessing SAS Cloud Analytic Services   As well as interacting with the SAS Viya services the SAS 9.4 session can use the Access Token to directly interact with SAS Cloud Analytic Services. So long as the SAS 9.4 environment is running maintenance release 5 or higher the CAS client is built into SAS 9.4. Leveraging the Access Token with the CAS client requires the following: SAS Cloud Analytic Services in SAS Viya must be configured to allow external access SAS 9.4 must have the SERVICEBASEURL system option defined which must be defined outside the session SAS 9.4 must have the SAS_VIYA_TOKEN environment variable defined which can be defined inside the session   The SAS_VIYA_TOKEN environment variable can be defined either during SAS invocation, or during the session with an OPTIONS statement. For example, using the following allows us to set the value of SAS_VIYA_TOKEN to the Access Token obtained using the macro code given above:   options set=SAS_VIYA_TOKEN="&custom_token";   The SERVICEBASEURL system option is required since the CAS client in SAS 9.4 will pre-validate the Access Token before attempting to use it. To pre-validate the Access Token the CAS client will obtain the public key from SAS Logon Manager in SAS Viya. The public key is used to validate the signature on the Access Token. If network connectivity is not correctly configured to allow SAS 9.4 to access the SERVICEBASEURL the CAS client will error and the connection to SAS Cloud Analytic Services will not be attempted. In such case, the only error will be presented in the SAS 9.4 session. There will be no error in the SAS Cloud Analytic Services logs since the connection is never attempted.   Putting all these parts together means that we can launch a CAS session using the custom application from a SAS 9.4 session with the following code:   %get_custom_token(webauthdomain=ViyaCustomClient); options set=CASCLIENTDEBUG=1; options set=CAS_AUTH_METHOD=oauth; options set=SAS_VIYA_TOKEN="&custom_token"; cas mysession host="SAS_VIYA_LOADBALANCER_HOSTNAME" port=5570 ;   Which will result in the following information in the SAS 9.4 log, since the CASCLIENTDEBUG is set to 1:   NOTE: The session MYSESSION connected successfully to Cloud Analytic Services SAS_VIYA_LOADBALANCER_HOSTNAME using port 5570. The UUID is 6939b748-9ec3-3d42-9c83-5c6ebfabc45e. The user is cust1.app and the active caslib is CASUSER(cust1.app). NOTE: The SAS option SESSREF was updated with the value MYSESSION. NOTE: The SAS macro _SESSREF_ was updated with the value MYSESSION. NOTE: The session is using 2 workers. NOTE: Forcing oauth authentication. NOTE: Client is using the oauth identity provider NOTE: Sent challenge length 968 NOTE: Received response length 57 NOTE: User cust1.app connected to CAS using OAuth 2.   This shows that we have successfully launched a SAS Cloud Analytic Services session as the custom application from the SAS 9.4 session.   Conclusion   In this post we have delved into more details on the specific use case of connecting to SAS Viya from SAS 9.4 using an Access Token for our custom client. This scenario is a good fit for SAS 9.4 batch sessions that need to interact with SAS Viya when the end-user for the SAS 9.4 batch session does not exist in the Identity provider of our SAS Viya environment. Which could easily be the case when our SAS 9.4 environment is running on-premises and our SAS Viya environment is running in the cloud with more modern cloud-native Authentication and Identity providers such as OpenID Connect and SCIM.   In the post we have presented a methodology for obtaining the Access Token without needing to set an extreme lifetime for the Access Token. Using an Authentication Domain in SAS 9.4 to hold the client_id and client_secret means that an Access Token can be obtained only by the designated users and only when necessary. This means that we do not leave an Access Token exposed for more time than it is needed. It also means that it is easier for whoever is administrating the environments to update the client_secret.   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. ... View more

Creating a custom client or application of SAS Logon Manager is normally used to allow end-users to authenticate with the new application and perform actions. This could be a custom script or your own application you are integrating with SAS Viya. In this blog I want to explore what can be done with the custom client application of SAS Logon Manager itself. So, in this case we will be using the client_credentials grant rather than the authorization_code or password grant types. This is not the standard approach. The standard approach would be to ensure all end-users and service accounts are correctly configured in your Identity and Authentication provider. These end-user and service accounts would then be the parties that run code or processes. However, in this case it will be the custom application that runs code or process outside the context of any specific user and often (but not always) outside of any user request.   A Reminder: Grant Types   SAS Logon Manager supports authorization_code, client_credentials, refresh_token, and password as valid grant_types. The grant_type defines the process that will be used to obtain an Access Token from SAS Logon Manager. The authorization_code grant requires the end-user to authenticate in their browser and return the code to the client to then exchange for the Access Token for the end-user. Examples of this flow are the standard login to the SAS Viya web applications and the SAS Viya CLI with the command auth loginCode. The client_credentials grant obtains an Access Token just for the custom application and not for the end-user, it uses the client_secret registered with SAS Logon Manager when the custom application was defined. The refresh_token grant obtains the Access Token by presenting an existing valid Refresh Token. Then the password grant uses the end-user username and password to authenticate to SAS Logon Manager and obtain the Access Token for the end-user. Remember the password grant is only applicable if an LDAP Provider is configured for your SAS Viya environment.   Use Cases   Before we dive into further details it is useful to understand some use cases when operating as the custom application using the client_credentials grant is appropriate or required. The first use case is specific to the internal services within the SAS Viya environment. As the different services and applications that make up the SAS Viya environment bootstrap, they need to create authorization rules, define their configurations etc. Internal SAS Viya services and applications during bootstraping leverage the client_credentials grant to allow them to complete this process. Another use case is application-to-application interfaces such as SCIM. The SCIM client, perhaps Azure Active Directory, needs to authenticate to SAS Viya to provision the users and groups. The SCIM client presents an Access Token to authenticate this connection.   Other use cases are more specific to your own usage of the SAS Viya environment. Perhaps you have an on-prem SAS 9.4 environment that needs to connect to SAS Cloud Analytic Services as part of an ETL process. The ETL process is part of your standard batch processing, and a corresponding end-user does not exist in your cloud-based SAS Viya environment. As such you want to configure a custom application on the SAS Viya side and authenticate as this for the connection to SAS Cloud Analytic Services.   Alternatively, you might have an external application that presents generalized modelling results. You want to be able to regularly connect to SAS Viya run a model in SAS Cloud Analytic Services and return the results to the external application. Since this is a regular process that runs unattended you do not want to run this in the context of a specific end-user. So again, you want to run this as a custom application registered with SAS Logon Manager.   Authentication and Authorization   Using the client_credentials grant results in an Access Token for the custom application and not an end-user. Once an Access Token has been obtained SAS Viya at the most basic level does not distinguish between how the Access Token was obtained. Access Tokens obtained with client_credentials do not contain any user claims, so the client ID in the Access Token will be accepted as the authenticated principal name. This is for all practical purposes treated like a username. This means that any connection providing a valid Access Token will be as an "Authenticated User". Most SAS Viya APIs do not distinguish between user and client Access Tokens. However, some services will inspect the Access Token itself to see if it is an end-user or a custom application that is connecting and presenting the Access Token. These services will inspect the Access Token looking for user specific claims which are not present when the Access Token is obtained using the client_credentials grant.   Authorization requires one of the following: A rule granting access to the endpoint to "Everyone". A rule granting access to the endpoint for all "Authenticated Users", where "users" in this context includes custom applications. A rule granting access to a User principal where the principal name is the client ID. A rule granting access to a Group principal where the custom application is registered with the Group in its list of authorities.   Within SAS Environment Manager only the Rules page will allow you to type the client ID to define authorization rules that will apply to your custom application. In other authorization screens, such as CAS authorization, or Folder’s authorization, you are only able to select Users, Groups, and Custom Groups as provided by the Identities microservice. Therefore, it is not possible to assign direct permissions to your ClientID to say a folder or a caslib. Instead, you need to create a Custom Group for your custom applications and assign authorization information to the Custom Group. For the examples in this blog, we will create a Custom Group with the name and ID of CustomApps. Then we can apply authorization information to the CustomApps group, for example allowing access to the Public folder:     Select any image to see a larger version. Mobile users: To view the images, select the "Full" version at the bottom of the page.    Adding a Custom Application to a Custom Group   Adding a custom group to a custom application is very straightforward. When the custom application is registered, the authorities parameter defines a list of the groups that will be present in the Access Token obtained when using the client_credentials grant. So, all you need to do is include the group ID for your custom group in the authorities parameter when you register your custom application.   Registering an Example Custom Client   Now we can create our custom client application to SAS Logon Manager. There are two ways to register the custom application, you can either use the SAS Viya CLI or you can manually register the custom application by calling the SAS Logon Manager APIs. Here we will demonstrate manually registering the custom application. To register the custom application, you need to obtain an Access Token from SAS Logon Manager as a member of the SAS Administrators group. For example, the following could be used to obtain a token for the sasadm user, who is a member of the SAS Administrators group:   export BEARER_TOKEN=`curl -sk -X POST \ "${INGRESS_URL}/SASLogon/oauth/token" \ -u "sas.cli:" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d 'grant_type=password&username=sasadm&password={{myPassword}}' | awk -F: '{print $2}'|awk -F\" '{print $2}'`   Where you replace {{myPassword}} with the password for the sasadm user. The same could be used for any other member of SAS Administrators if you have an LDAP Provider defined. Otherwise, if your environment is configured for SCIM you could use the SAS Viya CLI to obtain the initial Access Token using the auth loginCode command. You could then extract the Access Token from the credentials.json file.   This token will then enable you to register your custom application:   curl -k -X POST "${INGRESS_URL}/SASLogon/oauth/clients" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $BEARER_TOKEN" \ -d '{ "client_id": "cust1.app", "client_secret": "myclientsecret", "scope": ["uaa.none"], "authorities": ["CustomApps"], "authorized_grant_types": ["client_credentials"], "access_token_validity": 900 }'   Note: You should specify a complex random string as the client_secret, a simple value is shown here to make the examples easy to read.   You should see something like the following for a successful response, we have split this output onto multiple lines to make it easier to read:   {"scope":["uaa.none"], "client_id":"cust1.app", "resource_ids":["none"], "authorized_grant_types":["client_credentials"], "autoapprove":[], "access_token_validity":900, "authorities":["CustomApps"], "lastModified":1673609094057, "required_user_groups":[]}   Notice that the authorized_grant_types only include client_credentials; this means that this client will never be able to obtain an Access Token for an end-user. Since this custom application will never obtain credentials for an end-user we have also set the scope to uaa.none. In addition, for our example the access_token_validity has been set to 900, which is 10 minutes, so we will need to reauthenticate every 10 minutes. You can define the access_token_validity to whatever value makes sense for your custom application, the value is the number of seconds that the Access Token will be valid for.   When using the client_credentials grant the authorities will represent the custom group, so our custom application will be in the CustomApps custom group.   Updating an Example Custom Client   If you need to change the details of the custom client, perhaps to change the client secret or to change the access_token_validity you can again use the SAS Logon Manager API. As with registering you will need to have an Access Token as a member of SAS Administrators. For example, to update the client secret of our already registered custom application we would use the following command:   curl -k -X PUT "${INGRESS_URL}/SASLogon/oauth/clients/cust1.app" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $BEARER_TOKEN" \ -d '{ "client_id": "cust1.app", "client_secret": "myclientsecret1234", "scope": ["uaa.none"], "authorities": ["CustomApps"], "authorized_grant_types": ["client_credentials"], "access_token_validity": 900 }'   You should see something like the following for a successful response, we have split this output onto multiple lines to make it easier to read:   {"scope":["uaa.none"], "client_id":"cust2.app", "resource_ids":["none"], "authorized_grant_types":["client_credentials"], "autoapprove":[], "access_token_validity":900, "authorities":["CustomApps"], "lastModified":1673610132049, "required_user_groups":[]}   Deleting/Unregistering an Example Custom Client   Finally, if you want to remove the registration for your custom application you would use the SAS Logon Manager API again. As with registering you will need to have an Access Token as a member of SAS Administrators. For example, to delete our custom application we would use the following command:   curl -k -X DELETE "${INGRESS_URL}/SASLogon/oauth/clients/cust1.app" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $BEARER_TOKEN"   You should see something like the following for a successful response, we have split this output onto multiple lines to make it easier to read:   {"scope":["uaa.none"], "client_id":"cust2.app", "resource_ids":["none"], "authorized_grant_types":["client_credentials"], "autoapprove":[], "access_token_validity":900, "authorities":["CustomApps"], "lastModified":1673610132049, "required_user_groups":[]}   Then use the following command to check there is no output:   curl -k "${INGRESS_URL}/SASLogon/oauth/clients/cust1.app" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $BEARER_TOKEN"   Custom Applications and Credentials Microservice   The Credentials microservice inspects the Access Token when deciding if the secret that is stored can be accessed. When the Access Token has the grant_type of client_credentials the Credentials microservice identifies the caller as a client and not an end-user, since there are no user scopes within the Access Token. The credentials microservice uses three types of identity: Identity Type = User Identity Type = Group Identity Type = Client   Within SAS Environment Manager credentials can be managed for Users and Group. However, credentials for Clients cannot be managed in SAS Environment Manager. Therefore, it makes sense to register the custom application as a member of a custom group so that credentials can be easily managed for that custom application. These credentials could be a user and password in a Password Authentication Domain, a token credential in a Token Authentication Domain, or an encryption key in an Encryption Domain.   If we store credentials in either a Password Authentication Domain or a Token Authentication Domain, these can be used by the Launcher microservice when launching a SAS Compute Server pod. So, the SAS Compute Server pod will run with this credential. Remember, by default the Launcher microservice will look in the DefaultAuth Password Authentication Domain. But this can be changed by editing the sas.compute.domain.default property. If we don’t store a credential, then the Launcher microservice will prevent the SAS Compute Server pod from being launched.   You can then validate that the ClientID has access to the stored credential by performing a GET request on /credentials/domains/{domainID}/secrets and presenting the Access Token for the custom application as the Bearer Token. If this returns the credentials, then it is setup correctly.   Client Credentials and SAS Cloud Analytic Services   SAS Cloud Analytic Services inspects the Access Token when launching the CAS session. Since the Access Token contains grant_type=client_credentials SAS Cloud Analytic Services recognises that this is a client application and with TRACE logging will display the messages:   DEBUG 2022-12-02 12:02:04.736 +0000 [cas-shared-default] - REST authentication request DEBUG 2022-12-02 12:02:04.736 +0000 [cas-shared-default] - oauthAuthenticate(): Validating token. DEBUG 2022-12-02 12:02:04.737 +0000 [cas-shared-default] - Service request: cust1.app TRACE 2022-12-02 12:02:04.737 +0000 [cas-shared-default] - Oauth token zid: uaa TRACE 2022-12-02 12:02:04.737 +0000 [cas-shared-default] - Identity is service account   As such, the CAS session will always run as the CAS service account. The session can never be host-launched and credentials in the authentication domain given by the sas.compute.domain.default property cannot be used to launch the CAS session. Once running, the CAS session can be leverage both authentication and encryption domains to access data.   Client Credentials and Launcher Service   The Launcher service will launch SAS Compute pods for the custom client. The Launcher service recognises that the Identities microservice will not generate a UID and GID for the grant_type=client_credentials. As such by default the Launcher will look for the reserved sasapp in the authorities, which means that the client is part of the SAS Viya environment. If it is part of the SAS Viya environment the SAS Compute Server pod runs with the default user, which is sas. Otherwise, for custom applications that do not have the reserved sasapp in the authorities, the Launcher service attempts to look-up credentials in the authentication domain given by the sas.compute.domain.default property for launching the SAS Compute Server pod. If there is no stored credential launching the SAS Compute Server pod will fail.   Therefore, if you associate a credential with the Custom Group your custom application is a member of, the Launcher service will use those to launch the SAS Compute Server pod. This can be validated by examining the debug logging for the Launcher service, which for example will show:   DEBUG 2022-12-01 16:03:28.519 +0000 [launcher] - Getting credential supplier: credentialType=USER_LAUNCH [0:USER_LAUNCH] DEBUG 2022-12-01 16:03:28.519 +0000 [launcher] - Checking if host credential is required: user=cust1.app operatingSystem=linux [0:cust1.app 1:linux] DEBUG 2022-12-01 16:03:28.519 +0000 [launcher] - Host credential not required: user=cust1.app operatingSystem=linux reason=["Operating system is linux.", "sas.compute.kerberos.enabled property is set to false."] [0:cust1.app 1:linux 2:["Operating system is linux.", "sas.compute.kerberos.enabled property is set to false."]] DEBUG 2022-12-01 16:03:28.519 +0000 [launcher] - Found authentication domain: user=cust1.app authenticationDomain=DefaultAuth [0:cust1.app 1:DefaultAuth] DEBUG 2022-12-01 16:03:28.519 +0000 [launcher] - Searching for OAuth2 credential: user=cust1.app authenticationDomain=DefaultAuth [0:cust1.app 1:DefaultAuth] DEBUG 2022-12-01 16:03:28.559 +0000 [launcher] - Found stored credential: user=cust1.app authenticationDomain=DefaultAuth [0:cust1.app 1:DefaultAuth] DEBUG 2022-12-01 16:03:28.559 +0000 [launcher] - Using password credential: user=cust1.app operatingSystem=linux credentialUserId=sastest1 [0:cust1.app 1:linux 2:sastest1] DEBUG 2022-12-01 16:03:28.559 +0000 [launcher] - Assigned value clientToken from a UserPassCredential WARN 2022-12-01 16:03:29.015 +0000 [launcher] - #{...} syntax is not required for this run-time expression and is deprecated in favor of a simple expression string WARN 2022-12-01 16:03:29.095 +0000 [launcher] - #{...} syntax is not required for this run-time expression and is deprecated in favor of a simple expression string DEBUG 2022-12-01 16:03:29.128 +0000 [launcher] - Is Workload orchestrator enabled?: false [0:false] DEBUG 2022-12-01 16:03:29.129 +0000 [launcher] - User sastest1 currently owns 0 processes in a non-terminal state [0:sastest1 1:0] DEBUG 2022-12-01 16:03:29.129 +0000 [launcher] - User sastest1 is a non-super user and has a limit of 10: enabled=true [0:sastest1 1:10 2:true] DEBUG 2022-12-01 16:03:29.137 +0000 [launcher] - Using podTemplate sas-compute-job-config in namespace gelenv [0:sas-compute-job-config 1:gelenv] DEBUG 2022-12-01 16:03:29.138 +0000 [launcher] - Requested command in the launch request unwrapped: /opt/sas/viya/home/bin/compsrv_start.sh [0:/opt/sas/viya/home/bin/compsrv_start.sh] DEBUG 2022-12-01 16:03:29.138 +0000 [launcher] - The allow list with the replaceable parameters replaced: [/opt/sas/viya/home/bin/compsrv_start.sh] [0:[/opt/sas/viya/home/bin/compsrv_start.sh]]   This shows the cust1.app custom client connecting and then fetching the credentials for the sastest1 user from the Credentials microservice.   Example Custom Client: Using Job Execution Service   Now that we have the following: A Custom Group defined An authorization rule allowing the Custom Group access to the Public folder A custom client defined with the scope linking the Custom Group   We can attempt to create a folder inside the Public folder, create a job definition inside the new folder, submit the job definition to the Job Execution service, check the job execution status, and fetch the resulting job execution files. To perform this test, I used Postman and the sample provided by Joe Furbee available here: https://github.com/sassoftware/rest-api-use-cases/tree/main/postman/job-execution. This is an end-to-end example for Job Execution and interacts with the following endpoints: /folders/folders /jobDefinitions/definitions /jobExecution/jobs /jobDefinitions/definitions/{{job_ID}} /jobExecution/jobs/{{execution_ID}}/state /jobExecution/jobs/{{execution_ID}} /{{files_location}}/content   After authenticating with the client_ID and client_secret I was able to run Joe’s example without any further changes. The custom client, because it had access to the Public folder, was able to create and submit the job to SAS Viya.   Example Custom Client: Accessing CAS   Next, I wanted to see if the custom client would be able to interact with SAS Cloud Analytic Services using the REST API. For this use-case I wanted to generate a CAS session, load a table from the Samples global CASLIB and then fetch the first 10 rows from that table. The authorization for the Samples CASLIB was not changed from the default which is:       Again, I used Postman to interact with the CAS REST API, using the following endpoints: /cas-shared-default-http/cas/sessions – to start a session /cas-shared-default-http/cas/sessions/{{cas_session}}/actions/table.loadTable – to issue the loadTable action /cas-shared-default-http/cas/sessions/{{cas_session}}/actions/table.fetch – to fetch the first 10 rows /cas-shared-default-http/cas/sessions/{{cas_session}} – to terminate the session   Information from the documentation was used to construct the CAS REST API calls.   After authenticating with the client_ID and client_secret I was able run this flow successfully and return 10 rows of data from SAS Cloud Analytic Services to the REST API client.   Example Custom Client: Running SAS Code   Finally, I wanted to test running a SAS Compute Server pod and submitting code to it via the SAS Compute REST API. The documentation for the SAS Compute REST API was used to build out this test using Postman. This test leveraged the following endpoints:   /compute/contexts – to find the ID for the SAS Studio Compute Context /compute/contexts/{{contextId}}/sessions – to launch a SAS Compute Server session /compute/sessions/{{computeId}}/jobs – to submit a job to the SAS Compute Server session /compute/sessions/{{computeId}}/jobs/{{jobId}}/state – to check the status of the submitted job /compute/sessions/{{computeId}}/jobs/{{jobId}}/listing – to fetch the listing from the completed job /compute/sessions/{{computeId}}/jobs/{{jobId}}/log – to fetch the log from the completed job /compute/sessions/{{computeId}} – to terminate the SAS Compute Server session   After authenticating with the client_ID and client_secret I was able to complete this test. Running through this example a SAS Compute Server pod was launched, since credentials were stored for the custom application, these were used to launch the pod. Then some simple code to do a PROC PRINT, launch a CAS Session, report on the CAS nodes, and terminate the CAS session was run within the SAS Compute Server session. All this code completed successfully and then the listing and log output was fetched back to Postman.   Conclusion   In this blog, we have explored a possible option for some use-cases when it is impossible to configure service accounts in your Identity and Authentication providers. This can assist in uses-cases where some Viya related jobs/tasks are required to be automated or where a real user credential cannot be used. The expected scenario is that processes are run within your SAS Viya environment as real users; these users could be your actual end-users, or they could be service accounts correctly configured in your Identity and Authentication providers. It is only this scenario that is fully tested with all the SAS Viya applications. What we have explored here is a possible option for some use-cases when it is impossible to configure service accounts in your Identity and Authentication providers.     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. ... View more

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.   What Shared Accounts   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.   Where are Token Credentials Stored?   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.   Making the Token Authentication Domain Available   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.   Storing Token Credentials   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.   Using Token Credentials   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.   Token Expiry   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.   Conclusion   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. ... View more

With the Stable release of SAS Viya 2023.03, some further incremental improvements have been made in how Kerberos Authentication can be configured with SAS Viya. In this post I want to explain both what the changes are and what the implications are. I won’t be delving into a great deal of detail on how to configure Kerberos Authentication; for this type of information, you should refer to the official documentation and my previous posts.   Kerberos Hybrid Authentication with Protocol Transition   Around one year ago I wrote about the different scenarios for configuring Kerberos authentication. In that post I described the following Kerberos modes:   Kerberos for SAS Logon Manager Kerberos Delegation With Direct Kerberos connections to CAS and SAS/CONNECT Without Direct Kerberos connections to CAS and SAS/CONNECT Kerberos Hybrid Authentication with Protocol Transition With Direct Kerberos connections to CAS and SAS/CONNECT (when pod-launched) Without Direct Kerberos connections to CAS and SAS/CONNECT Kerberos Hybrid Authentication with User Credentials With Direct Kerberos connections to CAS and SAS/CONNECT (when pod-launched) Without Direct Kerberos connections to CAS and SAS/CONNECT   The mode Kerberos Hybrid Authentication with Protocol Transition is where you want to use a non-Kerberos authentication method with SAS Logon Manager but want to use Kerberos authentication from SAS Viya to your data sources. Specifically, you want to leverage Kerberos Constrained Delegation so that the SAS Viya environment obtains Kerberos credentials for each end-user as themselves. For example, you might use Azure Active Directory OpenID Connect (OIDC) to authenticate to SAS Logon Manager, which would allow you to enable Single Sign-On to data sources within Azure. In addition, you also need to access on-premises resources that are secured with Kerberos, so you enable Kerberos Hybrid Authentication with Protocol Transition.   With Kerberos Hybrid Authentication with Protocol Transition the SAS Kerberos Proxy Sidecar will use Kerberos Constrained Delegation to obtain the Kerberos credentials for the end-user and make those available to SAS Cloud Analytic Services or SAS Compute Server. The improvement in the SAS Viya 2023.03 Stable release is in the processing that the SAS Kerberos Proxy Sidecar completes to request these credentials. The SAS Kerberos Proxy Sidecar is aware of the method of authentication used to authenticate the end-users to SAS Logon Manager. If Kerberos authentication is used with SAS Logon Manager, so we are in a straight-forward Kerberos Delegation mode, the SAS Kerberos Proxy Sidecar is provided with the end-users User Principal Name (UPN) by SAS Logon Manager. As such, the SAS Kerberos Proxy Sidecar then obtains a delegated credential with this UPN. If LDAP authentication is used with SAS Logon Manager, so one case of Kerberos Hybrid Authentication with Protocol Transition, the SAS Kerberos Proxy Sidecar constructs the expected UPN from the end-users LDAP Distinguished Name provided by SAS Logon Manager. If any other authentication protocol is used with SAS Logon Manager, and we have configured Kerberos Hybrid Authentication with Protocol Transition, the SAS Kerberos Proxy Sidecar leverages the username in SAS Viya as the UPN to obtain Kerberos delegated credentials. This part is the minor update with the SAS Viya 2023.03 Stable release.   So, if we return to our example of using Azure AD OIDC to authenticate to SAS Logon Manager with Kerberos Hybrid Authentication with Protocol Transition configured for SAS Viya. The ability for the SAS Kerberos Proxy Sidecar to correctly obtain the delegated Kerberos credentials for the end-users will be dependent on the username value used in your SAS Viya environment. The value you configure for the username in SAS Viya will be dependent on your configuration of the Identities microservice. You might be pulling the identity information from an LDAP server, or you could be pushing the information to Identities from a SCIM client such as Azure Active Directory or OKTA. If you are using Azure Active Directory with OIDC and SCIM with your SAS Viya environment, you can control the value used for the username in SAS Viya. I have written previously on this topic as regards OIDC Custom Attributes and SCIM Custom Attributes. You need to ensure the value used for the username in SAS Viya will be valid for obtaining the delegated credentials.   In addition to the value used for the username, you have some controls you can leverage in the Kerberos configuration (krb5.conf) file provided to the SAS Kerberos Proxy Sidecar. If the username has no Kerberos Realm, i.e. it is just `username` rather than `username@REALM.COM`, then specifying the default_realm in the [libdefaults] section of the krb5.conf will cause the Kerberos Realm to be appended.   CAS Direct Kerberos Authentication   The next change with the SAS Viya 2023.03 Stable release related to Direct Kerberos connections to SAS Cloud Analytic Services. For some time now, it has been necessary to configure Direct Kerberos connections to CAS even if it was not required. This was required by the implementation of Kerberos Ticket renewal that required the SAS Cloud Analytic Services controller itself to initialize a Kerberos credential using the Service Principal as SAS Cloud Analytic Services started-up. With the SAS Viya 2023.03 Stable release this is no-longer required; the CAS sessions running internally as the CAS service account will still leverage the SAS Kerberos Proxy Sidecar to obtain a Kerberos credential using the Kerberos keytab provided to the sidecar. As such if it is not required by the scenario you are configuring, you do not need to configure Direct Kerberos connections to SAS Cloud Analytic Services. For example, if you will only ever be connecting to SAS Cloud Analytic Services from within the SAS Viya environment you will not need to configure Direct Kerberos connections to CAS. If in the future, you do need to enable Direct Kerberos connection to CAS you can update your configuration to enable this.   This means that you do not need to have the site-config/kerberos/cas-server directory and you do not need to have reference to this in the resources block of your kustomization.yaml. Also you do not need to add - sas-bases/overlays/kerberos/sas-servers/cas-kerberos-direct.yaml to the transformers block of the kustomization.yaml. The site-config/kerberos/sas-servers directory and associated entries in your kustomization.yaml will still be required to configure the SAS Kerberos Proxy Sidecar.   Conclusion   The two minor updates in the SAS Viya 2023.03 Stable release should make the configuration of Kerberos authentication with SAS Viya more flexible. The changes to Kerberos Hybrid Authentication with Protocol Transition allow for better support of different scenarios. Then removal of the requirement to configure Direct Kerberos connections to SAS Cloud Analytic Services will simplify the configuration for a number of setups.   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. ... View more

SAS Viya on Azure Kubernetes Service uses the NGINX Ingress Controller. Several times I have seen confusion over the firewall settings that prevent access to the Ingress Controller. This often causes issues when trying to configure the SAS Viya environment for SCIM, where the SCIM client needs to be able to directly access the Identities microservice. In this blog I want to explore the settings for the Ingress Controller that impact the firewall settings and show where these are defined. From this we will see where the confusion can arise and how to resolve these issues.   The Setup   To explore this topic, we will take a deployment of SAS Viya LTS 2022.09 in AKS. This environment has used the SAS Viya 4 Infrastructure as Code (IaC) for Microsoft Azure to provision the AKS cluster. The Ingress Controller is then installed into the cluster using HELM. In this case the following command is used to install the Ingress Controller:   helm install ingress-nginx --namespace ingress-nginx \ --set controller.service.externalTrafficPolicy=Local \ --set controller.service.sessionAffinity=None \ --set controller.config.use-forwarded-headers="true" \ --set controller.autoscaling.enabled=true \ --set controller.autoscaling.minReplicas=2 \ --set controller.autoscaling.maxReplicas=5 \ --set controller.resources.requests.cpu=100m \ --set controller.resources.requests.memory=500Mi \ --set controller.autoscaling.targetCPUUtilizationPercentage=90 \ --set controller.autoscaling.targetMemoryUtilizationPercentage=90 \ --set-string controller.service.annotations."service\.beta\.kubernetes\.io/azure-allowed-service-tags"="AzureActiveDirectory" \ --set controller.service.loadBalancerSourceRanges="254.254.254.254/32" --version 4.4.2 \ ingress-nginx/ingress-nginx   This HELM installation command should allow access to the Ingress Controller from both the IP address 254.254.254.254 and everything covered by the Azure Service Tag of "AzureActiveDirectory". We have used just the IP address 254.254.254.254 in the LoadBalancer Source Ranges as it will make it easier to see where this value is used. In most SAS Viya environments this will instead be a list of different IP address ranges where your various end-users will be connecting from.   The Allowed Service Tag setting is useful in Microsoft Azure since it allows us to define firewall rules dependent on the tags maintained by Microsoft. Using the tags means that we do not need to constantly update the IP address ranges used by those services when they are changed by Microsoft.   We can then review the deployed Ingress Controller service within AKS with the following command:   kubectl -n ingress-nginx describe svc ingress-nginx-controller   Which will show:   Name: ingress-nginx-controller Namespace: ingress-nginx Labels: app.kubernetes.io/component=controller app.kubernetes.io/instance=ingress-nginx app.kubernetes.io/managed-by=Helm app.kubernetes.io/name=ingress-nginx app.kubernetes.io/part-of=ingress-nginx app.kubernetes.io/version=1.5.1 helm.sh/chart=ingress-nginx-4.4.2 Annotations: meta.helm.sh/release-name: ingress-nginx meta.helm.sh/release-namespace: ingress-nginx service.beta.kubernetes.io/azure-allowed-service-tags: AzureActiveDirectory Selector: app.kubernetes.io/component=controller,app.kubernetes.io/instance=ingress-nginx,app.kubernetes.io/name=ingress-nginx Type: LoadBalancer IP Family Policy: SingleStack IP Families: IPv4 IP: 10.0.63.178 IPs: 10.0.63.178 LoadBalancer Ingress: 20.232.249.245 Port: http 80/TCP TargetPort: http/TCP NodePort: http 30207/TCP Endpoints: 10.244.1.2:80,10.244.6.47:80 Port: https 443/TCP TargetPort: https/TCP NodePort: https 31352/TCP Endpoints: 10.244.1.2:443,10.244.6.47:443 Session Affinity: None External Traffic Policy: Local HealthCheck NodePort: 31529 LoadBalancer Source Ranges: 254.254.254.254/32   This includes the information we expect with the LoadBalancer Source Ranges and the annotation for the Allowed Service Tags.   If we look at the corresponding Network Security Group within the Azure Portal (https://portal.azure.com) we will see that the following firewall rules have been automatically defined for us:   Select any image to see a larger version. Mobile users: To view the images, select the "Full" version at the bottom of the page.   Again, this reflects the information we provided when installing with HELM and we would expect to be allowed access from both IP address 254.254.254.254 and everything covered by the Azure Service Tag of "AzureActiveDirectory".   The Problem   In our example setup we would expect that Azure Active Directory is able to access the Ingress Controller. This is a core requirement for configuring SCIM with SAS Viya. However, when we try and provide the Tenant URL, Secret Token, and test the connection we will instead see an error:     This rather vague error just tells us there is a problem connecting from Azure Active Directory to our Identities microservice. This could be a network problem or a problem with the Secret Token. But if we have already validated the Secret Token using CURL when we generated it, we can eliminate this as the cause of the problem. This means the problem must lie with the network connection from Azure Active Directory to SAS Viya.   The Cause   Everything that we have shown for our setup would suggest that Azure Active Directory should have no problems connecting. But something is preventing the connection. When we use the LoadBalancer Source Ranges, in the background in addition to defining the Network Security Group rules, additional IPTABLES firewall rules are also defined on the AKS nodes where the Ingress Controller service is running.   We can demonstrate this by using the kubectl-exec project to run a debugging privileged container on the AKS node and access the IPTABLES rules on that node. Since this is a privileged container, you should not run this on a production cluster. We are running it here on our testing cluster to demonstrate what is happening. Once you have installed kubectl-exec as per the instructions you will need to edit the /usr/local/bin/kubectl-exec script to allow the NET_ADMIN capability, as discussed here. The changed part of the file will look like the following:   ... #nsenter JSON overrrides OVERRIDES="$(cat <<EOT { "spec": { "nodeName": "$NODE", "hostPID": true, "containers": [ { "securityContext": { "privileged": true, "capabilities": { "add": [ "NET_ADMIN" ] } }, ...   Then you can use the following command to find the node where your Ingress Controller is running:   kubectl -n ingress-nginx get pods -o wide   Which will output something like the following:   NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES ingress-nginx-controller-7f5d995f47-d9858 1/1 Running 0 9h 10.244.6.47 aks-generic-21185651-vmss000000 ingress-nginx-controller-7f5d995f47-wml2w 1/1 Running 0 10h 10.244.1.2 aks-generic-21185651-vmss000002 The kubectl-exec script can then be used to launch the debugging container on the node with the following command:   kubectl-exec aks-generic-21185651-vmss000000   Finally, you can use the following IPTABLES command to list all the rules in the NAT table and search for the IP address we included in the LoadBalancer Source Ranges:   iptables -t nat -L|grep -A1 -B1 254.254.254.254   Which will output something like the following:   target prot opt source destination KUBE-EXT-CG5I4G2RS3ZVWGLK all -- 254.254.254.254 anywhere /* ingress-nginx/ingress-nginx-controller:http loadbalancer IP */ KUBE-MARK-DROP all -- anywhere anywhere /* ingress-nginx/ingress-nginx-controller:http loadbalancer IP */ -- target prot opt source destination KUBE-EXT-EDNDUDH2C75GIR6O all -- 254.254.254.254 anywhere /* ingress-nginx/ingress-nginx-controller:https loadbalancer IP */ KUBE-MARK-DROP all -- anywhere anywhere /* ingress-nginx/ingress-nginx-controller:https loadbalancer IP */   This shows that we have two rules defined for the IP address that allow access via HTTP and HTTPS coming from 254.254.254.254/32, but all other source ranges will be dropped by IPTABLES. Therefore, this is the cause of our network connection issue. The connection from Azure Active Directory is allowed by the Network Security Group rules but is being dropped by IPTABLES on the actual node where the Ingress Controller is running.   The Solution   To resolve this issue, we need to remove the LoadBalancer Source Ranges from the Ingress Controller service definition. If we have allowed access to the AKS control plane from our own machine we could perform this in a browser using the Azure Portal (https://portal.azure.com), or we could use kubectl from our management host, or we could use HELM to update the deployment of the Ingress Controller. For example, to use kubectl to edit the service definition use the following command:   kubectl -n ingress-nginx edit svc ingress-nginx-controller   This will open the service definition for editing and we can just remove the required lines. As soon as we save the edited content it is applied and the IPTABLES rules will be removed alongside the Network Security Group rules.   CAUTION 1: If you only had the LoadBalancer Source Ranges defined and you have now removed them, Microsoft Azure will helpfully define a new Network Security Group rule allowing access to 0.0.0.0 which is everyone on the internet.   CAUTION 2: If you have both the LoadBalancer Source Ranges defined and the Allowed Service Tags, when you remove the LoadBalancer Source Ranges, Microsoft Azure will only have a Network Security Group rule allowing access from the service tags. This means that your end-users will not be able to access your SAS Viya environment. You will need to manually add Network Security Group rules to allow access to your environment. You can add these rules either through the Azure Portal (https://portal.azure.com) or using the Azure CLI.   Conclusion   As we have seen leveraging the LoadBalancer Source Ranges makes it easy to secure your Ingress Controller. However, this can have unintended consequences when you later need to open access to the Ingress Controller to other services running in Microsoft Azure. As such, if you will configure your SAS Viya environment running in Azure for SCIM with Azure Active Directory, you are better using the Allowed Service Tags to allow Azure Active Directory access to your Ingress Controller. Then manually, defining the Network Security Group rules to allow your end-users access.   Find more articles from SAS Global Enablement and Learning here. ... View more

Throughout the last year leading up to the SAS Viya Stable 2022.10 release the default token lifetimes for SAS Viya have been changing. With the SAS Viya 2022.10 Stable release the Access Token now has a default lifetime of 1 hour while the Refresh Token has a default lifetime of 90 days. It should be noted that the current SAS Viya 2022.09 LTS release still has a default lifetime for the Access Token of 4 hours, while the Refresh Token lifetime is 90 days. Refresh Tokens, as we will explore, are revokable so they can be long lived. Whereas the Access Tokens are not revokable and so they have a much shorter lifetime.   Given these lifetime values for the tokens I wanted to discuss some implications for the SAS Viya CLI, how tokens can be revoked and the implications for any custom clients of SAS Logon Manager. Previously, Edoardo Riva has discussed Tuning the authentication timeout for long-running jobs where he discusses the implications for situations where clients have long-running sessions that try to use expired Access Tokens – and obviously fail.   Types of Tokens   As we have stated above there are two types of tokens generated by SAS Logon Manager. The Access Token is used to access the different SAS Viya services and the Refresh Token, if requested, can be used to obtain a new Access Token. Most of the time when using the SAS Viya web applications, you will not need to be concerned about the SAS Logon Manager generated tokens. Since the tokens are requested and used seamlessly by the various SAS Viya web applications. The tokens are never exposed to the end-user’s browser and the end-user never has direct access to their tokens.   However, there are other cases where the end-user does have access to their tokens. This could be when leveraging the supported third-party programming languages such as Java, Python, or Lua to interact with either SAS Cloud Analytic Services REST API or other SAS Viya REST APIs. Or when using the SAS Viya CLI. The SAS Viya CLI will place the Access Token and Refresh Token in a credentials.json file within the user’s home directory. On Linux this would be ~/.sas/credentials.json and for example would contain:   { "Default": { "access-token": "eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbG9jYWxob3N0L1NBU0xvZ29uL3Rva2VuX2tleXMiLCJraWQiOiJsZWdhY3ktdG9rZW4ta2V5IiwidHlwIjoiSldUIn0. eyJqdGkiOiI1MzI1Yzk5YTAyZTM0NGNhOTNlZWExMTJjODAzYWJhNyIsInN1YiI6IjIyMGIyODI5LTQ4M2UtNDQ3My1hZWEwLWJiMDc2Nzk2YWUyYiIsInNjb3BlIjpbImNsaWVudHMucmVhZCIsImNsa WVudHMuc2VjcmV0IiwidWFhLnJlc291cmNlIiwib3BlbmlkIiwidWFhLmFkbWluIiwiY2xpZW50cy5hZG1pbiIsInNjaW0ucmVhZCIsInVhYS51c2VyIiwiU0FTQWRtaW5pc3RyYXRvcnMiLCJjbGllbn RzLndyaXRlIiwic2NpbS53cml0ZSJdLCJjbGllbnRfaWQiOiJzYXMuY2xpIiwiY2lkIjoic2FzLmNsaSIsImF6cCI6InNhcy5jbGkiLCJncmFudF90eXBlIjoicGFzc3dvcmQiLCJ1c2VyX2lkIjoiMjI wYjI4MjktNDgzZS00NDczLWFlYTAtYmIwNzY3OTZhZTJiIiwib3JpZ2luIjoidWFhIiwidXNlcl9uYW1lIjoic2FzYm9vdCIsImVtYWlsIjoibm9uZSIsImF1dGhfdGltZSI6MTY2OTY0MzAwMSwicmV2 X3NpZyI6IjU1MGI0ZTUyIiwiaWF0IjoxNjY5NjQzMDAxLCJleHAiOjE2Njk2NDY2MDEsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3QvU0FTTG9nb24vb2F1dGgvdG9rZW4iLCJ6aWQiOiJ1YWEiLCJhdWQiO lsic2NpbSIsImNsaWVudHMiLCJzYXMuKiIsInVhYSIsIm9wZW5pZCIsInNhcy5jbGkiXX0.PcGyJQEG1maldQtwQ3FiCKZWZ_SIGckvF8X24XppVRUWktpmMmxQGdD-lZzPPJ0D9HJ51kyzkKETseFueo CSjgxdwvLi4TiNEgIAgln-itcmtRmRzdFLKtWufgcZLuU-Fx9aH5YwVJIAgcJWDRUcIR_dwBMC2AJQOqWKF15JoPi07gmTjLejQcIf23OiM4jX0RZWJjKeXFHNvvJ67EqmO90oUbhmyhQ-l-hagh-UqFk kueOFZUkbLy6PGrcGMWLgARJ6oTkXCRMide61j7hXk2lR5X-caxhZ6hdlctGR39uEY8gBQZhPMOE6j-vtEQrSXf-hjmX1Y1Uy6w3jO_bxHQ", "expiry": "2022-11-28T14:43:20Z", "refresh-token": "642db5db07e140bbb19262793b0f3c06-r" }   In this output you can see that authenticating with the SAS Viya CLI has obtained the Access Token and Refresh Token. The Access Token is a signed JSON Web Token while, in this case, the Refresh Token is an opaque token. With the SAS Viya 2022.09 Stable release the SAS Viya CLI started to use opaque tokens for the Refresh Token. Also note the "-r" at the end of the Refresh Token, this means that the Refresh Token can be revoked. Specifically, when you issue the command sas-viya auth logout the SAS Viya CLI will revoke the existing Refresh Token and remove the contents of the credentials.json file. This way even if someone has managed to obtain a copy of the Refresh Token it cannot be abused once the logout command is issued.   The same information can be viewed in a nicer format using the SAS Viya CLI itself. The command sas-viya profile show will display essentially the same information, as shown here:   Current settings for the [Default] profile: Setting Current Value output text sas-endpoint https://sasviya.customer.com access-token eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbG9jYWxob3N0L1NBU0xv... expiry 2022-11-29T12:36:41Z refresh-token 6c51cf4fa54d4a76b3c118f3c5350ec5-r ansi-colors-enabled true oauth-client-id sas.cli   It should be noted that in both cases the expiry time is shown in the UTC time zone, which might not reflect the same time zone as the host where you are running the SAS Viya CLI.   SAS Viya CLI Auto-Refresh   The SAS Viya CLI will automatically use the opaque Refresh Token to obtain a new Access Token. This means that even when the Access Token has expired you are still able to run SAS Viya CLI commands, so long as the Refresh Token has not expired, and you have not logged out. This does not require any interaction from the end-user. So, with the SAS Viya 2022.09 LTS release after 4 hours the Access Token will be automatically refreshed for you. While with SAS Viya 2022.10 Stable release (and later) this occurs after 1 hour. If you look at the credentials.json file, you will see that the Access Token has been refreshed and the expiry time moved forward. If you attempt to use the SAS Viya CLI after the Refresh Token has expired, you’ll be presented with the following message:   The following errors have occurred: The user token is expired. Login again before attempting any commands. Http Status: 0 This means that if you have a secured environment where you want to run scheduled tasks leveraging the SAS Viya CLI and you are confident in the security of the credentials.json file you could leave the SAS Viya CLI authenticated. The SAS Viya CLI would then continue to refresh the Access Token until the Refresh Token expires, after 90 days.   Revoking Tokens   Since the Refresh Token produced by the SAS Viya CLI will be valid for 90 days and can be used to obtain an Access Token, being able to revoke the Refresh Token is important. If you are administrating a SAS Viya environment and are concerned that some of your end-users might not remember to use the command sas-viya auth logout to revoke their own token. Then you could revoke all Refresh Tokens issued to the SAS Viya CLI on a regular basis. You will need to have a Bearer token as a member of SAS Administrators or the sasboot user.   To revoke the Refresh Tokens issued to users of the SAS Viya CLI you would use:   curl -i -X GET "${INGRESS_URL}/SASLogon/oauth/token/revoke/client/sas.cli" -H "Authorization: Bearer $BEARER_TOKEN"   Which would output:   HTTP/1.1 200 Date: Tue, 29 Nov 2022 12:35:02 GMT Content-Length: 0 Connection: keep-alive Set-Cookie: sas-ingress-nginx=a772dad7648bc6f096fb118a58701b7e|f8c52217c576225c1e53519ff3193724; Path=/SASLogon/; Secure; HttpOnly; SameSite=Lax Vary: Origin Vary: Access-Control-Request-Method Vary: Access-Control-Request-Headers Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache Expires: 0 Strict-Transport-Security: max-age=15724800; includeSubDomains X-XSS-Protection: 1; mode=block X-Frame-Options: DENY X-Content-Type-Options: nosniff After this, anyone using the SAS Viya CLI would need to reauthenticate once their Access Token has expired. But it would not impact any existing Access Tokens.   Custom Clients   If you define your own clients to SAS Logon Manager, you will need to decide about the correct lifetime values you want to use for the Access Tokens. You can override the system-wide default for your custom applications by updating the value for the access_token_validity property. See Register an OAuth Client ID in SAS Viya: Authentication for information about the access_token_validity property and the steps for registering a client so that it can obtain tokens.   For example, say you have registered a client to SAS Logon Manager with the following settings:   curl -k -X POST "${INGRESS_URL}/SASLogon/oauth/clients" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -d '{ "client_id": "test.app", "client_secret": "myclientsecret", "scope": ["*"], "authorized_grant_types": ["password","authorization_code","refresh_token"], "access_token_validity": 300, "redirect_uri": "urn:ietf:wg:oauth:2.0:oob" }'   This will allow end-users to authenticate with either their username and password or using the authorization code. This client will produce Access Tokens with a lifetime of 5 minutes but will use the system wide default of 90 days for the lifetime of the Refresh Tokens. With this client you could then authenticate with a username and password to obtain the end-users Access Token and Refresh Token with the following:   AUTH_RESP=$(curl -skX POST "${INGRESS_URL}/SASLogon/oauth/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=password&username=sasadm&password=Metadata0" \ -u "test.app:myclientsecret"); \ USER_TOKEN=$(echo $AUTH_RESP|jq -r '."access_token"'); \ USER_REFRESH=$(echo $AUTH_RESP|jq -r '."refresh_token"'); \ echo "The end-user access-token is: " ${USER_TOKEN}; \ echo "The end-user refresh-token is: " ${USER_REFRESH}; \ echo "Expiry date of Access Token is: $(printf '%(%FT%T%z)T\n' $(echo ${USER_TOKEN}|awk -F'.' '{print $2}'|base64 -d|jq -r '."exp"'))"   Which would produce an output something like the following:   The end-user access-token is: eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbG9jYWxob3N0L1NBU0xvZ29uL3Rva2VuX2tleXMiLCJraWQiOiJsZWdhY3ktdG9rZW4ta2V5IiwidHlwIjoiSldUIn0. eyJqdGkiOiIxNzUwZThkZmNlM2Y0Zjc2YTA3YTNmN2FjZTVkNWQyYSIsImV4dF9pZCI6ImNuPVNBUyBBZG1pbmlzdHJhdG9yLG91PUFBRERDIFVzZXJzLGRjPWdlbGVuYWJsZSxkYz1zYXMsZGM9Y29tIiwic3ViIjo iNjVjYTdjZDctZmM4Yi00OGNiLTgyMTAtNWRmYmJhYTIxNmZkIiwic2NvcGUiOlsiU0FTIEFkbWlucyIsIkhSIiwiU0FTIFVzZXJzIiwiU2FsZXMiLCJBbGwgR0VMQ29ycCBVc2VycyIsIkdFTFN5c3RlbUFkbWlucy IsIkZpbmFuY2UiLCJvcGVuaWQiLCJQb3dlclVzZXJzIiwiU0FTQWRtaW5pc3RyYXRvcnMiXSwiY2xpZW50X2lkIjoidGVzdC5hcHAiLCJjaWQiOiJ0ZXN0LmFwcCIsImF6cCI6InRlc3QuYXBwIiwiZ3JhbnRfdHlwZ SI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjY1Y2E3Y2Q3LWZjOGItNDhjYi04MjEwLTVkZmJiYWEyMTZmZCIsIm9yaWdpbiI6ImxkYXAiLCJ1c2VyX25hbWUiOiJzYXNhZG0iLCJlbWFpbCI6InNhc2FkbUBnZWxlbmFi bGUuc2FzLmNvbSIsImF1dGhfdGltZSI6MTY2OTczNjYxMSwicmV2X3NpZyI6IjRiN2U4NiIsImlhdCI6MTY2OTczNjYxMSwiZXhwIjoxNjY5NzM2OTExLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0L1NBU0xvZ29uL29 hdXRoL3Rva2VuIiwiemlkIjoidWFhIiwiYXVkIjpbInRlc3QuYXBwIiwib3BlbmlkIiwidGVzdC4qIl19.sIBcRkWLAUIZy6nGGRxtiAVIrJ4eVxykYJpqakFN25ln6ctnXd-gK7fXcL6qy2Xu0EVstI8j-OoCrTJ9L m7WrXAMz_p2oCKHnsF4b7Cu9g-S0OjNSYKGCg8qctAVSaUuPeAtZoHopnPLe1P9Jrn1_bXzgCy0TwVW3dBj-BXjmz5GSXUy5_ru6UjPQ8EwQkvTAbFyYX1aBo8iyAcMgmehIV14C1JfIjClXBI0sWF4icZLsS_6eIv5 sy_p5U-BD8dP5wbj59qIuHBxvB0ZhOgyMqlhPO84QpPds0AhuiDe3GAeFBbybr578kFaaYxDP8GXE_pJEgnm8bx99VMpkZVucA The end-user refresh-token is: eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbG9jYWxob3N0L1NBU0xvZ29uL3Rva2VuX2tleXMiLCJraWQiOiJsZWdhY3ktdG9rZW4ta2V5IiwidHlwIjoiSldUIn0. eyJqdGkiOiJlMzMyNjFiMzY4NzU0OTgzYTNhYWM1OWFhZmIwNTIzZS1yIiwic3ViIjoiNjVjYTdjZDctZmM4Yi00OGNiLTgyMTAtNWRmYmJhYTIxNmZkIiwiaWF0IjoxNjY5NzM2NjExLCJleHAiOjE2Nzc1MTI2MTEs ImNpZCI6InRlc3QuYXBwIiwiY2xpZW50X2lkIjoidGVzdC5hcHAiLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0L1NBU0xvZ29uL29hdXRoL3Rva2VuIiwiemlkIjoidWFhIiwiYXVkIjpbInRlc3QuYXBwIiwib3Blbmlk Il0sImdyYW50ZWRfc2NvcGVzIjpbIlNBUyBBZG1pbnMiLCJIUiIsIlNBUyBVc2VycyIsIlNhbGVzIiwiQWxsIEdFTENvcnAgVXNlcnMiLCJHRUxTeXN0ZW1BZG1pbnMiLCJGaW5hbmNlIiwib3BlbmlkIiwiUG93ZXJV c2VycyIsIlNBU0FkbWluaXN0cmF0b3JzIl0sImFtciI6WyJleHQiLCJwd2QiXSwiYXV0aF90aW1lIjoxNjY5NzM2NjExLCJleHRfaWQiOiJjbj1TQVMgQWRtaW5pc3RyYXRvcixvdT1BQUREQyBVc2VycyxkYz1nZWxl bmFibGUsZGM9c2FzLGRjPWNvbSIsImdyYW50X3R5cGUiOiJwYXNzd29yZCIsInVzZXJfbmFtZSI6InNhc2FkbSIsIm9yaWdpbiI6ImxkYXAiLCJ1c2VyX2lkIjoiNjVjYTdjZDctZmM4Yi00OGNiLTgyMTAtNWRmYmJh YTIxNmZkIiwicmV2X3NpZyI6IjRiN2U4NiJ9.S78JjwjNCsg43fpIPYAsIv5TEzxBSXc8KHcJj7cMWCSnXB4BIMfBSKOFya8lqRbZ7jSB1XUqC2oouWQVvMSoDEg8FtHTR3hIBiVepBFpSkJqH8LCjbWXdoJWww6WgWy UJOKSdi3T45JecXISx5BSCgQKdxUcW5-KXW8_d1CaFbCIgFoGumFHkqdmOr6m4TRmfTYF1HeZLrYgQ6V5XfavVVkAwPqAA7QOMGQzBLkk7k-n-v8yMrrZLGeMNnwdz8CMJ82M6QC4LFZe0cv--k2KXEp_UdDWk_GeN19 zuk9a2NlicA-J-2G-NCWh1GfYo8uc1Ayo14f-XYcVTNDGVyRkJQ Expiry date of Access Token is: 2022-11-29T10:48:31-0500 You could then use the Refresh Token to obtain a new Access Token with the following:   AUTH_RESP=$(curl -skX POST "${INGRESS_URL}/SASLogon/oauth/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_id=test.app&client_secret=myclientsecret&grant_type=refresh_token&refresh_token=${USER_REFRESH}"); \ USER_TOKEN=$(echo $AUTH_RESP|jq -r '."access_token"'); \ echo "The end-user access-token is: " ${USER_TOKEN}; \ echo "Expiry date of Access Token is: $(printf '%(%FT%T%z)T\n' $(echo ${USER_TOKEN}|awk -F'.' '{print $2}'|base64 -d|jq -r '."exp"'))"   Which would produce the following:   The end-user access-token is: eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbG9jYWxob3N0L1NBU0xvZ29uL3Rva2VuX2tleXMiLCJraWQiOiJsZWdhY3ktdG9rZW4ta2V5IiwidHlwIjoiSldUIn0. eyJqdGkiOiJmZmI3MWUxMDZmMTA0NWY0YWUxODI4NDdjNDdhOGFjMSIsImV4dF9pZCI6ImNuPVNBUyBBZG1pbmlzdHJhdG9yLG91PUFBRERDIFVzZXJzLGRjPWdlbGVuYWJsZSxkYz1zYXMsZGM9Y29tIiwiYW1yIjp bImV4dCIsInB3ZCJdLCJzdWIiOiI2NWNhN2NkNy1mYzhiLTQ4Y2ItODIxMC01ZGZiYmFhMjE2ZmQiLCJzY29wZSI6WyJTYWxlcyIsIkFsbCBHRUxDb3JwIFVzZXJzIiwiU0FTQWRtaW5pc3RyYXRvcnMiLCJGaW5hbm NlIiwib3BlbmlkIiwiU0FTIEFkbWlucyIsIkdFTFN5c3RlbUFkbWlucyIsIkhSIiwiU0FTIFVzZXJzIiwiUG93ZXJVc2VycyJdLCJjbGllbnRfaWQiOiJ0ZXN0LmFwcCIsImNpZCI6InRlc3QuYXBwIiwiYXpwIjoid GVzdC5hcHAiLCJncmFudF90eXBlIjoicGFzc3dvcmQiLCJ1c2VyX2lkIjoiNjVjYTdjZDctZmM4Yi00OGNiLTgyMTAtNWRmYmJhYTIxNmZkIiwib3JpZ2luIjoibGRhcCIsInVzZXJfbmFtZSI6InNhc2FkbSIsImVt YWlsIjoic2FzYWRtQGdlbGVuYWJsZS5zYXMuY29tIiwiYXV0aF90aW1lIjoxNjY5NzM2NjExLCJyZXZfc2lnIjoiNGI3ZTg2IiwiaWF0IjoxNjY5NzM2NzMzLCJleHAiOjE2Njk3MzcwMzMsImlzcyI6Imh0dHA6Ly9 sb2NhbGhvc3QvU0FTTG9nb24vb2F1dGgvdG9rZW4iLCJ6aWQiOiJ1YWEiLCJhdWQiOlsidGVzdC5hcHAiLCJvcGVuaWQiXX0.nTzDb6C5FjCksk1xyViXIwgl9vG1X7_6aSF4rYOYkkffTOvFt85JRsXfvycUOxVB1i DAa2KKTF8yWX0n7XhTROnERP99SVsLoNwX-umuiE_K-uvpHQ_Ec5dYx1N-pRD8aJ3Cw-9TTrgwsmdVDc0VeN_cBhhf155F7EOd5U8uh3-FlLOMFoZ_dq4xSgBlM3uGRzm04OmMvOOxKZr6egFi0pzjZWjcfTW6N6a9U JjGkjobhLWrAiiwCqT6ddyNLhhh_Piq9rmtsSkwdJmTT7WXx3WLxyd1f4UAbL2HGsz02awNcrg64aZfmFfWnTVAipEXcxazjGgsWLyW1VxRgEeTSA base64: invalid input Expiry date of Access Token is: 2022-11-29T10:50:33-0500   These simple CURL examples demonstrate how you could use the Refresh Token for your own custom clients of SAS Logon Manager. Notice that in this case the Refresh Token is a Signed JSON Web Token, not an opaque token, and is not revokable.   Conclusion   With the SAS Viya 2022.10 Stable release the Access Token now has a default lifetime of 1 hour while the Refresh Token has a default lifetime of 90 days. In this blog we have shown how the SAS Viya CLI will automatically refresh the Access Token so long as the Refresh Token is still valid. Equally, we have shown how you can easily revoke these long-lived Refresh Token’s ensuring that you can force your end-users to reauthenticate. Finally, we have also discussed how these token lifetimes might impact your custom clients of SAS Logon Manager, and how you can also leverage the Refresh Token. ... View more

With the SAS Viya 2022.10 Stable release there are changes in the way in which UID & GID information is handled by the Identities microservice. Starting with the SAS Viya 2022.10 Stable release SAS Viya moves to an EITHER-OR model for the user and group identifier information. Either, as the SAS Administrator, you choose to Bring Your Own (BYO) UID and GID information, which would be loaded to the Identities microservice. Or, as the SAS Administrator, you chose to allow the Identities microservice to generate the UID and GID information. You can load UID and GID information either from LDAP or manually. In this blog we’ll examine this new model in more detail and look at some implications of the change.   Why be Concerned with UID & GID   Before we delve into the details, why should you be concerned with the UID & GID? In your SAS Viya environment the Launcher service, SAS Cloud Analytic Services, and the SAS/CONNECT Spawner all can launch processes as your end-users. The Launcher Service always fetches the user attribute information from the Identities microservice, which includes the UID and possibly the GID information. This is used for the pod that is then launched. For SAS Cloud Analytic Services, the default option is CASCLOUDNATIVE=1 which means that for Host Launched sessions the user attribute information will be returned from the Identities microservice. Equally, for the SAS/CONNECT Spawner since the default option here is SASCLOUDNATIVE=1, the user attribute information is queried from the Identities microservice. Therefore, if your end-users will be interacting with the file system from the SAS Compute Server, SAS Cloud Analytic Services host-launched sessions, or from SAS/CONNECT sessions the UID and GID used will be crucial to the implementation of file system permissions.   How to Choose the Mode   The SAS Viya 2022.10 Stable release introduces the following new configuration settings for the Identities microservice:   sas.identities.identifier.generateUids = true/false sas.identities.identifier.generateGids = true/false sas.identities.identifier.disableGids = true/false   First, let’s consider the setting sas.identities.identifier.generateUids:   Generate UIDs Expected Behaviour True (default) Always supply a generated UID, returned when the users identifier endpoint is returned. Any attempt to load UID values through the Identities microservice endpoint will return an error. Users with existing BYO UIDs (loaded to identities when generate was set to false or persisted in LDAP) will be pre-empted by the generation of UIDs thus overriding any BYO UIDs. False This is a customer BYO model: custom UID values can be loaded through the Identities microservice endpoint or persisted in the LDAP store. Identifier endpoints will return BYO UID values and loaded values should take precedence over LDAP. If no BYO value is found, nothing is returned.   Next, let’s consider the two settings (sas.identities.identifier.disableGids and sas.identities.identifier.generateGids) for controlling GID values:   Disable GIDs Generate GIDs Expected Behaviour False (default) True Always supply a generated GID, returned when either identifier endpoint is called (users or groups). Any attempt to load gid values through the Identities microservice endpoint will return an error. Groups with existing BYO GIDs (loaded to identities when generate was set to false or persisted in LDAP) will be pre-empted by the generation of GIDs thus overriding any BYO GIDs. False (default) False (default) This is a customer BYO model: custom GID values can be loaded through the Identities microservice endpoint or persisted in the LDAP store. The Identities microservice endpoints will return BYO GID values and loaded values should take precedence over LDAP. If no BYO value is found, nothing is returned. True N/A GID Functionality Disabled: GIDs will not be returned by either identifier endpoint in any context.   As a SAS Administrator you choose to either Bring Your Own (BYO) values or to generate values based on these configuration settings. Any previous configuration settings are not used.   How to Configure the Settings   These three configuration options are under the sas.idenities group of settings. The sas.identities settings are not tenant specific, which means in an application multi-tenant environment you would only configure the settings once in the multi-tenant provider. You as a SAS Administrator can set the values, if you do not want to use the defaults, in any of the following ways:   Using SAS Environment Manager to manually configure the settings. The Identities microservice will automatically pick up the configuration change after a couple of minutes. Use the SAS Viya CLI to either create or patch the configuration by providing a JSON configuration file. Use the sitedefault.yaml to load these new configuration settings, since these are new properties this can also be done when upgrading to the SAS Viya 2022.10 Stable release from an earlier release. Your sitedeafult.yaml content would look like the following example: --- config: application : ... ... sas.identities: ... identifier.generateUids: 'true' identifier.generateGids: 'true' identifier.disableGids: 'false' ...   The Default Behaviour   By default, with the SAS Viya 2022.10 Stable release and later, the following will occur:   The Identities microservice will always provide a generated UID even if your LDAP Provider has a valid POSIX UID attribute The Identities microservice will not allow you as a SAS Administrator to load UID values through the Identities microservice endpoint The Identities microservice will allow you as a SAS Administrator to provide GID values from your LDAP Provider The Identities microservice will allow you as a SAS Administrator to load GID values through the Identities microservice endpoint The Identities microservice will not generate a GID value, if GID values are not provided by your LDAP Provider or loaded nothing is returned   This means that the default is to generate UID values and BYO GID values.   Is UID Treated the Same As GID   As we can see from the above the UID values are not treated the same as the GID values. In the default case the assumption is that you want the Identities microservice to generate UID values, but if you don’t provide GID values then no GID values are returned. So as a SAS Administrator you can choose:   To generate UID values and only Bring Your Own GID values To only Bring Your Own UID values and generate GID values To Bring Your Own UID & GID values To generate both UID & GID values To ignore GID values altogether How Are Values Generated   When the Identities microservice is configured to generate values for GID and/or UID the same approach is used. Values are only generated when the Identifier endpoint is called; for a user the Identifier endpoint is https://viya.customer.com/identities/users/{{USERNAME}}/identifier , while for a group it is: https://viya.customer.com/identities/groups/{{GROUPID}}/identifier. To generate values the Identities microservice takes the Identity type (either USER or GROUP) along with the accountId value and generates a SHA hash of the string. This ensures that a user with the same accountId value as a group will generate a different hash value. The hash value is then mapped onto a numerical space to generate either the UID or GID value. If the UID is generated for a user their primary GID (returned as just gid from the Identifier endpoint) is always set to the same value. Only when generating GID values for groups will these values be populated as secondaryGid for the end-user’s Identifier endpoint. For example, looking at the user Identifier endpoint when we are generating both values, we will see the following:   Select any image to see a larger version. Mobile users: To view the images, select the "Full" version at the bottom of the page.   Whereas, if we look at the user Identifier endpoint when we are generating only the UID values we will see the following:       The same output will be provided by the user Identifier endpoint if we set sas.identities.identifier.disableGids to true as well, so only the primary GID will be returned.   How Are Values Loaded   When you as a SAS Administrator decide to Bring Your Own values, you have a choice in how to provide them. If you have a LDAP Provider with a POSIX schema the Identities microservice can fetch the UID and/or the GID values from your LDAP Provider along with the other user and group attributes. Alternatively, you can load UID and/or GID information directly into the Identities microservice. This can be done with either the SAS Viya CLI or the Identities microservice REST API.   With the SAS Viya CLI you can update individual users:   /opt/sas/viya/home/bin/sas-viya identities update-user Command requires the following flags: id NAME: sas-viya identities update-user - Updates information about an existing user. Currently only supports updating the user identifier (uid/gid) values. USAGE: sas-viya identities update-user [command options] [arguments...] OPTIONS: --gid "0" Specifies the gid number to set or update for the user. This value must be greater than 0. --id Specifies the ID of the user that is being updated. --uid "0" Specifies the uid number to set or update for the user. This value must be greater than 0. Command requires the following flags: id   Or individual groups:   /opt/sas/viya/home/bin/sas-viya identities update-group Command requires the following flags: id NAME: sas-viya identities update-group - Updates information about an existing group. USAGE: sas-viya identities update-group [command options] [arguments...] OPTIONS: --description Specifies a new description for the group. --gid "0" Specifies the gid number to update for the group. This value must be greater than 0. --id Specifies the ID of the group that is being updated. --name Specifies a new name for the group. Command requires the following flags: id With the next release of the identities plugin version 1.18.11 you will also be able to bulk load either users or groups by providing either a JSON or CSV input file. In addition, the Python Tools for SAS Viya also offers an option to set the POSIX user attributes for users and groups.   Ignore GID Values   The setting sas.identities.identifier.disableGids when enabled (set to true) will prevent the Identities microservice from fetching GID information entirely. This is irrespective of the method of providing GID information, whether Bring Your Own or generated GID values. If you as a SAS Administrator are not concerned with GID information, perhaps your file system security model is purely based around UID, then you can set sas.identities.identifier.disableGids=true. This means the Identities microservice will respond slightly faster since there will be no internal processing for GID values. Meaning that there will be no LDAP queries for GID information, nor any internal database queries for GID information.   Generated Conflicts   As discussed above the generated values are calculated by taking a SHA hash and then mapping the resulting hash value onto a numerical space. While the SHA hash will be unique there is a chance that when mapping onto the numerical space two different hash values could result in the same numerical value. A conflict or clash will occur when the Identifier endpoint is called for a user or group and the value generated is the same as an existing generated value. If such a clash does occur, the Identities microservice will retry generating the value, moving slightly the numerical space the hash is mapped onto. This will prevent clashes in generate mode from producing an exception and you will be guaranteed to correctly generate a value.   However, if you are in the very rare case of experiencing a conflict and you happen to have multiple environments such as DEV, TEST, and PROD where you expect the generated values to be the same you might have an issue. Since the UID or GID values are only generated when the Identifier endpoint is called, for example by logging into SAS Studio. You might find that your end-users have triggered the generation in a different order. If user1 and user2 both generate the same UID then whichever one is queried first gets the original UID value and the second one gets the newly generated alternative. If on DEV, user1’s identifier was queried first and got 1234 and user2 was queried second and got 9876, that is their identifiers. Then if on TEST, user2’s identifier was queried first it would get 1234 and the user1 query is now second, it would get the newly generated alternative.   A way to resolve this issue would be to use the SAS Viya CLI to remove the two identifier values and have them regenerated. The SAS Viya CLI provides the following command to delete user identifier information:   /opt/sas/viya/home/bin/sas-viya identities delete-user-identifier Command requires the following flags: id NAME: sas-viya identities delete-user-identifier - Deletes the identifier for the specified user. USAGE: sas-viya identities delete-user-identifier [command options] [arguments...] OPTIONS: --id Specifies the ID of the user whose identifier is being deleted. Command requires the following flags: id   As well as an equivalent for groups:   /opt/sas/viya/home/bin/sas-viya identities delete-group-identifier Command requires the following flags: id NAME: sas-viya identities delete-group-identifier - Deletes the identifier for the specified group. USAGE: sas-viya identities delete-group-identifier [command options] [arguments...] OPTIONS: --id Specifies the ID of the group whose identifier is being deleted. Command requires the following flags: id   Or you could move to the Bring Your Own values mode instead.   Changing Mode   If you decide to change mode for either UIDs and/or GIDS with the SAS Viya Stable release 2022.10 and higher you can. If you change the value of the options from true to false, or vice-versa, the Identities microservice will automatically clean-up the next time the Identifier endpoint is called. For example, if you start generating both UID & GID values, but then decide that you need to provide the GID values you can change sas.identities.identifier.generateGids to false. You can then provide those GID values either from your LDAP with POSIX attributes or by loading them. The next time the Identifier endpoint is called, for example by a user logging into SAS Studio, the new value will be used.   However, while the Identities microservice will now use the value you want; separately, you will need to ensure any file system or other external content is correctly updated.   Upgrading to SAS Viya 2022.10 and higher   If you are upgrading to SAS Viya 2022.10 and higher from an earlier release of SAS Viya then the new EITHER-OR model will apply after you upgrade. Any previous configuration settings to enable the generation of UID/GID information no-longer apply and will have no effect. If you as a SAS Administrator do not choose a mode, as we discussed above, you will have the default behaviour. Also, since the Identities microservice will automatically clean-up, then previous values for UID or GID used by SAS Viya might be lost.   For example, if in a previous release you were leveraging LDAP with POSIX attributes to provide your UID values – in the new default case you will now generate UID values. As soon as the Identifier endpoint is called for a given user their UID values will be replaced. This would happen as soon as your end-users log into SAS Studio, since the Launcher service will call the Identifier endpoint.   Therefore, before you upgrade you should understand how your existing environment is configured and how this will map to the new EITHER-OR model for the provision of UID/GID information. Otherwise, your end-users will not be able to access content after the upgrade.   What Should I Choose?   Finally, let’s review some different scenarios and look at the options you could choose to use.   Scenario: SCIM Environment with no file system access   In this case you don’t really care what UID and GID values are used. It makes sense to use generated UID and primary GID values, but you do not need secondary GID values. As such, you would set the options to:   sas.identities.identifier.generateUids = true sas.identities.identifier.generateGids = false sas.identities.identifier.disableGids = true   Scenario: POSIX Attributes in LDAP and using shared file systems   In this case you already have one version of the truth for user attributes in your LDAP. As such you want to ensure SAS Viya uses these LDAP POSIX attributes so you would set the options to:   sas.identities.identifier.generateUids = false sas.identities.identifier.generateGids = false sas.identities.identifier.disableGids = false   Scenario: Environment with shared file systems leveraging an existing group-based security model   In this case you are not particularly concerned with the UID values, but the secondary GID values are vital to your file system security model. This file system security model already exists, and SAS Viya must use the same GID values as your existing systems. As such, you would allow SAS Viya to generate the UID values, but you would provide your own GID values so you would set the options to:   sas.identities.identifier.generateUids = true sas.identities.identifier.generateGids = false sas.identities.identifier.disableGids = false   If you have an LDAP with the POSIX group attributes, you could use this. Alternatively, if you don’t have the GID values in LDAP you could instead load these into SAS Viya, as we discussed above.   Scenario: Environment with shared file systems leveraging a new group-based security model   In this case you are not particularly concerned with the UID values, but the secondary GID values are vital to your file system security model. But this is a new group-based security model, and it will only apply to SAS Viya. So, you will be able to use the GID values generated by SAS Viya to build this new file system security mode. As such, you would allow SAS Viya to generate both the UID & GID values so you would set the options to:   sas.identities.identifier.generateUids = true sas.identities.identifier.generateGids = true sas.identities.identifier.disableGids = false   You can then call the group identifier endpoint to discover the generated GID values to use in building your new security model.   Conclusion   With the SAS Viya 2022.10 Stable release changes have been made to how UID and GID information is made available to SAS Viya. The change to an EITHER-OR model will ensure that in the future there are no confusing setups where some UID/GID information for a set of users is provided whilst for another set, within the same environment, this information is generated. There might be some initial confusion as we move to this new model, but I hope that the information we have discussed here makes it much clearer. Moving forward this will be a more robust model for the provisioning of user attributes.   Find more articles from SAS Global Enablement and Learning here. ... View more

In the last post we talked about enabling custom attributes for Azure Active Directory OIDC Authentication. This was only half the picture; for those users to be able to authenticate to SAS Viya we need the Identities microservice to also leverage the same custom attribute for the accountID of the end-user. Otherwise, our end-user’s will not be able to log in. In this post we will examine how we can configure SCIM to send the custom attribute as the username.   Why?   First and foremost, why would you want to use something other than email address, user principal name, or objectID as the unique identifier for your end-users? If you are doing everything within Microsoft Azure; you are running SAS Viya, you are accessing data sources such as Azure SQL Server, utilising ADLS, accessing file in Azure storage accounts, etc. then there really is no need to look at changing the unique identifier for your end-users. Either of the three attributes; email, upn, or objectID, will be sufficient. However, if you need to access a mixture of cloud and on-prem resources you might want to consider using a different attribute to identify your end-users. For example, if you want to use Kerberos Hybrid authentication with Protocol Transition, you’ll need to ensure the unique identifier matches the Kerberos User Principal Name. Quite often the Kerberos User Principal Name will not match the Azure Active Directory user principal name.   Basic Setup   You need to have completed the basic setup for SCIM. This involves both the configuration of your SAS Viya environment and the basic setup with Azure Active Directory, as covered in the documentation. Equally I have also previously posted about the SAS Viya configuration and the Azure Active Directory configuration. This will result in you having an Enterprise Application registered in Azure Active Directory with the required Tenant URL and Secret Token configured. Then we can move onto looking at the attribute mappings.   User Mapping Settings   You should first make the changes to the Provision Azure Active Directory Users settings as per the documentation.   Select any image to see a larger version. Mobile users: To view the images, select the "Full" version at the bottom of the page.   If you select the userName attribute, the first in the list, you will find that you are able to select from several default source attributes. This list includes the extensionAttributes for the user, but only includes the onPremisesSecurityIdentifier. No other on-premises attributes are available for selection. When you select the option Show advanced options you only have the option to Edit attribute list for customappsso or the option to Use the expression builder, as shown here:     If you follow the link to Request additional attributes you would like to see supported here it opens the following page. This page has an important note with the following text:     So, as the note describes the only way to edit the attributes presented by Azure Active Directory is to start from the link: https://portal.azure.com/?Microsoft_AAD_Connect_Provisioning_forceSchemaEditorEnabled=true. Following this link will log you into the Azure Portal again and you will need to navigate to your Enterprise Application again and then edit the attribute mappings. Then once you get back to the user attribute mappings page and now select Show advanced options you will see the following:     Notice that now you have the option to Edit attribute list for Azure Active Directory. This means that you can edit the attribute list used by the first column in the attribute mapping table, that is the source attributes for the mapping. Selecting the link Edit attribute list for Azure Active Directory will take you to a table containing the available Azure Active Directory attributes. You can then add to the bottom of this list:   Name = onPremisesUserPrincipalName, Type = String Name = onPremisesSamAccountName, Type = String   Which will look like the following:     Then select Save at the top of the screen and select Yes when prompted "Are you sure you want to make these changes". This will return you to the attribute mapping page and you can now use either attribute for the customappsso userName attribute, the first in the list. Select Save again at the top of the screen to save your changes and select Yes when prompted.   This completes the changes required to use either the on-premises User Principal Name or SAM Account Name as the userName attribute with SCIM. This means that SAS Viya will leverage this attribute as the unique identifier for your end-users and this will match the attribute used in the ODIC configuration.   Validate   You can now either provision all your users and groups to SAS Viya; or a better option is to provision a single user to validate your settings. From the main Provisioning page of your Enterprise Application there is an option to Provision on demand. The option to Provision on demand will allow you to provision a single selected user and so validate your settings. On the Provision on demand screen, you can select the user you want to test with, as shown here:     The results from provisioning on demand allow you to review the status and resolve any issues before provision all your users. For example, setting the userName to onPremisesUserPrincipalName and validating with Provision on demand for my test user shows the following:     If I also check in SAS Environment Manager, I can see my test user correctly provisioned into SAS Viya:    As you can see in SAS Viya, my test user is now identified with its on-premises User Principal Name rather than any other Azure Active Directory attribute.   Hopefully, this shows how helpful the option to Provision on demand is for validating the correct configuration before you attempt to provision hundreds of users.   Removing SCIM Users/Groups from SAS Viya   If we are testing our changes against a SAS Viya environment, you will probably need to remove the existing users and groups that Azure Active Directory has already provisioned into the environment. I previously wrote about an easy method to remove the SCIM users and groups. This leverages the existing valid OAuth Bearer token providing access to the SCIM endpoints of the Identities microservice and submits a HTTP DELETE request. In that previous post I also provided an example script to remove all the SCIM users and groups from a SAS Viya environment.   Conclusion   If you need to use an attribute such as on-premises User Principal Name for your users of SAS Viya, perhaps to make use of Kerberos Hybrid authentication with Protocol Transition, then you’ll need to complete the steps we have covered here and in the previous post. With both SCIM and ODIC configured to use the on-premises User Principal Name, your end-users accessing your SAS Viya environment with OIDC authentication will now be correctly identified by their on-premises User Principal Name. Then the SAS Kerberos Proxy will be able to obtain Kerberos credentials for your users using the correct UPN value and make these credentials available to your SAS Cloud Analytics Services and SAS Compute Server sessions. These credentials can then be used to access your data sources using Kerberos.   Find more articles from SAS Global Enablement and Learning here. ... View more