SAS REST APIs: Authentication & Authorization

SAS Viya provides authentication services with the SAS Logon Manager. SAS Logon Manager is based on the Cloud Foundry User Account and Authentication (UAA) server and its OAuth 2.0-based services. These services are built around Open Authorization (OAuth) and OpenID Connect. OAuth 2 is an authorization framework that enables applications to obtain limited access to secured HTTP resources such as those provided via SAS Viya APIs. SAS Logon Manager uses OAuth policy to enforce the access token to allow access to protected resources.

OAuth 2 works by delegating user authentication to the service that hosts the user account, and authorizing third-party applications to access the user account. OpenID Connect is an extension to OAuth 2.0 for authentication that uses an ID token to present claims about the identity of the end user as well as other metadata such as tenant identification. While actual authentication may be delegated to a Lightweight Directory Access Protocol (LDAP) provider, SAS Logon Manager also support authentication via Kerberos, OAuth, and Security Assertion Markup Language (SAML). Simply put, this means that SAS Viya integrates with the identity management system that your organization uses.

The SAS Viya REST APIs rely on the OAuth2 features of SAS Logon Manager for all operations that require authentication.

1. Developers contact the organization's SAS administrator to register a client application.
2. The SAS administrator registers the client and provides a client secret for the developers to use.
3. Developers implement code to acquire the token that is used for API calls. The request for the token must include the client identifier and client secret that were previously registered.
4. The acquired token is passed on API calls. Tokens typically are valid for 12 hours (unless set to another value during registration).

That's it. The authenticated token is passed on subsequent requests to identify the caller. If a valid OAuth2 token is not provided on the call, the operation fails with a standard 401 Unauthorized response code. SAS REST APIs use the OAuth2 tokens to authorize specific REST API operations. For example, an authenticated user may have authorization to read a resource via a GET method, but not have authorization update or delete a resource via a PUT or a DELETE methods.

Registering clients

All applications and scripts that make use of the SAS Viya REST APIs must be registered with the SAS environment. In practice, this registration is handled by the SAS administrator properly configuring a client with the OAuth service in SAS Logon Manager.

To register a client:

1. Locate a valid Consul token. (SAS Logon Manager has an endpoint that issues an OAuth access token to requests that contain a valid token from the SAS Configuration Server.) A SAS administrator can find a token in the client.token file at /opt/sas/viya/config/etc/SASSecurityCertificateFramework/tokens/consul/default. On a Linux system, run
   
   $ cat client.token
   
   to get the token string. Copy the value for later use.
2. Request a valid OAuth token to use on the registration call. For example, to register a client named app:
   

       curl -X POST "http://example.com/SASLogon/oauth/clients/consul?callback=false&serviceId=app" \
         -H "X-Consul-Token: <value-of-consul-token-goes-here>"
     

   Query parameter	Description
   callback	Set to false to receive an access token in the response, otherwise the token is sent to the service registered in SAS Configuration Server.
   serviceId	Name of the client to register

   
   
3. Use the value of the access_token field returned in the response JSON to register the new client:
   
   

        curl -X POST "https://localhost/SASLogon/oauth/clients" \
           -H "Content-Type: application/json" \
           -H "Authorization: Bearer <access-token-goes-here>" \
           -d '{
             "client_id": "app",
             "client_secret": "<secret-goes-here>",
             "scope": ["openid"],
             "authorized_grant_types": ["password"],
             "access_token_validity": 43199
            }'
   
   

   Note: There are other "authorized_grant_types" supported, but SAS Viya REST APIs currently expect the password grant type. By default, a token is valid for 12 hours (or 43200 seconds). To set a shorter duration, set access_token_validity field as needed, using an integer value for time in seconds.
4. If the request is successful, the client is registered. The JSON response looks like:
   

         Example:
           {"scope":["openid"],"client_id":"app","resource_ids":["none"],"authorized_grant_types":["password","refresh_token"],
             "access_token_validity":43199,"authorities":["uaa.none"],"lastModified":1521124986406}
       

Obtaining access tokens

Registered clients can request an access token using the SAS Logon OAuth API. Access tokens are obtained when a client makes a request and authenticates to the /SASLogon/oauth/token endpoint and passes a form of authorization. The authorization is expressed in the form of an authorization grant. Currently, SAS Viya REST APIs support the password grant type.

For example, given a client identifier of "app" with a secret "mysecret," a client must pass user credentials to authenticate and receive a token:

   curl -X POST "https://server.example.com/SASLogon/oauth/token" \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=password&username=<user-id>&password=<password>" \
      -u "app:mysecret"

Making API requests with access tokens

Once a client has a valid access token to use on behalf of a user, requests to SAS Viya REST APIs should use that token. The token can be passed to the API either as a query string parameter or on the HTTP Authorization header (which is the preferred approach). For example:

   curl -X GET "https://server.example.com/folders/folders/@myFolder" \
      -H "Accept: application/json" \
      -H "Authorization: Bearer <TOKEN-STRING>"