Get list of available scopes (for creating a client)

[AllanBowe]

When creating a client (using the "uaa.admin" scope) you can provide a list of available scopes (eg "openid" for authentication, plus "*" for all scopes, or a list of Viya group memberships).

The documentation also shows some alternative scopes, eg "clients.read" and "clients.write".   It's stated in the REST docs that the default is  "uaa.none".

Where can one find the full list of available scopes (ideally with descriptions) that could be used to create a client with the appropriate capabilities?  

Also, what is the link to / difference with "authorities" ?  It sounds as though this might be a subset of scopes that the client can manage..  I don't see how this is implemented in practice though.

[MikeRoda · Accepted solution]

Hi Allan,

There are two types of scopes, internal scopes only understood by the saslogon service, and external scopes that come from group memberships. First let’s discuss the internal scopes. The SAS Viya Logon Manager (saslogon service) is based largely on the open source Cloud Foundry UAA project.  UAA surfaces an API with many endpoints requiring a bearer token with certain scopes. These scopes are internal to the UAA code and not used by any other services. Refer to the UAA API online to see what internal scopes are needed when calling the APIs. Here is a link to the version currently shipping in SAS Viya 3.5:

http://docs.cloudfoundry.org/api/uaa/version/4.30.0/#overview

Next let’s discuss external scopes. First of all, understand that groups are treated as scopes. When a user signs in, the user's group memberships are queried from LDAP. These are treated as scopes and included in the access token for the user. Then when a SAS Viya API is called, either by the user interface or with a bearer token, the scopes are treated as groups again, and authorization rules are applied to those groups.

Now let's talk about how this applies to oauth clients. The scopes assigned to an oauth client are the scopes (groups) that the client is allowed to obtain on behalf of a user, when obtaining access tokens using an authorization or password grant, for example. Now this is going to get a little complicated but the scopes that end up in the access token are the intersection between what scopes client is allowed to request, what scopes (groups) the user actually has, and what scopes the client requests when it asks for the token (which may be less than what it is allowed). Many clients are registered with scope * because we don’t know ahead of time all the external groups that users may have.

Lastly, you asked about the difference between scopes and authorities. The authorities assigned to an oauth client are the scopes that the client will itself have when obtaining access tokens using its own client credentials. This must be a specific list, it cannot contain the wildcard *. So you use authorities if you will be obtaining tokens this way.

I wrote a paper for the 2018 SAS Global Forum that touches on some of this. Here is a link:

https://www.sas.com/content/dam/SAS/support/en/sas-global-forum-proceedings/2018/1737-2018.pdf

Hope this helps. Thanks for asking.

Mike

[AllanBowe]

Thanks for taking the time to write this up Mike - it is super helpful. FWIW we built a small web app to help admins quickly generate different types of token. It's not completely finished / functional but could be interesting for anyone else exploring this functionality: https://github.com/sasjs/viyatoken