Oauth2, scopes and user roles

Question

I am asking a question conceptually here as I am trying to understand the relationship between scopes and user roles in an OAuth2 based system.

As I am implementing an API, I want to restrict access to specific resources by using scopes on the resources. I understand the use of access tokens to request resources, and I believe my understanding to be correct in that you specify your scope(s) when requesting the access token.

What I am not entirely sure of is how restriction of scopes would work based on specific roles that an authenticated user is in. Let's assume Bob is an admin and Sue is a regular user. We have some resources protected by an is_admin scope. What stops Sue from requesting (and receiving) is_admin scope in her access token?

I am thinking that what should happen is the following:

• Bob authenticates.
• Bob's roles are looked up after his authentication is complete. His "admin" role has the "is_admin" scope attached.
• Bob asks for an access token with all the scopes collected from his various roles
• Bob is automatically given those scopes for his access token

Is it up to my calling app to enforce only sending asking for the scope Bobs needs? Or is there something I am missing with regards to scopes?

Can someone please enlighten me with some simple examples?

Downtrodden

For people stumbling here because they need to know what scopes there are: developers.google.com/identity/protocols/oauth2/scopes – Hen

According to your post, role is Admin and scope is is_admin. You use Admin role for the scope as well. They are 2 different terms. I think scope should be more like write:entity or read:entity. – Pollinate

Answer 1

In OAuth2, there are the following roles:

• Resource owner - usually some person
• Auth provider - the OAuth2 server
• Resource server - an API that requires an access token and validates its scopes
• Client application - application requesting an access token with some scopes.

To understand OAuth2, it's necessary to think about it as a protocol for access rights delegation from a Resource owner to a Client application. So the main use case is: the Client application wants to access the Resource server. In order to do that, the Client application needs an access token issued by the Auth provider and authorized by the Resource owner (which gets authenticated by the Auth provider).

In your description, the Client application is missing. Let's assume it's a frontend application for your API. It needs an access token with scopes admin-user-scope or regular-user-scope. So it redirect a user (Resource owner) to the Auth provider, requesting both scopes.

The Auth provider authenticates the user and asks him/her for a consent on granting some of the requested scopes to the Client application. The Auth provider may remove some scopes - for example the admin-user-scope for non-admins. The Auth provider may give the user a possibility to remove some scopes too.

The Client application receives an access token (or a grant) with scopes in a redirect URI. If the granted scopes differ from the requested scopes, the Auth provider sends a list of granted scopes (the scope URL parameter) along with the access token, so the Client application knows what actions it can perform with the access token.

Then the client application may access the Resource server and the Resource server makes sure that the provided access token contains required scopes. The Resource server uses the OAuth2 introspection endpoint to validate the token and to get a list of its scopes.

Cyclothymia

I think I understand. The user has access to a,b,c,d but he might only ask for access to a,b,c when authenticating (e.g. via an auth code request). The Auth provider would respond only with what the user asks for, and never his entire set. The Auth provider can also reduce what it returns if it discovers the user has no authority for an asked-for scope (in my case, not in a specific role). Once authenticated, the user gets an access code only with the asked-for (possibly reduced) scopes attached. Is this a correct summary? – Downtrodden

Let's say the the granted scopes that are returned from the Auth Provider back to the Client App in the token, are somehow changed manually (MITM or some other way), and a scope is added like the "admin-user-scope". What would happen when the client app tries to use this token to get a resource from the Resource Server, which is protected for admins only? – Giorgio

@Giorgio Unless the MITM operator knows the private key used to generate the access token, they cannot temper with the access token without it becoming invalid—in other words, not only would the admin-user-scope not be accepted, the token itself would be rejected, hopefully resulting in a 401-Unauthorised exception. – Headwater

Is it common to have the 'auth provider' and the 'resource server' running on the same server? From my understanding the 'auth providers' job is to do the privilege-to-scope mapping (I'm naming it 'privilege' here to not confuse it with the OAuth 'role' definition you explained above, it could be membership in a LDAP group, for example) and thus it needs to have some understanding of what scopes exist. Thus, there's a dependency between those two OAuth roles 'auth provider' and 'resource server' so it would make sense to have a shared logic that is deployed / updated together. – Preachment

The mapping between scopes, roles and users is specific to intended usage of an auth provider and the standard doesn't mention describe it. For example, a role "Google Drive user" may enable scopes for reading and writing to the user's Google Drive. A resource server should understand the same set of scopes and roles as the auth provider it uses. So yes, if the scopes or roles change on either side, the other module will need an update too. – Psychogenic

Answer 2

While Ján Halaša's answer was a nice general explanation of OAuth, I don't think it adequately answered the question. The truth is, OAuth scopes should only be used for a user to delegate access to a client. Scopes should not determine what the user is allowed to do.

Having the resource server blindly trust a scope like "is_admin" is a security problem because, like you said, a malicious user can modify the client to request that scope for them.

It is technically possible for the authorization server to filter the scopes based on the user's role (which would solve that problem), but this usually isn't the case.

Related blog post (not mine): https://auth0.com/blog/on-the-nature-of-oauth2-scopes/

Tamer