Child pages
  • UMA Implementer's Guide

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

This document is a non-normative set of auxiliary material produced by the User-Managed Access Work Group. It provides advice to, and discussions relevant to, developers and deployers of UMA-enabled software systems, services, and applications.

Status

This document is currently under active developmentwill have material added to it as warranted. It focuses primarily on UMA V2.0, which is currently at the WG draft stage; every attempt will be made to mark content that applies to specific versions.

...

Eve Maler, Maciej Machulak

...

Intellectual Property Notice

The User-Managed Access Work Group operates under Kantara IPR Policy - Option Patent & Copyright: Reciprocal Royalty Free with Opt-Out to Reasonable And Non - discriminatory (RAND) (HTML version)Copyright:  and the publication of this document is governed by the policies outlined in this option.


The content of this document is copyright of Kantara Initiative. © 2017 2018 Kantara Initiative

...

Table of Contents 

...

This document uses terms and abbreviations defined in the UMA V2.0 (currently in draft) Core and OAuth Resource Registration specifications, and presumes understanding of UMA concepts.specifications, and presumes understanding of UMA concepts.

...

Anchor
front-channel-security
front-channel-security
Security Considerations Regarding Interactive Claims Gathering Flows

When the requesting party is redirected to the authorization server for interactive claims gathering, a man in the middle/man in the browser can manipulate messages, impacting the claims_redirect_uri parameter (in what is called the Mix-Up attack in the case of a OAuth security analysis) and potentially more elements of the front-channel messages involved. The claims_redirect_uri parameter is similar to the OAuth redirect_uri parameter and some attacks may be able to be mitigated through approaches described in the OAuth Security Topics Internet-Draft (at revision 04 at the time of writing), Section 4.4. If the syntactic mitigation approach described is taken, the authorization server's redirection response back to the client would need to be extended with additional parameters as described in the OAuth 2.0 Mix-Up Mitigation Internet-Draft (at revision 01 at the time of writing). If the client-side mitigation approach described is taken, the client would have to perform a number of coordinating and tracking actions in addition to choosing authorization server-specific URLs. The client could additionally use the state parameter and choose a specific type of value that carries enough application state to enable it to match the value with its callback.

...

Anchor
why-the-pat
why-the-pat
Motivations for the Design of the PAT

Some developers and deployers studying UMA 2.0 have asked questions about the protection API access token, known as the PAT. What is it? Why does it exist? When does it need to be used?

The PAT is simply an OAuth access token with a particular scope, standardized by UMA with the name uma_protection. It represents the resource owner's (Alice’s) authorization for the resource server, acting as an OAuth client, to use the protection API presented by the authorization server.

This API is defined by the optional UMA Federated Authorization specification that is referenced by the UMA Grant specification; these sequence diagrams may be of interest. This API is what allows the resource server, on resource owner Alice’s behalf, to outsource resource protection to the authorization server in a formally defined fashion. In the FedAuthz specification, OAuth and the PAT are being used just as they would be for any other OAuth-protected API -- Facebook, Feedly, whatever. (This writeup assumes FedAuthz is in use. Otherwise there is no point talking about the PAT.)

Keep in mind that Alice could need resource protection from more than one resource server at a single authorization server, or could be using more than one authorization server -- or both. OAuth is a classic choice for ensuring both security and Alice’s authorization for these trusted app-to-service connections. It’s just that, in this case, the “app” is a resource server and the “service” is an authorization server.

To achieve resource protection, the protection API offers three endpoints. Alice’s permission is required for the resource server to make calls to any of these; hence the resource server must present a valid PAT for any of these calls to be allowed:

  • Resource registration, so that the authorization server knows what resources to protect and how to let Alice give it the policy conditions under which to grant access (various CRUD operations for managing registration and deregistration).

  • Permission requests on behalf of the client app used by a requesting party (such as Bob), so that the authorization server can correlate the originally attempted resource request with the client’s later request for an access token (the resource server gets back a permission ticket that it hands right over to the client).

  • Access token introspection, so when Bob’s client finally makes a resource request toting an RPT (requesting party token), the resource server can look up at the authorization server what resource and scope access was actually granted and enforce that grant.

The protection API is an “offline” type of API, meaning the resource server generally needs to make API calls to the authorization server when Alice does not currently have a session. In practice, this typically requires a way for the resource server to store a longer-lived refresh token persistently so that it can refresh a shorter-lived PAT on an ongoing basis. (For some thoughts on resource server error handling when the PAT is invalid, see this section.)

Here are "offline" use cases for each of the endpoints. None of these situations require Alice's current availability, vs. some other condition for the resource server to make the API call to the protection API.

  • Resource registration endpoint: The resource server needs to update all of Alice's resources when its API is versioned. For example, the API couldn't tag photos before, but now it's able to, and this corresponds to a new available scope.

  • Permission endpoint: The resource server needs to request one or more permissions on Bob's client's behalf at (tokenless) resource request time.

  • Token introspection: The resource server needs to introspect the RPT that Bob's client brings it at (token-carrying) resource request time.

The question has been posed: Why doesn’t the design of UMA2 call for the resource server (as an OAuth client) to switch to using its own client credentials, rather than the PAT, for the permission and token introspection endpoints of the protection API? It’s possible for the authorization server to derive the resource server’s intended resource owner from a resource ID passed in the request if client credentials were used. (see UMA GitHub issue #352)

The Work Group chose not to switch to a different construct for the following reasons:

  • It would be inefficient. What if Alice the resource owner had revoked her PAT before Bob's client made a tokenless resource request (requiring the resource server to use the permission endpoint) or an RPT-bearing resource request (requiring the resource server to use the token introspection endpoint), say, because Alice doesn't “like” the resource server anymore? Now the authorization server would have to keep track of whenever she did this and then prevent any client credentials flows from happening. It wouldn't get this tracking "for free" from an invalid PAT.

  • It would disrupt the higher-order trust relationship. Along with this loss of tracking comes the loss of the resource owner’s trust relationship with and delegation to the authorization server (properly stated, to the Authorization Server Operator) of its authorization function. The work by the UMA Legal subgroup to develop an UMA legal framework/business model includes the mapping of legal devices, such as contracts (including trust frameworks) and licenses, to the various UMA technical artifacts and messages, including the PAT. So this mapping capability might be lost if the PAT gets overtaken by a different mechanism.

  • It would make the design inelegant. It’s weird for the authorization server to have to derive resource owner context this way. Both the permission request message and the token introspection response can contain multiple resource IDs. The spec then might need a new error condition to check whether they all match the same resource owner.

Thanks to UMAnitarians James Philpotts, Domenico Catalano, and Andi Hindle for contributing to this writeup.

...

Anchor
perm-request-patterns
perm-request-patterns
Considerations Regarding Resource Server Permission Requests

...

Since there is a many-to-one relationship between API calls and the scopes they map to, the RS resource server can distinguish the desired scope from the client's access attempt and request it that scope if it sees fit.

...

This is a good example of where the client would want to exercise its option to pre-register for and then dynamically request admin scope if the requesting party’s immediate need were only for the two actions also available within user scope. It’s also a good example of where the RS resource server would potentially want to have a strategy of "parsimonious" rather than "generous" permission requests (either requesting user scope rather than admin scope and not requesting additional resource identifiers, or even requesting no scopes at all and let the client take on the burden of expressing its needs).

...

A GET call doesn’t distinguish between the two possible functions. The RS resource server can request zero scopes, which may be the wisest choice for (say) a paid service or just in the name of least privilege and minimal disclosure.

...

Assume the same example as above. Because the ROresource owner-RS resource server interface is private (beyond the issuance of the PAT), and the details of which resources are centrally protected and how are allowed to be variable, the resource server could make an option available to the resource owner to keep the the download scope "private" – that is, never registered for any of the ROresource owner's resources (meaning, never advertised by the RS resource server as part of the universe of possible scopes on this resource).

In this scenario, the RS resource server should first look at the ROresource owner-designated scopes before requesting permissions.

This would mean that the AS authorization server would fail the client with an invalid_scope error at the token endpoint if the client requested it (and presumably pre-registered for it). The RSresource server, too, would receive an invalid_scope error if it tried to request a permission it hadn't first registered as part of a resource.

...

Anchor
pat-invalid
pat-invalid
Resource Server Error Handling When the PAT Is Invalid

If the RS resource server can't get a permission ticket, it issues a 403 Forbidden HTTP error and Warning: 199 - "UMA Authorization Server Unreachable". One reason for being unable to get a permission ticket is that the resource owner's PAT has expired or is otherwise invalid, and it has no way of refreshing the PAT. In this case, the RS resource server could take this opportunity to initiate some refreshing action such as send a notification to the resource owner and ask them to re-consent to the pairing with the AS authorization server as required.

...

Anchor
RO-RqP-org
RO-RqP-org
Considerations Regarding Resource Owners and Requesting Parties

...

  • The resource server treats a "wildcarded" URI as being a single complex resource for authorization server purposes; this translates to individual registration.
  • To enable a human resource owner to share out resources one at a time using a Share button, the resource server would probably need individual registration at stage 2. But to enable "relationship-driven sharing" of (say) multiple smart device resources at once, the resource server might want to register as many resources as are available in a household. For industrial IoT use cases, the number of resources to register could climb
  • In discussions about the FHIR API for healthcare, resource registrations might "pair" with patterns of permission requests that anticipate a need for the requesting side to gain access to certain clusters of resources, say, three related resources if ever a client attempts to access one of them. (E.g., each of the use cases in the GDoc imagining RS resource server permission requests for various APIs gives us a way of imagining finite numbers.)

...

Regarding the resource registration API, it is common practice when using NoSQL databases to replicate entity tag (ETag HTTP header) revision information in the body of the response message as well, in a _rev property. The API does not mandate this property (though an early pre-V1.0 draft did include this property).

...

Anchor
authz-responses
authz-responses
Understanding Authorization Server Response Options From the Token Endpoint

When the client requests an RPT from the token endpoint, the authorization server is able to issue the token as requested, deny the request definitively, and so on. You can think of the responses as mapping to well-understood access control actions (for example, in XACML) as follows. (These are non-normative descriptions; see Grant Sec 3.3.5 and 3.3.6 for normative wording.)

Response (e.g., error code)HTTP status codeConditionsMeaningPermission ticket issued?
Issue an RPT200 OKRequesting side has met policy conditionsPermitNo
invalid_grant400 Bad RequestPermission ticket in request not found at authorization server, or was expired, or other RFC 6749 conditions(syntactic error)No
invalid_scope400 Bad RequestAt least one requested scope didn't match any scope on any permissions on permission ticket in request, or at least one requested scope didn't match any scope the client was pre-registered for.(syntactic error)No
need_info403 ForbiddenThe authorization server needs additional information in order for a request to succeed.IndeterminateYes
request_denied403 ForbiddenThe client is not authorized.DenyNo
request_submitted403 ForbiddenThe authorization server requires intervention by the resource owner to determine whether the client is authorized.NotApplicableYes

If the authorization server does not issue a permission ticket with an error, the client must start anew in a fresh authorization process. If the authorization server does issue a permission ticket, the client has a choice whether to continue and use it, or start anew.


...

Anchor
ignored
ignored
Handling Optional and Extension Properties (V1.0.1)

(This section is specific to UMA V1.0.1.)

Any entity receiving or retrieving a JSON data structure is supposed to ignore extension properties it is unable to understand, and manage property namespaces on its own to avoid collisions. Properties defined in the specifications that are optional to supply, however, are nonetheless required to be handled by the receiving entity.

...

Following are specific comments on optional properties defined in the specifications.

Property (V1.0.1 references)Recommendations
Core Sec 1.4: Authorization server configuration data
claim_token_profiles_supportedProvided as a hint; no significant impact if ignored by any party.  Should be logged if ignored to help with troubleshooting.
uma_profiles_supportedProvided as a hint; no significant impact if ignored by any party.  Should be logged if ignored to help with troubleshooting.
dynamic_client_endpointAuthorization Server: implementations should take care to provide this parameter if support for the dynamic client registration feature is provided.  Failing to provide it (or providing it erroneously) can induce incorrect handling by clients or resource servers.
Clients, Resource Servers: if the parameter is not provided, clients and resources servers must assume that dynamic client registration is not possible, and should therefore not attempt such registration.
requesting_party_claims_endpointAuthorization Server: to avoid confusion, should provide this parameter if end-user RP claims gathering capability exists.
Core Sec 3.4.2: RPT "Bearer" profile
exp

Authorization Server: since not providing this property implicitly means that the permission does not expire, the AS should take care only to ignore the parameter if a non-expiring permission is desired.  It may be sensible to consider always providing a value, even if far in the future, to avoid inadvertently granting permanent permissions.
Resource Server: if the parameter is provided, it must be adhered to.  If it is not, it may be sensible to consider applying an expiry date anyway, to avoid inadvertently allowing permanent access to a given resources.  It may also be sensible to log if this parameter is not provided (and, hence, long or permanent permission is given) for audit purposes.

iatAuthorization Server: Not providing the issued-at time introduces the potential for confusion at the RS about whether the token is valid or not.
Resource Server: RS should consider whether the issued-at time is reasonable (allowing for potential clock skew).  Ignoring the parameter, if provided, could introduce a risk of incorrectly processing a 'bad' token.
nbfAuthorization Server: failure to provide this parameter might result in access to a resource being granted earlier than intended.  The AS should consider providing a value to avoid any potential confusion.
Resource Server: if the parameter is provided, it must be adhered to. If a value is not provided, the RS should assume 'now' as the nbf, and log accordingly for audit purposes.
Core Sec 3.5.4.2: Error Details About Claims
nameAuthorization Server: not providing a value might cause processing confusion later.  The AS should consider providing this.
Client: the client should consider using this value when returning any eventual results to the AS, in order to avoid confusion.
friendly_nameAuthorization Server: no significant impact; although not providing a value means that the client will have to make assumptions about how to present the claim requirement to the user.
Client: no significant impact; although the client should consider using this value to help provide improved communication to the user.
claim_typeAuthorization Server: no significant impact.
Client: no significant impact.
claim_token_formatAuthorization Server: failing to provide this parameter might result in a token format being return that the AS cannot then process.  AS should consider providing this parameter to avoid confusion at the Client.
Client: if provided, client should take account of the acceptable token formats when it returns a token to the AS. Ignoring this parameter might result in a token being returned in a format which the AS cannot process.
issuerAuthorization Server: no significant impact.
Client: ignoring this parameter, if provided, might result in a token being returned from an issuing authority which is not acceptable to the AS (and so lead to a poor user experience).
Core Sec 3.6.3: Client Redirects Requesting Party to Authorization Server for Claims-Gathering
claims_redirect_uriAuthorization Server: it is recommended to include this parameter to avoid confusion or unexpected results at the AS.
Client: ignoring this parameter is not recommended.
stateAs noted in the spec, it is highly recommended that this parameter be included in order to avoid cross-site request forgery.
ticket (response)There are no circumstances in which this parameter can reasonably be ignored.
state (response)There are no circumstances in which this parameter can reasonably be ignored.
Core Sec 4.2: UMA error responses
error_descriptionNo significant impact.
error_uriNo significant impact.
RSR Sec 2.1: Scope descriptions
icon_uriResource Server: no significant impact
Authorization Server: should log that it is ignoring for troubleshooting purposes.
RSR Sec 2.2: Resource set descriptions
uriResource Server: in many deployments, the network location for the resource set being registered will be provided by (or inferable from) the 'scope' parameter (which is required).  If not, however, the resource server will most likely use the 'uri' parameter to provide the network location.
Authorization Server: if the parameter is ignored, this should be logged for troubleshooting.  It is unlikely to be ignored in most common scenarios.
typeResource Server: this can be a helpful hint to provide to the AS.
Authorization Server: should log that it is ignoring for troubleshooting purposes.
icon_uriResource Server: no significant impact.
Authorization Server: should log that it is ignoring for troubleshooting purposes.
RSR Sec 3: Error messages
error_descriptionResource Server: no significant impact.
Authorization Server: should log that it is ignoring for troubleshooting purposes.
error_uriResource Server: no significant impact.
Authorization Server: should log that it is ignoring for troubleshooting purposes.


...

Anchor
change-history
change-history
Change History

Change History