UDAP Dynamic Client Registration

DRAFT 2018-07-14

Registration with an Authorization Server is typically required before a Client Application can access protected resources using the OAuth 2.0 authorization framework. For larger ecosystems with numerous clients and authorization servers, manual client registration requiring one-off enrollments or pairwise key exchange presents a significant barrier. Such communities can leverage a distributed system of authoritative information through the use of digital certificates to enable a scalable dynamic solution to client registration, allowing real-time trust assessment, validation of identifying attributes, and support for revocation.

UDAP implements dynamic client registration using digital certificates as an extension to the OAuth 2.0 dynamic client registration protocol defined in RFC 7591. Use of this extension is requested by Client Apps by including a digitally signed software statement in their requests to the registration endpoint, where the signature is backed by an X.509 certificate. This framework also allows Client Apps to submit digitally signed certifications and endorsements provided by third parties as part of their registration request, which can be independently validated by the Authorization Server prior to allowing the registration of a Client App.

This protocol is based upon standard Public Key Infrastructure tools. Before granting registration, the Authorization Server validates the digital signature on the software statement submitted by the Client App, and evaluates the trust chain for the Client App’s certificate. Client registration is permitted only if the software statement is valid and the Client App’s certificate is trusted. This protocol MAY be used only by Client Apps that are able to protect the private key used to sign software statements, e.g. confidential clients and certain native device apps.

Note: The HTTP request and response examples presented below are non-normative. For readability purposes, line wraps have been added to some HTTP headers and request bodies, some headers have been omitted, and some parameters have not been URL encoded.

The following steps define the workflow:

1. The Client App checks that the Authorization Server supports UDAP by retrieving the Authorization Server’s UDAP metadata from a well-known URL.

GET /.well-known/udap HTTP/1.1
Host: resourceholder.example.com

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "x5c" : ["{cert1}", "{cert2}", …]
}

If the Authorization Server returns an error code, then the Authorization Server does not support UDAP Dynamic Client Registration and the Client App should abort this workflow.

2. The Client App prepares a software statement for submission. The software statement serves three purposes: it provides the necessary metadata for registration, it establishes the Client App’s control of a private key, and it provides the digital certificate needed to validate the signature and establish trust.

The software statement is a signed JWT containing the following claims:

   iss: Client App Operator’s unique identifying URI (identifying the holder of private key, also serves as the base URI for UDAP metadata including lookup of certificates)
   sub: same as iss
   aud: base URL of Authorization Server
   exp: expire time (should be short-lived, max 5 minutes from iat)
   iat: issued at time
   jti: token identifier used to identify token replay
   client_name: string
   redirect_uris: array of URIs
   grant_types: authorization_code | client_credentials
   response_types: code (omit for client_credentials)
   token_endpoint_auth_method: private_key_jwt

The JOSE Header for the software statement contains the following key/value pairs:

   alg : "RS256"
   x5c : [cert1, cert2, …] (cert1 is required; remainder of chain is optional)
   x5u : valid URI (optional)

The x5c claim contains the Client App’s certificate chain as an array of one or more elements, each containing a base64 encoded representation of the DER encoded X.509 certificate. The leaf certificate (cert1) contains the public key corresponding to the private signing key used by the Client App to digitally sign the software statement. The software statement is signed and assembled using JWS compact serialization as per RFC 7515.

3. The client requests registration by submitting the signed software statement to the Authorization Server’s registration endpoint. The additional extension parameter “udap” is also included with a string value of “1” to signal to the Authorization Server that version 1 of this protocol is being used, and that the included software statement conforms to this profile. Optionally, the Client App MAY submit certifications or endorsements provided by third parties by including the optional extension parameter “certifications” with a value of an array of one or more signed JWTs, each representing a separate certification or endorsement:

POST /register HTTP/1.1
Host: as.example.com
Content-type: application/json

{
   "software_statement" : "{signed software statement}",
   "certifications" : [array of one or more signed JWTs],
   "udap" : "1"
}

4. Authorization Server validates request

4.1 The Authorization Server validates the digital signature on the software statement using the public key extracted from cert1 in the x5c parameter of the JOSE header. If the signature cannot be validated, the request is denied.

4.2 The Authorization Server attempts to construct a valid certificate chain from the Client’s certificate (cert1) to an anchor certificate trusted by the Authorization Server using conventional X.509 chain building techniques and path validation, including certificate validity and revocation status checking. The Client SHOULD submit a complete certificate chain in its request. The Authorization Server MAY use additional certificates not included by the Client to construct a chain (e.g. from its own certificate cache or discovered via the X.509 AIA mechanism). If a trusted chain cannot be built and validated by the Authorization Server, the request is denied.

4.3 The Authorization Server validates the aud, exp, iat, and jti values. The aud value MUST contain the Authorization Server’s base URL, and the software statement MUST be unexpired. A maximum software statement lifetime of 5 minutes is RECOMMENDED. The Authorization Server MAY deny a request if the same software statement (as determined by the jti value) has been used in a previous registration request.

4.4 The Authorization Server validates the registration parameters in the software statement. If a parameter is invalid or a required parameter is missing, the request is denied.

4.5 If there has been a previous registration granted by the Authorization Server linked to the public key submitted by the Client for the requested grant type, the Authorization Server MAY cancel the previous registration.

5. Authorization responds to request

5.1 If the request is granted, the Authorization Server returns a registration response as per Section 3.2.1 of RFC 7591. The top-level elements of the response SHALL include the client_id issued by the Authorization Server for use by the Client App, the software statement as submitted by the Client App, and all of the registration related parameters that were included in the software statement:

HTTP/1.1 201 Created
Content-Type: application/json

{
   "client_id": "example_client_id_issued_by_AS",
   "software_statement": "{the software statement as submitted by the client}",
   "client_name": string,
   "redirect_uris": [array of URIs],
   "grant_types": "authorization_code",
   "response_types": "code",
   "token_endpoint_auth_method": "private_key_jwt"
}

In addition, the Authorization Server MUST store the certificate provided by the Client for use to validate subsequent client authentication attempts.

5.2 If the request is denied, the Authorization Server returns an error as per Section 3.2.2 of RFC 7591. Denials related to trust validation SHOULD use the “unapproved_software_statement” code. Denials related to invalid signatures should use the “invalid_software_statement” code. The Authorization Server MAY include an error_description parameter. For example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
   "error": "unapproved_software_statement"
}

Note: if the Client App receives an error code from the Authorization Server, then the Client App MAY attempt registration again by generating a new software statement specifying a different client certificate. For example, if the Client App has been issued two certificates corresponding to two trust communities, it MAY attempt registration using the second certificate if the registration using the first certificate is denied. The Client App SHOULD NOT attempt registration again with the same certificate if an unapproved_software_statement error is returned.

6 References

Cooper, D., et al. “Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile”, RFC 5280, RFC Editor, May 2008.
Hardt, D., Ed., “The OAuth 2.0 Authorization Framework”, RFC 6749, RFC Editor, October 2012.
Jones, M., et al, “JSON Web Token (JWT)”, RFC 7519, RFC Editor, May 2015.
Richer, J., Ed., “OAuth 2.0 Dynamic Client Registration Protocol”, RFC 7591, RFC Editor, July 2015.

7 Authors

Luis C. Maas III, EMR Direct

8 Notices

Copyright ©2016-2018 UDAP.org and the persons identified as the document authors. All rights reserved.

UDAP.org grants to any interested party a non-exclusive, royalty-free, worldwide right and license to reproduce, publish, distribute and display this Draft Specification, in full and without modification, solely for the purpose of implementing the technology described in this Draft Specification, provided that attribution is made to UDAP.org as the source of the material and that such attribution does not indicate an endorsement by UDAP.org.

All Draft Specifications and Final Specifications, and the information contained therein, are provided on an “AS IS” basis and the authors, the organizations they represent, and UDAP.org make no (and hereby expressly disclaim any) warranties, express, implied, or otherwise, including but not limited to any warranty that the use of the information therein will not infringe any rights or any implied warranties of merchantability or fitness for a particular purpose, and the entire risk as to implementing this specification is assumed by the implementer. Additionally, UDAP.org takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available, nor does it represent that it has made any independent effort to identify any such rights.