UDAP Certifications and Endorsements for Client Applications

DRAFT 2018-09-24

UDAP supports portable electronic client certifications that can be used by a Certifier to express verified attributes about a client application developer or a specific client application. A Certification can also be used to express an endorsement of a client application developer or application.

A client application developer can provider one or more certifications to an OAuth Server when registering its client application. This includes both manual and dynamic client registration processes. The OAuth Server can use the information in the certifications to determine whether or not to accept a client registration request. For authorization flows that interact with client app end users, the OAuth Server can also use the information in the certifications can also be used to inform the end user about the client.

Certifications are constructed as signed JWTs. These JWTs follow the UDAP profile for JWTs to allow authentication of a Certifier using standard PKIX tools. Before accepting a certification, the Authorization Server validates the digital signature on the certification, and evaluates the trust chain for the Certifier’s X.509 certificate used to perform this validation. The certification is accepted only if the certification is valid and the Certifier’s certificate is trusted.

The following steps define the work flow for a Certifier to generate a certification JWT:

1. The Certifier prepares a certification for submission. The certification serves three purposes: it provides the necessary metadata for registration, it establishes the Certifier’s control of a private key, and it provides the digital certificate needed to validate the signature on a certification and establish trust. The certification is a signed JWT containing the following claims:

iss

Certifier’s unique identifying URI

sub

client’s unique identifying URI (binds to SAN:uniformResourceIdentifier in Client App certificate)

aud

base URL of Authorization Server (optional, single valued or array). If absent, this certification is intended for all audiences.

exp

expire time (max 3 years, must not expire after certificate)

iat

issued at time

jti

token identifier that uniquely identifies this JWT until the expiration time

certification_name

string; short name for certification (required)

certification_logo

URI (optional); URI pointing to logo for this certification, e.g. seal

certification_description

string; longer description of what this certification entails (optional)

certification_uri

string; URI for more information (optional)

is_endorsement

boolean (default: false); true if this certification represents an endorsement of the Client App by the issuer.

developer_name

string (optional)

developer_address

as per OIDC Core 1.0 Section 5.1.1

client_name

as per RFC 7591

software_id

as per RFC 7591 (recommended)

software_version

as per RFC 7591 (optional)

client_uri

as per RFC 7591

logo_uri

as per RFC 7591

tos_uri

as per RFC 7591

policy_uri

as per RFC 7591

contacts

as per RFC 7591, further constrained as follows: array of string; mailto: + https:// so that AS operator can contact client app developer

launch_uri

for SMART app launch with EHR launch flow, requires scope includes launch

redirect_uris

as per RFC 7591, except as noted; an array of fully specified redirection URIs for the client (conditional). MUST be absent if grant_types = client_credentials. Note: To support the RFC 8252 requirement that a native mobile app use a different redirection URI for every Authorization Server, the Certifier may include the special character * in the URI as a wildcard for a single path component or query parameter value, e.g. https://app.example.com/redirect/* or https://app.example.com/redirect?server=*. For URIs that contain literal asterisk characters, these characters should be URL-encoded as “%2A”; the Authorization Server MUST NOT interpret such a URL-encoded asterisk as a wildcard symbol. For a given Authorization Server, the client MUST register one or more complete redirection URIs with the Authorization Server that match this pattern; each registered redirect_uri MUST be fully specified and MUST NOT contain any wildcard symbols, even if the certification includes a wildcard symbol.

ip_allowed

An array of one or more strings of the form ip, ip1-ip2, or ip/CIDR (optional); origin IP to connect to token endpoint, e.g. ["198.51.100.0/24", "203.0.113.55"]

grant_types

as per RFC 7591; e.g. authorization_code, refresh_token, client_credentials (optional)

response_types

as per RFC 7591; code (omit for client_credentials) (optional)

scope

as per RFC 7591; optional

token_endpoint_auth_method

as per RFC 7591 (optional); RFC 7591 defines the values: none, client_secret_post, and client_secret_basic. The additional value private_key_jwt may also be used.

jwks

as per RFC 7591 (optional); locks this certification to a specific client key or keys. Note that jwks_uri MUST NOT be used. The client must prove possession of this key during registration and during authentication. To facilitate key rollover, binding using the sub claim URI is preferable to binding to a specific key.

 

Inclusion of one or more of the optional client application parameters indicates that the Certifier wishes to limit this certification to the Client app for certain software ID and/or version, certain redirection URIs, grant types, response types, and/or endpoint authorization methods. When the restriction parameter is an array, a client registration requesting a subset of the array values would also be permitted. For example if the grant_types array in a certification contains two grant types, a Client App registration requesting only one of those grant types would also match the restrictions of that certification.

2. The JOSE Header for the certification 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 Certifier’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 Certifier to digitally sign the certification.

The certification is signed and assembled using JWS compact serialization as per RFC 7515.

3. Example App Certification. Certain information about the example app and its developer has been validated by a third party:

{
   "iss": "http://identityprovider.example.org/certifications",
   "sub": "http://appdeveloper.example.com/apps/superapp/v1",
   "exp": 1562961473,
   "iat": 1531425447,
   "jti": "C0hlwc7r+3/t0qoK1G4G/B0hsyE7xR4PGiRfWQBZXY7e",
   "certification_issuer": "Some Sample Verification Company",
   "certification_name": "ID Validated Developer - Silver",
   "certification_logo": "https://identityprovider.example.org/images/id-verified.jpg",
   "certification_description": "The identity of the app developer has been verified at the Silver level. ",
   "certification_uri": "https://acme.example.org/programs/id-verify",
   "is_endorsement": false
   "developer_name": "AppDeveloper Company",
   "client_name": "SuperApp v.1",
   "redirect_uris": ["https://appdeveloper.example.com/apps/superapp/redirect"],
   "grant_types": ["authorization_code"],
   "response_types": ["code"]
}

For this example, the issuer is limiting this certification to the setting where the Client App requests registration using the client app parameters listed in the final four elements of the JWT.

4. Example “Endorsement” Certification. This example app has earned the “ACME Seal of Approval” certification and is endorsed by ACME for use by its members:

{
   "iss": "http://acme.example.org/certifications",
   "sub": "http://appdeveloper.example.com/apps/superapp/v1",
   "exp": 1562961473,
   "iat": 1531425447,
   "jti": "mQtC0hlwc7r+3/t0qoK1G4G/B0hsyE7xR4PGiRfWQBZX",
   "certification_issuer": "ACME",
   "certification_name": "Seal of Approval",
   "certification_logo": "https://acme.example.org/images/seal-of-approval.jpg",
   "certification_description": "ACME has evaluated this software and recommends it use by its members. ",
   "certification_uri": "https://acme.example.org/programs/acme-certification",
   "is_endorsement": true,
   "client_name": "AppDeveloper SuperApp v.1",
   "redirect_uris": ["https://appdeveloper.example.com/apps/redirect"],
   "grant_types": ["authorization_code", "refresh_token"],
   "response_types": ["code"]
}

For this example, the issuer is limiting this endorsement to the setting where the Client App requests registration using the client app parameters listed in the final four elements of the JWT.

5 References

Denniss, W., Bradley, J., “OAuth 2.0 for Native Apps”, BCP 212, RFC 8252, RFC Editor, October 2017.
Hardt, D., Ed., “The OAuth 2.0 Authorization Framework”, RFC 6749, RFC Editor, October 2012.
Jones, M., et al., “JSON Web Signature (JWS)”, RFC 7515, RFC Editor, May 2015.
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.
Sakimura, N, et al. “OpenID Connect Core 1.0 incorporating errata set 1”, The OpenID Foundation, November 2014.

6 Authors

Luis C. Maas III, EMR Direct

7 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.