I have been reading a lot the past few days about OAuth2, I understand the use of scopes to delegate access in the name of a user. My question is, if I have users sub: A and sub: B with a /resource/X, only user A should have access to /resource/X, should I use a scope "read:X" in combination with sub field to determine if the user can access that resource, or is it enough to only have the sub field with value A?
I am learning how to use Auth0 API, and there is a question posted from 2018 with no answers that explains exactly my doubts:
Comment about the sub field from tokens
In simple APIs it is common to use scopes alone to determine access to resources. Read and write scopes are common, as are scopes to represent other high level privileges. There are limits to how well this scales though.
In more complex business apps you usually need to identify the user from the token (via the sub claim) so that you can then serve resources associated to that particular user's history.
This typically involves mapping the sub claim from access tokens to your API's own data, as in my below posts:
User Data Management
API Authorization
Related
It seemed like client_credentials flow was appropriate for a machine-to-machine communication between our system and third parties for importing and exporting data.
But if I have two third parties p and q say and users on our system u and v say, then I need to know which of p and q can acces the data of which of u and v.
For example: user u grants access to p (but not to q) and v to q (but not p).
I can give different client secrets to p and q but when they present thir secret to IdentityServer in order to obtain a token I need to know which of p and q it is and add a claim to the token that my controllers can use to determine which of u ad v's data is visible.
I can implement ICustomTokenRequestValidator to intercept the secret and look it up in the configuration context, but the Id column is not in the model class, so I could abuse the Description column as a foreign key to my table of third parties -- seems hacky.
Is there a standard/recommended way to resolve this situation -- that different machines have different data visible to them (different claims in their token)?
If you use client_credentials flow then there is no user-interaction involved.
Each third party should have it's own client with corresponding client credentials. Do not share the same credentials over boundaries, i.e. between different third parties. By having separate clients for separate parties, you minimize the security risk and minimize the impact when having to revoke or change the credentials.
With that said, in the Client Credentials flow the Authorization Server returns a token if the request is valid - it does not know from the request if the user authorized the request or not because the user is not involved. But it authenticates the client. So, if you want to differentiate between several third parties, give them individual clients. If you can't add a claim to the token.
Scopes and claims are the tools to define what a client requests to do. Some authorization can be done in the Authorization Server. For example, an Authorization Server typically only allows a client to request certain scopes.
Use then claims (the data in the token) for a fine grained authorization in the API. It depends on your use case. If the API is supposed to return a filtered result, i.e. only return data from users that are ok with it, then the API needs to be able to look this information up somewhere, as #gary-archer states. Use an applicable claim from the token that enables the API to identify the client or third party. It can then use this data for the lookup. For example, use the client_id claim but it really depends on the Authorization Server which claims it adds to the token.
If the client already knows beforehand which user's data it is going to access, it could add the user-id when requesting the token and - once again - depending on the capabilities of the Authorization Server - get a token with a user_id in the claim set. Then the API can use the client_id and user_id for a lookup.
How you collect the users' consent is out of scope and happens out of bound. It's part of your business logic.
At the end it is all about designing the token. Here is another article on Centralizing Identity Data
The standard option here is to include custom claims from your business data at the time of token issuance. Rather than machine to machine I would describe your scenario as B2B.
EXAMPLE USE CASE
Consider an API called by business partners who act as suppliers of inventory to your system. In this case a useful access token might look like this, and is what I would aim for:
{
client_id: 1hvf367g
supplier_id: 42
exp: ...
}
API requests for stock items could then authorize based on the supplier_id value in the access token. Eg by running a SQL query on the business data, filtering on the supplier ID. All of this keeps your API code simple.
DATA MAPPING
For this to work you need to design onboarding. Eg a button click to create a supplier in your system might create the OAuth client using Identity Server, then save the client_id to a suppliers table in the business data.
Not all identity systems support issuing custom claims in the above manner. An alternative design is to just include the client_id in the access token, and look up the supplier ID from business data when your API receives an access token. This tends to add complexity to API code though.
SUMMARY
I think your question is really about designing business permissions, and OAuth alone cannot solve it. If I'm right then the Claims Best Practices article may be useful.
I'm trying to wrap my head around scopes for this scenario.
I have a SPA client and an API. The client only communicates with this API and the API has no other clients communicating with it.
The application has two access levels, say a user and an admin (the SPA may block some routes for the user and the API may block some endpoints).
The roles are administered with AD-groups and mapped to the roles claim.
So what role does scopes play in this scenario? I do all authorization based on the roles claim. But I still need to specify a scope, so I have a API://[clientid]/all scope. Could someone help me make sense of all this?
Scopes are fixed at design time. They are high level privileges that indicate an area of data and what you can do with that data. These are often used as sanity checks, eg to prevent tokens for a valid user but wrong app being used to call an API.
orders_read
Claims are dynamic values looked up at runtime, and tend to have different values for different users. Pretty much all real world authorization is based on claims:
role = supervisor
company_id = 407
So in your case just define a scope or two, but keep them high level and easy to manage. Your claims based authorization (using roles) seems fine.
FURTHER INFO
At Curity we have a couple of good docs that explain the science of designing authorization based on OAuth standards:
Scope Best Practices
Claims Best Practices
I'm trying to better understand how to make use of OIDC/OAuth in securing a restful API, but I keep getting lost in terminology. Also when I research this question most of the answers are for Single Page Apps, so for purposes of this question assume the API will not be used for an SPA.
Assumptions:
Customers will access a restful API to interact with <Service>.
It is expected that customers will create automated scripts, or custom application in their own system to call the API.
Once setup it is not expected that there will be a real person who can provide credentials every time the API is called.
<Service> uses a 3rd party IDP to store and manage users.
3rd part IDP implements OIDC/Oauth and that is how it should be integrated into <Service>
Questions:
What OIDC/OAuth flow should be used in this situation?
What credentials should be provided to the customer? client-id/client-secret or something else?
What tokens can/should be used to communicate information about the "user"? E.g. Who they are/what they can do.
How should those tokens be validated?
Can you point me to any good diagrams/resources that explain this specific use case?
Am I missing anything important in the workflow?
It sounds like these are the requirements, if I am not misunderstanding you. The solution contains not just your own code and is more of a data modelling question than an OAuth one.
R1: Your company provides an API to business partners
R2. Business partners call it from their own applications, which they can develop however they see fit
R3. User authentication will be managed by each business partner, resulting in a unique ID per user
R4. You need to map these user IDs to users + resources in your own system
OAUTH
Partner applications should use the client credentials flow to get an access token to call the API. Each business partner would use a different credential for their set of users.
Using your own IDP to store users does not seem to make sense, since you do not seem to have an authentication relationship with the actual end users.
Access tokens issued to business partners would not be user specific by default. It is possible that a custom claim to identify the user could be included in access tokens - this would have to be developed in a custom manner such as via a custom header, since it is not part of the client credentials flow.
Access tokens would be verified in a standard OAuth manner to identify the partner - and possibly the end user.
DATA
Model users in your own system to have these fields, then store resources (such as orders) mapped against the User ID:
User ID (your generated value)
Partner ID (company the user is from)
External User ID (an ID that is easy for partners to supply)
Typically each partner would also have an entry in one of your database tables that includes a Client ID, name etc.
If you can't include a custom User ID claim in access tokens, partners have to tell you what user they are operating on when they call the API, supplying the external user ID:
POST /users/2569/orders
Your API authorization needs to ensure that calls from Partner A cannot access any resources from Partner B. In the above data you have all the fields you need to enable this.
SUMMARY
So it feels like you need to define the interface for your own APIs, based on how they will be called from the back end of partner apps. Hopefully the above hints help with this.
I'm aware of how OAuth2 and OIDC can use custom scopes and token introspection to secure an URL like this:
/users/me/documents
I can give this URL the documents:view scope and when receiving the token from the authenticated user, I can ask the authorization server if this user has the correct permissions. Then I can use the preferred_username claim or similar to see who /me actually is.
But what if I have a resource which is accessible by multiple users? Let's say a user has documents but they can be viewed by his direct manager. To retrieve the employee's documents as a manager, I'd need to have an url like this:
/users/${userId}/documents
How could I enforce it in a way that only the resource owner and direct manager can view this resource? I don't want everyone to access everyone's documents by knowing the userId. I could grant access as a whole to all users with the manager role, but that's not specific enough.
I'm aware there's the UMA extension where users can grant access to resources on his behalf to other users, but it's not the user who grants permission. It's the system who states in this case that managers can access their employees documents.
Would it make sense to write a custom policy which extracts the ${userId} and performs the check? Or should this not be done by the authorization server at all and be done by the resource server instead? Perhaps a different approach to reach the same goal?
Finer grained authorization like this is done with claims rather than scopes. There may be business rules around which docs a user can see, eg:
A user can access their own docs
An admin has view access to all docs
A manager can view docs for people they manage
In an access token this might be represented by these claims:
userId
role
Claims are often domain specific like this and the preferred option is to add them to tokens during token issuance. At Curity we have some good resources on this topic:
Claims Best Practices
CLAIMS AND AUTHORIZATION
The Authorization Server issues access tokens and then APIs (resource servers) verify the access token and use the token data to apply authorization rules (which are often domain specific) on every single request.
Claims are often used when dynamic behaviour is needed - they are runtime values that derive from the user identity, whereas scopes are fixed design time values. In your example an API might also need to vary SQL to retrieve documents based on the user identity.
There are more complex variations on this theme, such as an API calling a system such as Open Policy Agent, so that documents returned are determined by rules configured by a security administrator. That policy would still involve using claims from the access token though.
EXAMPLE CODE
If it helps, here is some sample code of mine that show the type of approach when enforcing domain specific authorization rules. Typically you need to filter collections and check access to individual items.
I have an application which provides authenticated users with views into data about various objects in a database. There's another application in our ecosystem that provides different views into some of the same objects, using its own permission model. We trust that other application's permission model, and would like to allow them to issue access tokens to users who haven't been authenticated through our application's usual method, so those users can only view specific objects that the other application has verified they have access to.
Rather than coming up with our own spec for the communication between these two applications, I was wondering if there's already a standard approach available via something like OpenID Connect. OIDC seems to handle most of the gnarly details we'd have to consider in a case like this, but the one aspect where it doesn't seem to fit is that its access tokens seem to be general-purpose, rather than calling out a specific object that the user has access to. It says "Here's a user who can access your application", but not "Here's a user who can access Item 123".
Is there a standard for using an access token to grant access to a specific item, preferably using OAuth 2 and/or OpenID Connect? Am I correct in assuming that using an item's ID as a scope on the access token would be an inappropriate use of OAuth scopes?
I've always found the best design for most real world apps to be like this:
OAuth 2.0 based tech identifies the user
You then lookup user details at an application level to enforce authorization
OAuth 2.0 scopes etc cannot handle things like this:
You don't have access to account 123
You don't have access to region US
So I tend to look them up from the user id in the token after login. This tends also to be much easier to extend, if for example the items and user rights in the external app grows over time.
For more concrete info see my write up on API Claims Caching.
Also here is an example of the coded algorithm in a Rest API, resulting in a claims object that can be injected into logic classes.
In your case the custom claims provider would be the external app, and you could query claims from it, for data that does not really fit well into OAuth tokens.
Just my thoughts - not sure if it will fully work for you - but I've found this to be quite an adaptable solution, which often puts responsibilities in the right places.