How to use OAuth 2.0 roles and scopes to secure services

Question

I have secured a REST API using OAuth 2.0 security, and I am not sure on how to configure security access using roles or scopes.

There will be three types of clients:

• Public mobile app client used by end-users that can access their profile, data, etc. (using password grant type). By "public" I mean that the app is intended from any user and available to any user from Google Store, etc.)
• Non-public administration client used only from me for administrative purposes that can access administrative services not allowed to be used by normal users (using client_credentials grant type).
• Non-public third-party client (using client_credentials grant type) that will use some services created specifically for them.

Should I just create three different roles, User, Admin and ThirdPartyX and secure services with 'oauth2.clientHasRole' rules? Or should I create different scopes and do not care about roles? Is there a general rule of thumb on where would I use roles or scopes in general?

Answer 1

I think it is important to keep the bigger picture of federated identity and access control in mind.

There is always a resource owner, a resource server and some client that wants to access resources maintained by the resource owner on behalf of the resource owner. And then there is an identity provider (or authentication server) that issues tokens containing the access control which all involved parties will trust.

Scopes are used to define different access control levels to the API of the resource server.

For instance, the Google API has scopes to read user profile data, edit user profile data, etc.

The scope included in the access token defines what permissions the user granted to a client application (e.g. some SPA) to access the resource server's API on behalf of that user.

User groups (or roles) on the other hand define what "a specific user is allowed to do* at the resource server's backend API. And this information could be included in the claims provided in the issued access token. But how this information is provided depends on the used identity provider service.

It could also be provided via some user info endpoint API for which you again have a specific scope to access that information from the user info resource server.

So in your case you could have some two-level access control:

• The first level is based on scopes which only allows specific clients to access specific functionality of the API on behalf of the user based on the granted scopes
• The second level is dependent on the current user rather than the application and makes sure the user only accesses resources and functionality they are allowed to access. This can be done on groups or role information (i.e. claims about the user) included directly in the issued access token or requested via some kind of user info endpoint via a separate request.

For example, by giving client (A) the scope to have read access to googles user profile data the user allows client (A) to make the call to Google's user profile API read methods in general.

Based on the user's identity (i.e. the subject claim in the token) Google is able to see - after checking the calling client application has the required scope - if that user is also allowed to read the profile information of that specific user profile based on the subject of the user. Let's say the user only belongs to the "normal" user group they can only access their own profile information.

If the user is also part of a specific group, e.g. an admin group, it can also be allowed to read any profile information, even if the profile id does not correspond to the subject claim of the current user. This would be the finer grained group-level access based on the user rather than the client application.

Answer 2

There is usually no golden right way for the problem. However, there are a few guidelines:

Use the scope request parameter as indicated in the IETF standard.

Use the claim in the JWT payload with an HMAC256 signature to verify the claims are issued by the server.

Map your roles permissions data to an RBAC database schema (but we usually use MongoDB with NoSQL).