Demystifying UMA2.0

This June at #Identiverse in Boston I had quite an epiphany during Eve and Mike’s session. I finally realized that User-Managed Access 2.0 protocol (aka UMA2.0) is not that complicated to understand and VERY similar to some OAuth2 flow we all know. Let me try and convince you.

UMA2.0 : an extension of OAuth2

Before taking the shovel and digging deeper, remember that UMA2.0 was actually designed as a new grant type of OAuth2 and not as a new protocol. If you already know OAuth 2.0, then you can understand UMA2 in less than 10 minutes. I promise.

Here’s the UMA2.0 grant type in one typical flow:

1. The client initiates a request against the resource without a token
2. The resource server requests a permission ticket from AS by sending it the requested resource details (requested scopes and resource registered id)
3. The resource server sends back an error response including the AS location and a permission ticket
4. The client optionally requests a Requesting Party Token (RPT, see it as UMA’s custom form of an access token) directly against the authorization server’s token endpoint using the permission ticket.
5. The client redirects the user agent to the authorization endpoint on the Authorization Server to request a token and the authorization server interacts with the requesting party to gather whatever is needed to take an authorization decision (authentication, attribute gathering, etc.) (wait, this sounds familiar)
6. The authorization server redirects the user-agent to the client redirection URI including an updated permission ticket (I know this…)
7. The client requests a requesting party token against the authorization server’s token endpoint using the updated permission ticket (I definitely remember now…)
8. The authorization servers responds with the RPT and a PCT (Persisted Claims Token, details follow) (so one ephemeral code against two tokens, mmh, been there…)
9. The client requests the resource server with the RPT (UMA2 actually recommends to conform to plain OAuth2 practice like RFC 6750 Bearer Token usage or PoP)
10. The resource server optinnaly requests the Authorization server to validate the RPT (using the OAuth2 introspection endpoint) (following RFC 7662 Token Introspection extended by UMA2) or can do that locally depending on the token’s format.

Do you see the authorization code flow? Let me highlight it to you:

Yes, steps 5 to 8 are VERY much like the OAuth2 authorization code grant.

If you agree to the following approximations, there are really no other major differences:

• Access Token (AT) becomes Requesting Party Token (RPT) (one with customized token introspection results)
• Refresh Token (RT) has now a companion Persisted Claims Token (PCT) (which is really a specialization of the refresh token class)
• Authorization code becomes (a kind of mutable) Permission ticket

So yes it is not the same. Yes there are some steps before the highlighted part and it is a tiny bit longer.

UMA2.0 : much more than OAuth2

Now User-Managed Access has been designed for a reason. And that reason is not to just rename a few OAuth2 artifacts. There are some differences that enable UMA2.0 to work beyond OAuth2 standard capabilities.

Let’s have a closer look at the differences:

• Step 1-3 : The client can get information in a standardized manner about the way to obtain a token (specifically the Authorization Server location) by contacting the resource with a token-less request while if following OAuth2 RFC 6750, no information should be given back by the resource (insufficient scope might be returned only if a token was provided)
• Step 4 : The client can try to get a token without starting a dance involving the user-agent. Maybe there’s no user authorization or consent to gather or maybe a previously delivered token (the PCT) was sufficient to get a new token. If this call is successful, you go straight to step 9 and this can actually be compared to the OAuth2 assertion flow (RFC 7523 JSON Web Token Profile)
• Step 5 : Only if required the end user is bothered to interact with the Authorization Server through the user-agent, to authenticate, gather claims about himself, consent, etc. while in OAuth2, the user-agent is solicited even if no user interaction is required and that can damage user experience
• Step 8 : an additional PCT can be handed over to the client in order to ease subsequent RPT deliveries for the same requesting party but for a different target resource (whereas a refresh token would only refresh an RPT for a given requesting party and target resource)
• Before step 1, a resource can register endpoints against an authorization server in a standard manner following Federated Authorization for UMA2.0 (but that could be covered in another article)

What the UMA2 standard achieves (and is actually designed for) is the separation of the requesting party and the resource owner (where OAuth2 considers them to be only one person). And this differentiation allows us to address more use-cases than OAuth2 allows by default:

• A document owner can share it with other people; for example, a patient can share (different) medical data with his/her spouse, relatives or doctor
• An application owner can design rules allowing certain enterprise employees (or business partners) to access an application/API
• A resource owner can aggregate the management of resource sharing under a single authorization server, even if the resources live in many domains
• An application can get additional permissions and upgrade the access token scopes without involving the user-agent in an OAuth2 dance if the authorization policies allows it
• All the above permissions can be granted asynchronously (whereas OAuth2 user consent is only synchronous within the token request flow)

Special thanks to Eve Maler for her insight while writing this article.