Previous articles presented the evolved architecture and capabilities that helped SAS/CONNECT move to dynamic cloud environments with SAS Viya. This time the focus is on the programmers: let's see some sample code that can leverage these new capabilities!
The first step in every program that leverages SAS/CONNECT is to submit a SIGNON statement from a client session to start a remote server session: that remote SAS/CONNECT session will be available to execute SAS code and to upload or download data from/to the client.
From a programmer’s point of view, there are two key information pieces that a client needs to provide – either explicitly written or implied with a default value – to be able to successfully start a SAS/CONNECT session:
- where will the remote session start – i.e., what is the backend server name?
- how does the client session authenticate?
In the following sections, we present some sample code snippets that show how to perform the initial SIGNON to SAS Viya in different cases - from the same Kubernetes clusters, or from an external client; across different releases (SAS Viya and SAS 9.4) – and leveraging different authentication methods: with interactive or hard-coded username and password, using authinfo files, or sharing OAuth tokens.
Spawner Sign-on from Internal Clients
Let’s start with the simplest use case: you are working within SAS Studio in a SAS Viya environment, and you want to start a SAS/CONNECT session in the same cluster, authenticating as yourself. The code is really simple:
/* launch a SAS/CONNECT session on the same cluster */
%let session1=sas-connect-spawner 17551;
/* authenticate re-using the already logged-in credentials */
SIGNON session1 user="_OAUTH_";
You can see that we used sas-connect-spawner as the hostname; this maps to the internal Kubernetes services with that name, listening on the SAS/CONNECT default port 17551. Kubernetes takes care of finding the correct pod on the correct host and directs the connection there. The authentication uses the OAuth protocol to sign in as the same user already logged into the client – more on that later.
Spawner Sign-on from External Clients
A more common use case is when you are writing your code in a client executing in a different environment than the cluster where the SAS/CONNECT server will start. For example, you want to connect a legacy SAS 9 environment to a modern SAS Viya cluster running in the cloud.
First, your SAS Administrator should have already configured all the required parts:
The details of these steps are out of scope for this article, you can reference the linked documentation pages for more info.
Once that’s done, as a programmer you can connect like this:
/* launch a SAS/CONNECT session from outside the cluster */
/* set TLS connection options */
OPTIONS NETENCRYPTALGORITHM=SSL;
/* connect using a fully-qualifies hostname or DNS alias */
%let session1=connect.gelenable.sas.com 17551;
/* authenticate with username and password */
SIGNON session1 user="Alex" password="My1Password!";
Notice the explicit set of the NETENCRYPTALGORITHM option. While this corresponds to the default for SAS Viya, SAS 9 clients may have a different value and the connection may fail if not set like this.
While this example shows a connection to the default 17551 port, your administrator could have configured the service to listen on a different one.
The hostname specified to connect is either the fully qualified hostname of the service exposing the SAS/CONNECT spawner (usually a cloud load balancer) or a DNS alias that points to it.
Note: to be able to connect from SAS 9 or SAS Viya 3 clients, they need to be patched with the hotfixes documented within the SAS Usage Note https://support.sas.com/kb/68/611.html .
Grid Sign-on
Starting with SAS Viya 2022.1.4 and later, it is possible to use the grdsvc_enable function to start a SAS/CONNECT server session in a dynamically launched pod. This is the evolution of the similarly named function used in SAS 9 SAS Grid Manager clients, but with SAS Viya it comes with a great advantage: it just works with any SAS Viya license - no SAS Workload Management required!
For the initial release, it is only possible to use this capability from a client co-located in the same Kubernetes cluster as the server.
The grdsvc_enable function is used to specify the 'context' to be used by the SAS/CONNECT service to have the Launcher service start the SAS/CONNECT server pod.
%put gs_rc=%sysfunc(grdsvc_enable(session1,"context=default-launcher"));
SIGNON session1;
Notice that we did not specify a username or a password; the client automatically sent in the OAuth token to sign in as the same user already logged into the client. Similarly, we did not specify any server/service hostname: grid-enabled sign-ons automatically connect to the SAS/CONNECT service that is in the same environment as the client. It is possible to automatically use this capability for all sessions and not only for the current one:
%put gs_rc=%sysfunc(grdsvc_enable(_ALL_,"context=default-launcher"));
SIGNON session1 signonwait=NO;
SIGNON session2 signonwait=NO;
The "signonwait=NO" helps run your code in parallel because it lets SAS/CONNECT sessions start asynchronously.
Architecture note: this capability bypasses the SAS/CONNECT spawner and uses the SAS/CONNECT service instead. This should be completely transparent to users.
MP CONNECT Sign-on
This is also referred to as SASCMD sign-on in the documentation.
MP CONNECT sign-ons always start a new process in the same pod that the client process is running in: there is no connection to any spawner or service. While this permits leveraging parallelization in your code, it is limited in scalability because all sessions share the same resources (CPUs, memory, I/O), since they are all hosted in the same pod, on the same node.
By default, if you omit both USER= and PASSWORD= options in the SIGNON statement, SAS Viya performs an MP CONNECT sign-on – ignoring any server name you may have specified to connect to.
SIGNON session1;
The SIGNON statement supports the SASCMD option to specify further options to influence how the children sessions are started. With SAS Viya, though, all options are ignored, and the default command is used because the LOCKDOWN option is enforced by default. To be able to use the SASCMD option, an administrator would have to disable LOCKDOWN (not recommended for the security implications).
Authentication
After discussing multiple ways to connect to SAS Viya using a SAS/CONNECT session, let’s talk about authentication, and how to specify user credentials on the SIGNON command. SAS/CONNECT on SAS Viya can currently authenticate clients by supporting four different methods:
- username/password
- OAuth
- authinfo files
- Kerberos
Username and password
While this is the simplest authentication method, it is also the less secure, since it requires to hard-code user credentials in your code:
SIGNON session1 user="Alex" password="My1Password!";
Passwords can be encoded with PROC PWENCODE, but that only offers basic security: for example, it does not protect from replay attacks.
OAuth
OAuth authentication relies on the exchange of access tokens between services, which is the default SAS Viya internal authentication method. No passwords are exchanged, and this is considered the most “cloud-native” model.
To enable OAuth authentication, specify “_OAUTH_” as the username. To sign on from an internal client, do not specify any password: the SAS/CONNECT client will automatically pass the OAuth token that it acquired at initial logon to the SAS/CONNECT spawner:
SIGNON session1 user="_OAUTH_";
To sign on from an external client, the OAuth token should be acquired in some other way, then specified as the password:
%let token=eyJhbGcz1N ... ... ... OlXlI1UN6XQ;
SIGNON session1 user="_OAUTH_" password="&token";
As an example, if you have the SAS Viya command-line interface installed on the client, you can use that to sign into SAS Viya, and that will save a usable token on your client, in the credentials.json file located in your home directory.
Notice that the token is usually a long sting, and SAS may output a warning note that can be safely ignored:
87 %let
87! token=eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbG9jYWxob3N0L1NBU0xvZ29uL3Rva2VuX2tleX
...
...
87! 1UN6XQ;
88 SIGNON session1 user="_OAUTH_" password="&token";
NOTE: The quoted string currently being processed has become more than 262 bytes long. You might have unbalanced quotation marks.
Authinfo files
Hard-coding your username and password credential in the SIGNON statement not only is a bad security practice, but does not permit sharing code between different people. A better way to store and specify credentials, while still using username and password to SIGNON, is provided by AUTHINFO files.
An authinfo file contains user IDs and passwords that are used for authentication. To use an authinfo file, specify _AUTHINFO_ as the value in the PASSWORD= option in the SIGNON statement. If there is more than one user ID in the authinfo file, specify a value for the USER= option to select which one to use.
By default, SAS/CONNECT looks for an authinfo file in the client user home directory (on Windows, that’s usually C:\Users\<username> ); you can specify another location, for example with the AUTHINFO= system option.
SIGNON session1 password="_AUTHINFO_";
Kerberos
Within SAS Viya, Kerberos is enabled by default, but it has to be properly configured by your administrator. Once that is done, signing on with Kerberos is as simple as writing:
SIGNON session1 user="_SSPI_";
Debugging
While testing the code for this article, configuration errors and wrong statements were inevitable. Why not capture the error messages that SAS outputs?
Here they are, all collected for your reference, together with possible solutions if you’ll make the same mistakes I did!
ERROR: Windows SSL error -2146893019 (0x80090325) occurred at line 2696, the error message is "The certificate chain was issued by an authority that is not trusted. "
ERROR: A communication subsystem partner link setup request failure has occurred.
ERROR: Network request failed (rc 0x033C2F90) - Windows SSL error -2146893019 (0x80090325) occurred at line 2696, the error message is "The certificate chain was issued by an authority that is not trusted. "
Or
ERROR: Windows SSL error -2146869244 (0x80096004) occurred at line 2696, the error message is "The signature of the certificate cannot be verified. "
ERROR: A communication subsystem partner link setup request failure has occurred.
ERROR: Network request failed (rc 0x3B2C40F0) - Windows SSL error -2146869244 (0x80096004) occurred at line 2696, the error message is "The signature of the certificate cannot be verified. "
This means the SAS Viya Root CA was not imported into the client truststore. See
https://go.documentation.sas.com/doc/en/sasadmincdc/v_032/calencryptmotion/n1xdqv1sezyrahn17erzcunxw...
and
https://go.documentation.sas.com/doc/en/sasadmincdc/v_032/calencryptmotion/n1xdqv1sezyrahn17erzcunxw...
ERROR: A communication subsystem partner link setup request failure has occurred.
ERROR: Network request failed (rc 0x033C2EF0) - SSL Error: Invalid subject name in partner's certificate. Subject name must match machine name.
This means the TLS certificate presented by SAS/CONNECT spawner does not include the external hostname or DNS alias used to connect to the server. See
https://go.documentation.sas.com/doc/en/sasadmincdc/v_032/calencryptmotion/n1xdqv1sezyrahn17erzcunxw...
ERROR: A communication subsystem partner link setup request failure has occurred.
ERROR: The connection has timed out.
This is a generic error when the client cannot reach the SAS/CONNECT spawner. It may mean that the spawner is not listening on the hostname/port specified. Also, make sure that the SAS/CONNECT spawner has been enabled to support external clients. See https://go.documentation.sas.com/doc/en/sasadmincdc/v_032/dplyml0phy0dkr/n08u2yg8tdkb4jn18u8zsi6yfv3...
Another reason may be that there is a firewall blocking access, in which case refer to your IT department to have it open.
ERROR: A communication subsystem partner link setup request failure has occurred.
ERROR: Cannot negotiate encryption algorithm.
This could be due to a mismatch between client and server TLS configuration. See
https://go.documentation.sas.com/doc/en/pgmsascdc/v_031/viyaconnref/n0pj55r718uoj3n1jjp89k1jfrgx.htm
ERROR: A communication subsystem partner link setup request failure has occurred.
ERROR: Communication request rejected by partner: security verification failure.
Either username/password credentials are wrong, or, if using a AUTHINFO file, you may have specified USER=”_AUTHINFO_” instead of PASSWORD=”_AUTHINFO_”.
ERROR: A communication subsystem partner link setup request failure has occurred.
ERROR: Retrieval of credentials from authinfo file failed.
When using an AUTHINFO file, the SAS client was unable to either find or read it.
Conclusion
In this article, we have seen the different ways a programmer can use the SIGNON statement to specify the connection and authentication parameters to start a SAS/CONNECT session in a SAS Viya cluster. Are you leveraging SAS/CONNECT in your SAS Viya environments? Let us know in the comments!
Find more articles from SAS Global Enablement and Learning here.
