Configuring Enterprise Miner to chat with CAS
As the capabilities of SAS 9.4M5 are enhanced to interoperate with Viya 3.3, you may expect that once the Viya deployment is configured and running that the SAS 9.4M5 clients would be ready to communicate with CAS. But if specific "default" settings for CAS are taken within the Viya 3.3 deployment, communications between the environments would fail. For example, if you attempt to create a CASLIB from an Enterprise Miner project, the instantiation of the CAS session would result in messages about SSL errors. To understand why this occurs and how to ensure that the Enterprise Miner client can interact with CAS, please continue reading.
Reflecting back to the summer of 2017
Prior to 9.4M5 it was possible for Enterprise Miner clients to talk to CAS, but it was accomplished via SAS/CONNECT. Essentially the EM workspace server would communicate with a Viya CONNECT spawner and then a CONNECT server, followed by RSUBMITing code to the Viya server. The results would then be returned to the local EM session.
In essence the user would logon to the SAS 9.4 environment with a known account in metadata and then connect to SAS/CONNECT in the Viya environment with different credentials passed as macro variables. Then the credentials required to initiate a CAS session were stored in an authinfo file on the host where the CONNECT spawner resides. The CONNECT server on Viya used these credentials to fire up the CAS session. This was a clever, although somewhat complicated, way to get the two environments to work together using technology that has been around many years.
Returning to the present
You are now probably aware that the aforementioned method is no longer necessary. SAS 9.4M5 is now enabled to "talk" directly with CAS. The September 2017 release of SAS 9.4M5 introduced some procedures that communicate directly with CAS, and the December 2017 release introduced even further integration with Viya and CAS. As a result of this change there are new steps to take in order to get the SAS 9.4M5 environment to talk with CAS.
Encryption
If you've been paying attention to the new features of Viya 3.3, you may have noticed that there are substantial improvements with encryption and authentication. I'll let Stuart Rogers do the heavy lifting with these topics, but one key aspect of a Viya 3.3 deployment is the introduction of CAS encryption as the default setting. Therefore, getting SAS 9.4M5 to communicate with CAS to requires some configuration and manipulation of certificates.
The setting for client encryption can be found in /opt/sas/viya/config/etc/cas/default/casconfig_deployment.lua. The parameter to enable encryption is env.CAS_CLIENT_SSL_REQUIRED. Here is a snippet of the section for TLS enablement from the test environment.
Although it is not recommended, this variable can be overridden in vars.yml prior to deployment.
The Test Environment
The first step is to understand the environment.
The key pieces of the testing environment that are referenced in this blog are the sasclient and the CAS Controller. The sasclient has a full deployment of VA 7.4 and Enterprise Miner 14.3 on a Windows 2012 server. And the CAS Controller is running on a RHEL 7.4 machine. The Windows machine is using local accounts for the deployment and authentication, while the Viya 3.3 deployment and CAS use a local LDAP instance. Here the key pieces for integration are shown.
Configuring . . .
As noted earlier, since encryption is enabled by default it is necessary to ensure the correct certificates are in place. If an attempt is made to initiate a CAS session from Enterprise Miner and certificates are not in place, a message similar to the following will be displayed:
. . . Steps
In order to configure encrypted communication, the following steps are required:
- Locate the file containing the proper certificates on the Viya/CAS machine
- Import the root certificate into the Windows Trusted certificate stores
- Add the SAS 9.4 client certificates to the trusted certificates of the 9.4 deployment
- If connecting to the SAS 9.4 and Viya environments with different authentication methods, define an authinfo file containing credentials for the Viya environment
Locate CA certificate for the CAS Server
The CA certificate used to sign the certificate that CAS uses can be located in /opt/sas/viya/config/etc/SASSecurityCertificateFramework/cacerts on the CAS controller machine where the vault service is deployed. There are multiple files in this directory, but the one that is needed is the vault-###-ca.crt.
Copy this file to the Windows client machine.
Split the certificates and import into the Windows Trusted Root Certification Authority
The vault-###-ca.crt file actually contains two certificates: the SAS Viya root CA certificate and the intermediate certificate. The following shows an abbreviated example file.
These certificates need to be split into two files. As you can see they are delineated by the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- tags. The first certificate is the SAS Viya root CA certificate and second is the intermediate certificate. Once the two certificate files are created, import the root certificate into the Windows CA store.
Although the detailed steps for importing the certificates into the Windows CA stores could be listed here, they are well documented here. Using the capabilities of the MMC (Microsoft Management Console), add a Snap-in and walk through the steps of importing of certificates. In the end the certificate should be available and visible within the MMC. An example is shown here.
Add the SAS Viya CA certificates to the SAS 9.4 trusted CA certificates location
Finally the SAS Viya CA root certificate and intermediate certificate need to be added to the SAS 9.4 trusted certificates. The location for the SAS 9.4 trusted certificates is at <SASHome>/SASSecurityCertificateFramework/1.1/cacerts/trustedcerts.pem
Although it is possible to use a text editor to append the certificates to the trustedcerts.pem file, it is highly recommended to use the SAS Deployment Manager. The SAS Deployment Manager takes a backup of files prior to updating the existing trustedcerts.pem file. When prompted to select the SDM task, select "Add Certificate to Trusted CA Bundle".
Then select the appropriate certificate, first the root and then the second iteration select the intermediate certificate. This example shows the root certificate.
When the task is complete, review the location of the trustedcerts.pem file.
Notice that a copy of the root and intermediate certificates are stored here, the trustedcerts.pem file has been updated and that a backup directory exists for storage of the previous state of trusted certificates. We're almost there.
Create an _authinfo or .authinfo file (maybe)
If the credentials used to logon to the SAS 9.4 environment are different than the credentials used in the Viya environment, then it will be necessary to create an _authinfo file for the user that will be logging into the Enterprise Miner client. In the test environment, the sasdemo account was used to logon to Enterprise Miner. That account did not exist in the SAS Viya environment. So the _authinfo file was created and stored in C:\Users\sasdemo.
If the workspace server started on behalf of the Enterprise Miner client is running on Linux, then the credentials should be stored in .authinfo file. This file should be saved in the home directory of the account used to logon to the Enterprise Miner client and given permissions of 600. For example, if sasdemo is an account on RHEL, then the .authinfo would be saved in /home/sasdemo/.authinfo.
Most likely you've seen the format of the _authinfo file, but if not, here is an example of the one used for testing.
intcas01.race.sas.com is the host machine where the CAS controller is installed and it listens on port 5570. The next two parameters specify the user credentials.
Steps in the Enterprise Miner client
In order for the Enterprise Miner client to know how to contact CAS, there are two more areas of setup. Once the Enterprise Miner project is created, select the project name and then select ellipses for the "Project Start Code".
Then in the editor add the _authinfo option if it is being used, followed by macro variables for the CAS host and CAS port.
In this test project, only two objects were defined. The first object is the data source. In this case it was the CARS dataset. The second object was SAS Viya Code. So the project was quite simple. In this screen shot the project had already been executed once.
Select the SAS Viya Code object and the "Code Editor" property in the Train section. In the Training Code window you will notice that two additional macro variables need to be defined: "caslib" and "casuser".
Once these are set the window can be closed and the project executed. Successful execution is indicated by the green checks. But to be certain, review the log. The CAS session should be started and the Public CASLIB assigned.
One more possible item
For SAS 9.4M5 deployments prior to 17w47 on Linux, it will be necessary to set the CAS_CLIENT_SSL_CA_LIST environment variable to the list of trusted certificates. This variable can be set in the <SASHome>/SASFoundation/bin/sasenv_local file. Example follows:
That's all folks.
Final Thoughts
In a Viya 3.3 deployment the default settings for CAS will enable encryption for client communication. This means some CA certificate setup must be completed on the client before it communicates with CAS. In this example the configuration was completed for the Enterprise Miner client, but similar setup must be done for SAS 9.4M5 and other clients.
My thanks to Stuart Rogers, the encryption and authentication guru, for his guidance on this topic.
Stay tuned for tips on configuration of other non-SAS clients.
References
SAS Viya 3.3 Administration: Data in Motion
Add Certificates to the Windows CA stores
