Child pages
  • UMA Implementer's Guide

Versions Compared

Key

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

...

See the UMA Legal page for information on ongoing work to connect the technical UMA entities to contracts and trust frameworks that define "access federations" (in contrast to identity federations).

...

Anchor

...

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
RO-offline
RO-offline
Ensuring Asynchronous Resource Server Access to an Authorization Server

The protection API generally requires "offline" access, that is, when the resource owner is not available. Thus, the authorization server needs to manage the lifetime of the protection API access token (PAT) for this outcome.

...

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.

This section recommends how to deal with optional and extension properties. It is helpful for handling behavior to be consistent because UMA flows involve loosely coupled entities. Typically, an extension property would appear if one of the entities has implemented some agreed extension to the specification that might not apply to this particular transaction.

In the event that an unrecognized property is received, it's a good idea to log the property and its value, taking normal precautions regarding safe methods of logging potentially dangerous properties in order to avoid injection attacks or similar. This will help with any troubleshooting or auditing that may be required, while allowing normal processing to continue. Finally, it's also recommended to log any property that is malformed (for example, where a Boolean value is expected, but a text value is received), taking the same precautions regarding safe methods of logging.

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

...

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.

...

Anchor

...

redirect

...

 

Anchor

...

redirectredirect
Redirecting the Requesting Party to the Client After Claims Gathering 

...

Rather than the resource description document pointing to a series of scope URIs that must be dereferenced (as was the case in UMA V1.0.x), the resource server in UMA V2.0 can instead make use of the OpenID Connect discovery document and its scopes_supported metadata item, which, when filled with (the same) scope description document URIs, allows for development-time discovery of the necessary scope information.

...

Anchor
extension-profiles
extension-profiles
Combining UMA Entities

...

and Using Alternate Networking Protocols

In some circumstances, it may be desirable to couple UMA software entity roles tightly. For example, an authorization server application might also need to act as a client application in order to retrieve protected resources so that it can present to resource owners a dashboard-like user interface that accurately guides the setting of policy; it might need to access itself-as-authorization server for that purpose. For another example, the same organization might operate both an authorization server and a resource server that communicate only with each other behind a firewall, and it might seek more efficient communication methods between them.

...

In such cases, parts of UMA's flows may require profiling or extension because it is only defined over HTTP. Where appropriate, use the uma_profiles_supported configuration property to flag usage of a documented profile or extension.

...

Anchor
ETag
ETag
Managing Resource Registration Revisions 

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
ignored
ignored
Handling Optional and Extension Properties

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

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.

This section recommends how to deal with optional and extension properties. It is helpful for handling behavior to be consistent because UMA flows involve loosely coupled entities. Typically, an extension property would appear if one of the entities has implemented some agreed extension to the specification that might not apply to this particular transaction.

In the event that an unrecognized property is received, it's a good idea to log the property and its value, taking normal precautions regarding safe methods of logging potentially dangerous properties in order to avoid injection attacks or similar. This will help with any troubleshooting or auditing that may be required, while allowing normal processing to continue. Finally, it's also recommended to log any property that is malformed (for example, where a Boolean value is expected, but a text value is received), taking the same precautions regarding safe methods of logging.

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

Property (V1.0 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.3.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.4.1.2: Claims-gathering flows
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.4.1.2.2: Client redirects requesting party to authorization server
redirect_uriAuthorization 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.
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.