UMA1 Interop Features and Feature Tests

Main UMA1 Interop Testing page | Participants and Solutions | Results | uma-dev list

The features and tests relate exclusively to the core protocol spec, any other normatively referenced specs, and software components that serve as protocol endpoints. None relate to the Binding Obligations specification because it describes expected behaviors of operators and users of these endpoints, which makes them untestable for the purposes of an interop.

The type values for a test are minimally one of:

• "req" (required)
• "opt" (optional)

A test may additionally be of these types:

• "rpt-bearer" (specific to the mandatory-to-implement "bearer" RPT profile)
• "claim-oidc" (specific to the optional OpenID Connect claim profile)
• "optim-asc"  (specific to the forthcoming optional AS=C optimization profile)
• "humanrqp" (specific to the claims-gathering flow for clients operated by end-users)

Tests could be added to cover additional UMA WG-specified or third-party profiles, in which case the possible type values will expand. Generic high-level features of the protocol have an ID in the form "F-", and they group feature tests that have an ID in the form "FT-".

Where spec text is quoted, be aware that it may be out of date. In cases of discrepancy, please alert the UMA leadership team or the WG list; the real spec is always normative.

1. F-as-config: AS makes available its configuration data in the correct form at the correct location

The feature tests in this section have been reviewed.

This feature is about machine-readability of capabilities and constraints.

Supporting clauses

• Core 1.4: "The authorization server MUST provide configuration data in a JSON [RFC4627] document that resides in an /uma-configuration directory at at its hostmeta [hostmeta] location."
• Core 1.4: "Authorization server configuration data MAY contain extension properties that are not defined in this specification."
• Core 1.4: "All endpoint URIs SHOULD require the use of a transport-layer security mechanism such as TLS. The authorization server MUST declare all of its endpoints in its configuration data."
• (Also all the REQUIREDs/MUSTs and MAYs appearing in Core Sec 1.4 regarding the JSON format for AM configuration data.)
• Core 2: "The resource owner, resource server, and authorization server perform the following actions to put resources under protection. This list assumes that the resource server has discovered the authorization server's configuration data and endpoints as needed." (non-normative)
• RSR 1.3: "If the authorization server declares its endpoints and any other configuration data in a machine-readable form, for example [OAuth-linktypes] or [OAuth-meta], it SHOULD convey its resource set registration endpoint in this fashion as well."

2. F-dyn-client-reg: AS supports generating dynamic client credentials and RS and client support getting them

The feature tests in this section have been reviewed.

This feature is about client registration of resource servers (which are clients of the AS's protection API) and clients of resource servers (which are also clients of the AS's authorization API) at run time when services have not "met" before a resource owner or requesting party forces the issue.

Supporting clauses

• Core 1.4: "dynamic_client_endpoint - OPTIONAL. The endpoint to use for performing dynamic client registration. Usage is defined by [DynClientReg]. The presence of this property indicates authorization server support for the dynamic client registration feature and its absent indicates a lack of support."
• Core 2: "It is OPTIONAL for the client credentials to be provided dynamically through [DynClientReg]); alternatively, they MAY use a static process."

Issues

1. Typo in Core Sec 1.4: s/absent/absence/

3. F-pat: AS successfully issues PAT to RS for use at AS's protection API

The feature tests in this section have been reviewed.

This feature is about "protection of the protection API" at the authorization server, and the association made between the authorization server, resource server, and resource owner as a result of protection API token (PAT) issuance.

Supporting clauses

• Core 1: "To accomplish this protection, the authorization server presents a protection API ("C") to the resource server. This API is OAuth-protected and requires a protection API token (PAT) for access." (non-normative)
• Core 1.3.1: "The authorization server presents a protection API to the resource server and an authorization API to the client. These APIs MUST be OAuth-protected; thus, the authorization server has an OAuth token endpoint and user authorization endpoint, and has the option to issue an OAuth refresh token along with any access tokens issued for these APIs."
• Core 1.3.1: "An entity seeking protection API access MUST request the scope "http://docs.kantarainitiative.org/uma/scopes/prot.json", and an access token with at least this scope is called a protection API token (PAT). ... The same entity can serve in both roles, so that an OAuth access token might be considered both a PAT and an AAT if it has both scopes. If a request to an endpoint fails due to an invalid, missing, or expired PAT or AAT, or requires higher privileges at this endpoint than provided by the PAT or AAT, the authorization server responds with an OAuth error."
• Core 1.3.1: "The authorization server is REQUIRED to support the OAuth bearer token profile for PAT and AAT issuance, and MAY support other OAuth token profiles for these purposes. It MUST declare all supported token profiles for PAT and AAT issuance in its configuration data."
• Core 1.3.1: "The authorization server MAY support the use of any OAuth grant type for PAT and AAT issuance, but MUST support the authorization_code grant type, and SHOULD support the SAML bearer token grant type [OAuth-SAML] (urn:ietf:params:oauth:grant-type:saml2-bearer) if it anticipates working with entities that are operating in environments where the use of SAML is prevalent. It MUST declare its supported grant types for PAT and AAT issuance in its configuration data."
• Core 1.4: "pat_profiles_supported - REQUIRED."
• Core 1.4: "pat_grant_types_supported - REQUIRED."
• Core 1.4 : "token_endpoint - REQUIRED."
• Core 1.4 : "user_endpoint - REQUIRED."
• Core 1.4 : "A valid PAT MUST accompany requests to this (introspection_endpoint) protected endpoint."
• Core 1.4 : "A valid PAT MUST accompany requests to this (resource_set_registration_endpoint) protected endpoint."
• Core 1.4 : "A valid PAT MUST accompany requests to this (permission_registration_endpoint) protected endpoint."
• Core 3.2: "The resource server MUST provide its valid PAT in order to get access to (permission_registration_endpoint) endpoint."
• Core 3.3.1: "The authorization server MUST OAuth-protect this (introspection_endpoint) endpoint and require a PAT from the resource server for access to it."

4. F-aat: AS successfully issues AAT to Client for use at AS's authorization API

The feature tests in this section have been reviewed.

This feature is about "protection of the authorization API" at the authorization server, and the association made between the authorization server, client, and requesting party as a result of authorization API token (AAT) issuance.

Supporting clauses

• Core 1: "The (authorization) API is OAuth-protected and requires an authorization API token (AAT) for access." (non-normative)

• Core 1.3.1: "The authorization server presents a protection API to the resource server and an authorization API to the client. These APIs MUST be OAuth-protected; thus, the authorization server has an OAuth token endpoint and user authorization endpoint, and has the option to issue an OAuth refresh token along with any access tokens issued for these APIs."
• Core 1.3.1: "An entity seeking authorization API access MUST request the scope "http://docs.kantarainitiative.org/uma/scopes/authz.json", and an access token with at least this scope is called an authorization API token (AAT). The same entity can serve in both roles, so that an OAuth access token might be considered both a PAT and an AAT if it has both scopes. If a request to an endpoint fails due to an invalid, missing, or expired PAT or AAT, or requires higher privileges at this endpoint than provided by the PAT or AAT, the authorization server responds with an OAuth error."
• Core 1.3.1: "The authorization server is REQUIRED to support the OAuth bearer token profile for PAT and AAT issuance, and MAY support other OAuth token profiles for these purposes. It MUST declare all supported token profiles for PAT and AAT issuance in its configuration data."
• Core 1.3.1: "The authorization server MAY support the use of any OAuth grant type for PAT and AAT issuance, but MUST support the authorization_code grant type, and SHOULD support the SAML bearer token grant type [OAuth-SAML] (urn:ietf:params:oauth:grant-type:saml2-bearer) if it anticipates working with entities that are operating in environments where the use of SAML is prevalent. It MUST declare its supported grant types for PAT and AAT issuance in its configuration data."
• Core 1.4: "aat_profiles_supported - REQUIRED."
• Core 1.4: "aat_grant_types_supported - REQUIRED."
• Core 1.4 : "token_endpoint - REQUIRED."
• Core 1.4 : "user_endpoint - REQUIRED."
• Core 1.4 : "A valid PAT MUST accompany requests to this (rpt_endpoint) protected endpoint."
• Core 1.4 : "A valid PAT MUST accompany requests to this (authorization_request_endpoint) protected endpoint."
• Core 3: "If the client does not already have an AAT at the appropriate authorization server to be able to use its authorization API, it first obtains one." (non-normative)
• Core 3.4: "2. The client acquires an AAT. This enables it to use authorization API endpoints." (non-normative)
• Core 3.4.1: "It (client) obtains an RPT by performing a POST on the RPT endpoint. It MUST provide its own valid AAT in the header."
• Core 3.4.2: "It (client) performs a POST on the authorization request endpoint, supplying its own AAT in the header and its RPT and the permission ticket in a JSON object with properties "rpt" and ticket", respectively."

5. F-rsr: RS registers resource sets at AS in order to put them under AS protection

The feature tests in this section have been reviewed.

This feature is about putting resources under protection by a third party.

Supporting clauses

• Core 2: "In an ongoing fashion, the resource server registers any resource sets with the authorization server for which it intends to outsource protection, using the process defined by [OAuth-resource-reg]." (non-normative)
• RSR 2.1: "Scope descriptions MAY contain extension properties that are not defined in this specification."
• RSR 2.2: "When a resource server creates or updates a resource set description (see Section 2.3), the authorization server MUST attempt to retrieve the referenced scope descriptions so that it can present fresh data in any resource owner interactions."
• RSR 2.3: "Following is a summary of the five registration operations the authorization server is REQUIRED to support. Each is defined in its own section below. All other methods are unsupported." (see all RSR 2.3 subsections)
• RSR 2.3: "If the request to the resource set registration endpoint is incorrect, then the authorization server responds with an error message by including one of the following error codes with the response..."

6. F-protect-rsrc: RS, AS, and client interact to enable authorized access to protected resources and block unauthorized access

The feature tests in this section have not yet been reviewed.

This feature is about protecting resources in practice, at run time. This involves a successive series of "gates": having a valid RPT, supplying any claims needed to assess against policy, having valid authorization data that matches the type of access sought, etc.

Supporting clauses

• Core 1.3.2: "The resource server presents one or more protected resource endpoints to the client; these endpoints are protected by the UMA profile of OAuth and require a requesting party token (RPT) with sufficient authorization data for access." (non-normative)
• Core 1.3.2: "This specification defines one RPT profile, call "bearer" (see Section 3.3.2), which is REQUIRED for the authorization server to support."
• Core 2: "Once a resource set has been placed under authorization server protection through the registration of a resource set description for it, and until such a description's deletion by the resource server, the resource server MUST limit access to corresponding resources, respecting authorization data associated with client-presented RPTs by the authorization server as appropriate."
• Core 3: "Each interaction (as part of getting authorization and access a resource) MAY be the last, if the client chooses not to continue pursuing the access attempt or the resource server chooses not to continue facilitating it."
• Core 3.1.1: "If the client does not present an RPT with the request, the resource server MUST return an HTTP 401 (Unauthorized) status code, along with providing the authorization server's URI in an "as_uri" property to facilitate authorization server configuration data discovery, including discovery of the endpoint where the client can request an RPT."
• Core 3.1.2: "If the client presents an RPT with its request, the resource server MUST determine the RPT's status (see Section 3.3) before responding. If the RPT is invalid, the resource server MUST return an HTTP 401 (Unauthorized) status code, along with providing the authorization server's URI in an "as_uri" property in the header, similarly to the case where no RPT was presented."
• Core 3.1.2: "If the RPT is valid but has insufficient authorization data for the type of access sought, the resource server SHOULD register a requested permission with the authorization server that would suffice for that scope of access (see Section 3.2), and then respond with the HTTP 403 (Forbidden) status code, along with providing the authorization server's URI in an "as_uri" property in the header, and the permission ticket it just received from the AM in the body in a JSON-encoded "ticket" property."
• Core 3.1.2: "If the RPT's status is associated with authorization data that is consistent with authorized access of the scope sought by the client, the resource server MUST give access to the desired resource."
• Core 3.1.2: "The resource server MUST NOT give access where the token's status is not associated with sufficient authorization data for the attempted scope of access."
• Core 3.2: "The (permission) ticket value MUST be securely random (for example, not merely part of a predictable sequential series), to avoid denial-of-service attacks."
• Core 3.2: "If the registration request is successful, the authorization server responds with an HTTP 201 (Created) status code and includes the Location header in its response as well as the "ticket" property in the JSON-formatted body."
• Core 3.2: "If the registration request is authenticated properly but fails due to other reasons, the authorization server responds with an HTTP 400 (Bad Request) status code and includes one of the following UMA error codes..."
• Core 3.3.2: "On receiving an RPT of the "Bearer" type in an authorization header from a client making an access attempt, the resource server MUST introspect the token by using the authorization server's token introspection endpoint. ... The authorization server responds with a JSON object with the structure dictated by [OAuth-introspection]."
• Core 3.4.1: "It (client) obtains an RPT by performing a POST on the RPT endpoint. ... The authorization server responds with an HTTP 201 (Created) status code and provides a new RPT."
• Core 3.4.1: "If the AAT provided in the header is the same as one provided for a previously issued still-valid RPT by this authorization server, the authorization server invalidates the old RPT and issues a new one."
• Core 3.4.2: "It (client) performs a POST on the authorization request endpoint, supplying its own AAT in the header and its RPT and the permission ticket in a JSON object with properties "rpt" and ticket", respectively."
• Core 3.4.2: "The authorization server MUST base the addition of authorization data to RPTs on user policies."

Issues

1. Break down these feature tests into smaller chunks? What makes sense? The list of supporting clauses will be huge once we fill it in. Some candidates: MTI "bearer" RPT support vs. other profiles.
2. "User policies" isn't testable; how do we shore up this wording in FT-as-give-authz-data?
3. Need more rptbearer-specific tests?
4. Add claimoidc-specific tests?
5. Add optasc-specific tests?
6. Regarding FT-rs-respect-authz-data: Is this truly a testable assertion, or is it in the realm of Binding Obs? Doublecheck what language we really have in the current spec about this need for "respecting" permissions. See Section 2 of the Core spec.
7. Regarding FT-as-issue-rpt: Is it too implementation-specific that the spec says that "If the AAT provided in the header is the same as one provided for a previously issued still-valid RPT by this authorization server, the authorization server invalidates the old RPT and issues a new one." in Section 3.4.1? The AS could instead have refreshed the same RPT that had expired and give it back.
8. Regarding FT-rs-introspect-rpt: The client currently has no way of knowing if the RPT is about to expire, and it could be more efficient if it could look this up through token introspection. Should we consider this for the spec?
9. Regarding FT-rs-register-permission and FT-as-permission-ticket: Can the RS register a whole bunch of permissions at the same time?
10. Regarding FT-as-oidc-client: This is sort of an implicit callout to the OpenID Connect interop tests. Do we even need this? Is anyone planning to test this for UMA1? See Section 3.5.1.1 for the list of things an AS has to do to conform to this claim profile.
11. We have a new philosophical question: Even if the AS=C optimization profile is in use, is it mandatory-to-implement for the AS to present real and functional HTTPS endpoints for clients that "aren't it" (the same system entity) to use? If so, our various "req" feature tests below are true. If not, do we make them "opt" and "non-optim-asc" (the inverse of "optim-asc")? In any case, we should be sure to explicitly list the MUSTs that get turned off in this profile (and other such profiles). Maciej is thinking we may, after all, want to put health warnings next to each MUST – it might not be that onerous, and we will have done all the work anyway! Spec readers would otherwise be challenged.