Connecting to SAS Viya for Learners from a Remote Jupyter Notebook

[#1]

A question came through the SAS Communities a few weeks ago asking, "Can we connect SAS Viya for learners from macOS terminal via Python SWAT library?" The answer is, "Yes". In this article, I'll cover how users can connect to SAS Viya using the SWAT package.

First, I'd like to point out that there is an easier (and recommended) way to make the connection outlined in this article. SAS Viya for Learners users have access to a Jupyter environment that is directly linked to the SAS Viya instance. Add /hub to the server URL. This launches a Juypter hub. Once in the hub, create a notebook and run the following commands:

For Python

import swat, os

conn = swat.CAS(os.environ['CAS_CONTROLLER'], 5570, password=os.environ['ACCESS_TOKEN'])

For R

library(swat)

conn <- swat::CAS(Sys.getenv('CAS_CONTROLLER'), 5570, password=Sys.getenv('ACCESS_TOKEN'))

And Voilà, you're connected. This article will only cover the remote connection for Python. If there's a need for an R equivalent, please leave a comment. 

Users may have reasons for not following this simple procedure, so I'll explain how to make the SWAT connection from a local Jupyter Notebook. The steps and commands are slightly different for Windows users vs Mac and Linux. I'll cover both below.

Windows Users

Follow these steps to make the SWAT connection. These steps MUST be carried out using Windows PowerShell. They will not work in the Command Prompt, Git Bash, or any other shell.

Extract the Public Certificate

You will need to extract out the public certificate.  To do this, I did the following replacing <server.demo.sas.com> with actual value:

echo -n | openssl s_client -showcerts -connect <server.demo.sas.com>:443 -servername <server.demo.sas.com>:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > certificate.pem

Please note that you need to remove the https:// from the server name, in both instances. This copies the Viya certificate to your local home directory. Normally this will be in C:\users\<your user name>.

Extract Access Token

For Viya for Learners 4, you will be using single sign on. As a result, you will need to extract your access token:

1. On your browser, go to https://<server.demo.sas.com>/SASLogon/oauth/authorize?client_id=sas.SWAT&response_type=token
2. This will generate the access token within a new URL. Users will need to extract the token from this URL.
3. Copy the entire URL and paste it into a text editor. 
4. Remove the http://...access_token text from the beginning of the URL.
5. Remove everything after the &expires_in... at the end of the URL.
6. Copy the remaining text. This is the access token.

Create an Environment Variable

1. Export out the token in your OS: 

[Environment]::SetEnvironmentVariable('ACCESS_TOKEN','eyJhbGciOiJSUzI1NiIsImprdSI6Imh0d.......','user')

 Launch Jupyter

This step must be done in a new Windows Powershell window.

1. Start a new Windows PowerShell session
2. Launch Jupyter

Jupyter Lab

Upload Certificate and Notebook

In the Jupyter lab, upload the certificate.pem and Remote_SWAT_Connection_Win.ipynb Jupyter notebook to either the home directory or a directory of your choice.

Open and Run

Open the Remote_SWAT_Connection_Win.ipynb Jupyter notebook. In the first cell, fill in the SAS Viya server URL and file_path. Run the cell to create the variables. The second cell makes the connection to SWAT and prints out the connection information.

Below is a representation of the experience in Jupyter.

Note

Please note that the access token is good for an hour. You'll have to run through the process again after that time. This is another reason it is recommended you use the Jupyter hub attached to the SAS Viya environment to make SWAT connections.

Mac and Linux Users

Follow these steps to make the SWAT connection in a zsh shell.

Extract the Public Certificate

You will need to extract out the public certificate.  To do this, I did the following replacing <server.demo.sas.com> with actual value:

echo -n | openssl s_client -showcerts -connect <server.demo.sas.com>:443 -servername <server.demo.sas.com>:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > certificate.pem

Please note that you need to remove the https:// from the server name, in both instances. This copies the Viya certificate to your local home directory. Normally for the Mac this will be in /Users/<your user name>. For Linux it will be /home/<your user name>.

Extract Access Token

For Viya for Learners 4, you will be using single sign on. As a result, you will need to extract your access token:

1. On your browser, go to https://<server.demo.sas.com>/SASLogon/oauth/authorize?client_id=sas.SWAT&response_type=token
2. This will generate the access token within a new URL. Users will need to extract the token from this URL.
3. Copy the entire URL and paste it into a text editor. 
4. Remove the http://...access_token text from the beginning of the URL.
5. Remove everything after the &expires_in... at the end of the URL.
6. Copy the remaining text. This is the access token.

Create an Environment Variable

1. Export out the token in your OS: 

export ACCESS_TOKEN=eyJh9iiskgK…

Copy Jupyter Notebook from GitHub

1. Download the Remote_SWAT_Connection_Mac_Linux.ipynb Jupyter notebook from the sascommunites GitHub.

 Launch Jupyter

1. Launch Jupyter

Jupyter Lab

Upload Certificate and Notebook

In the Jupyter lab, upload the certificate.pem and Remote_SWAT_Connection_Mac_Linux.ipynb Jupyter notebook to either the home directory or a directory of your choice.

Open and Run

Open the Remote_SWAT_Connection_Mac_Linux.ipynb Jupyter notebook. In the first cell, fill in the SAS Viya server URL and file_path. Run the cell to create the variables. The second cell makes the connection to SWAT and prints out the connection information.

Below is a representation of the experience in Jupyter for Mac OS. Linux would be the same output except /Users/... would be replaced with /home/...

Note

Note that the access token is good for 10 hours. You'll have to run through the process again after that time. This is another reason it is recommended you use the Jupyter hub attached to the SAS Viya environment to make SWAT connections.