[WG-UMA] AI: Feature test proposals

Eve Maler eve at xmlgrrl.com
Thu Jun 21 23:29:20 EDT 2012


Here's another AI that I was supposed to have finished before today's call. Sorry about that! At least I was able to get to it on my (interminable) plane ride.

Trey, hopefully this will give you some good ideas how to proceed with your Section 3 feature test proposals; it seemed to make sense to capture spec issues as I went along, just so nothing got lost.

I've dipped into some Section 3 testable assertions here, but only as they relate to UMA's supporting infrastructure, so to speak. That includes AM config data stuff for requesters and also AAT stuff. Your part includes all the RPT-related flows.

Note: All "supporting clauses" quotes below are from the current rev, 05a. As the spec undergoes revision, we should evaluate whether to continue upkeep of these quoted clauses. I mostly just wanted to collect anything that looked like a testable assertion related to each overall feature, and then stare at them for a bit while coming up with the proposed tests...

	Eve

======
Feature: Adherence to binding obligations

Supporting clauses:
Sec 1 intro: "Parties operating entities that claim to be UMA-compliant MUST adhere to these expected behaviors." (That is, the ones defined in [UMA-trustmodel].)

Feature tests:
?

Issues:
Should this clause appear in the technical spec, or only in the upper-level Binding Obligations doc? If it appears in the spec, should it be worded differently? Should it, for example, require entities claiming conformance to provide documentation affirmatively stating their acceptance of the Binding Obligations contractual framework?
What are the sensible feature tests to have for this, if any? This isn't a testable assertion in its current form.

======
Feature: AM configuration data

Supporting clauses:
Sec 1.5: "The AM MUST provide configuration data to other entities it interacts with in a JSON [RFC4627] document that resides in an /uma-configuration directory at at its hostmeta [RFC6415] location."
Sec 1.5: "AM configuration data MAY contain extension properties that are not defined in this specification."
Sec 1.5: "All endpoint URIs supplied SHOULD require the use of a transport-layer security mechanism such as TLS."
(Also all the MUSTs and MAYs appearing in Section 1.5 regarding the JSON format for AM configuration data.)
Sec 2.1: "From the data provided, discovered, or configured, the host MUST retrieve the AM's configuration data document, as described in Section 2 of hostmeta [RFC6415]."
Sec 3.4.1: "From the "am_uri" information provided in the host's response, the requester MUST retrieve the AM's configuration data document, as described in Section 2 of hostmeta [RFC6415]."

Feature tests:
(Optional) The AM publishes endpoints that use the https: URI scheme.
The host successfully accesses and parses AM configuration data properties it needs at location http://{am_uri}/.well-known/uma-configuration or https://{am_uri}/.well-known/uma-configuration. (This includes, at a minimum, all the endpoint-related properties not specific to the requester.)
The requester successfully accesses and parses AM configuration data properties it needs at location http://{am_uri}/.well-known/uma-configuration or https://{am_uri}/.well-known/uma-configuration. (This includes, at a minimum, all the endpoint-related properties not specific to the host.)
The host successfully handles the presence of non-understood extension properties in the AM configuration data.
The requester successfully handles the presence of non-understood extension properties in the AM configuration data.

Issues:
At this point, should we just assume that if hosts or requesters or others need to access the generic AM configuration data that goes beyond endpoints, we can add more feature tests later?
There are numerous MUSTs throughout the Section 1.5 definitions of the configuration data properties that are unrelated to the configuration data itself, but related to the usage of the various features and endpoints being described. Should this normative text be moved elsewhere?

======
Feature: (Optional) Dynamic client registration

Supporting clauses:
Sec 1.5: "The value, if this property is present, the value MUST be the string "yes" (dynamic registration is supported, using an unspecified method) or "no" (it is not supported; hosts and requesters are required to pre-register)." (The property being dynamic_client_registration_supported.)
Sec 2.2: "If the host has not already obtained an OAuth client identifier and optional secret from this AM, in this step it MUST do so in order to engage in OAuth-based interactions with the AM."
Sec 3.4.2: "If the requester has not already obtained an OAuth client identifier and optional secret from this AM, in this step it MUST do so in order to engage in OAuth-based interactions with the AM."

Feature tests:
(Optional) The AM supplies a dynamic_client_registration_supported AM configuration data property with a value of "yes".
(Optional) The host successfully receives client credentials dynamically from the AM.
(Optional) The requester successfully receives client credentials dynamically from the AM.

Issues:
There's a MAY related to dynamic client registration in Sec 2 intro ("It MAY do this using [OCDynClientReg], if the AM supports it."), which should be removed because it's duplicative and adds no value where it is.
Fix the double "the value" in Sec 1.5 where the property is defined.
Do we need to soften the description of "client identifier and optional secret" in Sec 2.2 and 3.4.2 to account for OAuth's more abstract direction these days?

======
Feature: Protection API token issuance

Supporting clauses:
Sec 1.5: "oauth_token_profiles_supported REQUIRED. …. The AM is REQUIRED to support this profile, and to supply this string value explicitly. The AM MAY declare its support for additional access token profiles by providing a unique absolute URI in a string value in the array for each one." (This profile being the bearer token profile.)
Sec 1.5: "oauth_grant_types_supported REQUIRED. …. Each string value MUST be one of the grant_type values defined in [OAuth2], or alternatively an extension grant type indicated by a unique absolute URI."
Sec 1.5: "token_endpoint REQUIRED."
Sec 1.5: "user_endpoint REQUIRED."
Sec 2.3: "The host MUST use OAuth 2.0 [OAuth2] to obtain the protection API token."
Sec 2.3: "The AM MAY support the use of any grant type, 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 hosts that are operating in environments where the use of SAML is prevalent. The AM MUST indicate all grant types it supports in its configuration data, as defined in Section 1.5."

Feature tests:
The AM, host, and authorizing user successfully engage in an OAuth 2.0 authorization_code flow for a PAT that has the "protection" scope. (As appropriate, this flow should result in a PAT being issued, or an OAuth-level error condition. Mostly this feature test should outsource to OAuth testing.)
(Optional) The AM, host, and authorizing user successfully engage in grant flows other than authorization_code for which the AM declares support and the host has support.

Issues:
None.

======
Feature: Protection API token usage

Supporting clauses:
Sec 1.3: "The AM presents the following endpoints to the host as part of its protection API; these endpoints are OAuth-protected and require a PAT for access, for which the "protection" OAuth scope is required…"
Sec 1.5: "resource_set_registration_endpoint REQUIRED. …. A PAT MUST accompany requests to this protected endpoint."
Sec 2.4.3: "The host MUST use its valid PAT obtained previously to gain access to this endpoint." (This endpoint being resource_set_registration_endpoint.)
Sec 3.2: "The host registers the permission using the POST method at the AM's permission registration endpoint, providing its PAT to get access to this endpoint."
Sec 3.3.1: "In order to ask the AM for an RPT's status, the host makes the request to the AM with a POST request to the AM's RPT status endpoint."

Feature tests:
The AM requires a valid PAT to be presented by the host for access to protection API endpoints.

Issues:
The references to endpoint usage in Sec 3.2 and Sec 3.3.1 should prescribe (MUST) the use of PATs.

======
Feature: Authorization API token issuance

Supporting clauses:
Sec 1.5: "oauth_token_profiles_supported REQUIRED. …. The AM is REQUIRED to support this profile, and to supply this string value explicitly. The AM MAY declare its support for additional access token profiles by providing a unique absolute URI in a string value in the array for each one."
Sec 1.5: "oauth_grant_types_supported REQUIRED. …. Each string value MUST be one of the grant_type values defined in [OAuth2], or alternatively an extension grant type indicated by a unique absolute URI."
Sec 1.5: "token_endpoint REQUIRED."
Sec 1.5: "user_endpoint REQUIRED."
Sec 2.3: "The AM MAY support the use of any grant type, but MUST support the authorization_code grant type, and SHOULD support the SAML bearer token grant type [OAuth‑SAML]…. The AM MUST indicate all grant types it supports in its configuration data, as defined in Section 1.5."
Sec 3.4.3: "The requester MUST use OAuth 2.0 [OAuth2] to obtain the AAT."

Feature tests:
The AM, requester, and requesting party successfully engage in an OAuth 2.0 authorization_code flow for an AAT that has the "authorization" scope. (As appropriate, this flow should result in an AAT being issued, or an OAuth-level error condition. Mostly this feature test should outsource to OAuth testing.)
(Optional) The AM, requester, and requesting party successfully engage in grant flows other than authorization_code for which the AM declares support and the requester has support.

Issues:
None.

======
Feature: Authorization API token usage

Supporting clauses:
Sec 1.3: "The AM presents the following endpoint to the requester as part of its authorization API; this endpoint is OAuth-protected and requires an AAT for access, for which the "authorization" OAuth scope is required…"
Sec 3.4.4: "The requester performs a POST on the RPT endpoint, supplying its own AAT in the header in order to gain access to the RPT endpoint."
Sec 3.4.5: "The requester performs a POST on the permission request endpoint, supplying: … Its own AAT in the header in order to gain access to the permission request endpoint"

Feature tests:
The AM requires a valid AAT to be presented by the requester for access to authorization API endpoints.

Issues:
Fix the singular reference to "endpoint" in Sec 1.3 regarding AAT-protected endpoints; there are now two of them again.
The references to endpoint usage in Sec 3.4.4 and 3.4.5 should prescribe (MUST) the use of AATs.

======
Feature: Resource set registration mechanisms

Supporting clauses:
Sec 2.4 intro: "Once the host has received a PAT, for any of the user's sets of resources that are to be protected by this AM, it MUST register these resource sets at the AM's registration endpoint."
Sec 2.4.1: "Scope description documents MUST be accessible to AMs through GET calls made to these URI references" (These being scope URI references.) 
Sec 2.4.3: "The AM MUST present an API for registering resource set descriptions at a set of URIs with the structure "{rsreguri}/resource_set/{rsid}", where the PAT provides sufficient context to distinguish between identical resource set identifiers assigned by different hosts."
Sec 2.4.3: "Following is a summary of the five registration operations the AM is REQUIRED to support…"
Sec 2.4.3: "If the request to the resource set registration endpoint is incorrect, then the AM responds with an error message (see Section 4.2) by including one of the following error codes with the response…"
Sec 2.4.3.1: "On successfully registering a resource set, the host MUST use UMA mechanisms to limit access to any resources corresponding to this resource set, relying on the AM to supply currently valid permissions for authorized access."
Sec 2.4.3.1: "On successful registration, the AM MAY return a redirect policy URI to the host in a property with the name "policy_uri"."
Sec 2.4.3.3: "On successful update, the AM MAY return a redirect policy URI to the host in a property with the name "policy_uri"."
Sec 3.2: "If the registration request is authenticated properly but fails due to other reasons, the AM responds with an HTTP 400 (Bad Request) status code and includes one of the following UMA error codes..."

Feature tests:
The host successfully uses PUT with a unique ID to register a new resource set description at the AM.
The host successfully uses GET with a unique ID to read an already-registered resource set description at the AM.
The host successfully uses PUT with If-Match and a unique ID to update an already-registered resource set description at the AM.
The host successfully uses DELETE with a unique ID to delete an already-registered resource set description at the AM.
The host successfully uses GET on the resource_set path to read a list of already-registered resource set descriptions.
The AM produces the appropriate UMA-level and HTTP-level errors for incorrect resource set registration requests.
The host uses UMA mechanisms for protecting access to a resource set and its scopes according to the currently registered condition of the resource set. (For example, once a host deletes a resource set, it and the AM should no longer expect to use UMA flows for its protection.)
The AM produces an invalid_resource_set_id error when the host attempts to register a permission not associated with a currently registered resource set.
The AM produces an invalid_scope error when the host attempts to register a permission with a scope that was not already associated with this resource set.
The host successfully handles the presence of a policy_uri property in the AM's response to resource set creation.
The host successfully handles the presence of a policy_uri property in the AM's response to resource set updating.

Issues:
Need a period at the end of the scope URI paragraph in Sec 2.4.1.
The requirement in Sec 2.4.3.1 is both broader and more specific, and perhaps should be moved up to 2.4.3 with an explanation that the host MUST outsource protection to the AM according to the currently registered state of a resource set. For example, if it's been deleted and is no longer under AM protection, the original MUST wouldn't apply as stated. (Details of how protection actually works would be covered under features associated with Sec 3.)

======
Feature: Resource set and scope descriptions

Supporting clauses:
Sec 2.4.1: "Scope descriptions MAY contain extension properties that are not defined in this specification."
Sec 2.4.1: "A host MUST list a resource set's available scopes using URI references (as defined in Section 2.4.2). The scopes available for use at any one host MUST have unique URI references so that the host's scope descriptions are uniquely distinguishable. A scope URI reference MAY include a fragment identifier. Scope descriptions MAY reside anywhere."
Sec 2.4.2: "Resource set descriptions MAY contain extension properties that are not defined in this specification."
Sec 2.4.2: "The AM SHOULD use the scope names and any icons defined as part of the referenced scopes in its user interface to assist the user in setting policies for protecting this resource set."
Sec 2.4.2: "When a host creates or updates a resource set description (see Section 2.4.3), the AM MUST attempt to retrieve the referenced scope descriptions. It MAY cache such descriptions as long as indicated in the HTTP cache-control header for the scope description resource unless the resource set description is subsequently updated within the validity period. At the beginning of an authorizing user's login session at the AM, the AM MUST attempt to re-retrieve scope descriptions applying to that user whose cached versions have expired."
Sec 2.4.3: "The host is free to use its own methods of identifying and describing resource sets. The AM MUST treat them as opaque for the purpose of authorizing access, other than associating them with the authorizing user represented by the PAT used to access the API."

Feature tests:
The AM successfully accesses the scope descriptions associated with a registered resource set description at the time the host creates a resource set description.
The AM successfully accesses the scope descriptions associated with a registered resource set description at the time the host updates a resource set description.
The AM attempts to re-retrieve all scope descriptions whose cached versions have expired at the time the authorizing user begins an interaction session at the AM.
(Optional) In the interface it presents to an authorizing user, the AM uses the scope names and any icons defined as part of the registered scope descriptions associated with that user.

Issues:
None.

Eve Maler                                  http://www.xmlgrrl.com/blog
+1 425 345 6756                         http://www.twitter.com/xmlgrrl


-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://kantarainitiative.org/pipermail/wg-uma/attachments/20120621/7cd45ed0/attachment-0001.html 


More information about the WG-UMA mailing list