AAI OIDC Profile

Abstract

This specification defines a profile for using the OpenID Connect protocol [OIDC-Core] to provide federated multilateral authorization infrastructure for greater interoperability between biomedical institutions sharing restricted datasets. (OpenID Connect is a simple identity layer, on top of the OAuth 2.0 protocol, that supports identity verification and the ability to obtain basic profile information about end users.) In particular, this specification defines tokens, endpoints, and flows that enable an OIDC provider (called a Broker) to provide Passports and Visas to downstream consumers called Passport Clearinghouses. Passports can then be used for authorization purposes by downstream systems.

Introduction
Notation and Conventions
Terminology
Relevant Specifications
Overview of Interactions
- Full Login and Token Exchange Interaction
- Flow of Assertions
Profile Requirements
GA4GH JWT Formats
Security Considerations
Specification Revision History

Introduction

This specification leverages OpenID Connect (OIDC) to authenticate researchers desiring to access clinical and genomic resources from data holders adhering to GA4GH standards. Beyond standard OIDC authentication, AAI enables data holders to obtain security-related attributes and authorizations of those researchers. The Data Use and Researcher Identity (DURI) Work Stream has developed a standard representation for researcher authorizations and attributes [Researcher-ID].

Technical Summary

At its core, the AAI specification defines cryptographically secure tokens for exchanging researcher attributes called Visas, and how various participants can interact to authenticate researchers, and obtain and validate Visas.

The main components identified in the specification are:

Visa Issuers, that cryptographically sign researcher attributes in the form of Visas.
Brokers, that authenticate researchers and provide Visas.
Clients, that perform actions that may require data access on behalf of researchers, relying on tokens issued by Brokers and Visa Issuers.
Passport Clearinghouses, that accept tokens containing or otherwise availing researcher visas for the purposes of enforcing access control.

Visa Tokens

Visas are used for securely transmitting authorizations or attributes of a researcher. Visas are tokens [JWT] signed by Visa Issuers and validated by Passport Clearinghouses.

Separation of Data Holders and Data Access Committees

It is a fairly common situation that, for a single dataset, the Data Access Committee (DAC) (the authority managing who has access to a dataset) is not the same party as the Data Holder (the organization that hosts the data, while respecting the DAC’s access policies).

For these situations, AAI is a standard mechanism for data holders to obtain and validate existing authorizations from DACs, by specifying the interactions between Visa Issuers, Brokers, and Passport Clearinghouses.

The AAI standard enables Data Holders and Visa Issuers to recognize and accept identities from multiple Brokers — allowing for a more federated approach. An organization can still use this specification with a single Broker and Visa Issuer, though they may find in that case that there are few benefits beyond standard OIDC.

Notation and Conventions

Terms defined in Terminology appear as capitalized links, e.g. Passport.

References to Relevant Specifications appear as bracket-enclosed links, e.g. [OIDC-Core].

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this specification are to be interpreted as described in [RFC2119].

Terminology

This specification inherits terminology from the OpenID Connect [OIDC-Core] and OAuth 2.0 Authorization Framework [RFC6749] specifications.

Broker – An OIDC Provider service that authenticates a user (potentially by relying on an Identity Provider), collects user’s Visas from internal and/or external Visa Issuers, and provides them to Passport Clearinghouses.

Claim – as defined by the JWT specification [RFC7519] – A piece of information asserted about a subject, represented as a name/value pair consisting of a claim name (a string) and a claim value (any JSON value).

Client – as discussed in the OAuth 2.0 Authorization Framework [RFC6749] specification

Data Holder – An organization that holds a specific set of data (or its copy) and respects and enforces the Data Access Committee’s (DAC’s) decisions on who can access it.

GA4GH Claim – A Claim as defined by a GA4GH documented technical standard that is making use of this AAI specification. Typically this is the ga4gh_passport_v1 or ga4gh_visa_v1 Claim for Passports v1.x. A GA4GH Claim is asserted by the entity that signed the token in which it is contained (not by GA4GH).

Identity Provider (IdP) – A service that provides to users an identity, authenticates it, and provides assertions to a Broker using standard protocols, such as OpenID Connect, SAML or other federation protocols. Examples: eduGAIN, Facebook, NIH eRA Commons. IdPs MAY be Visa Assertion Sources.

JWT – JSON Web Token as defined in [RFC7519]. A JWT contains a set of Claims.

Passport Clearinghouse – A service that consumes Visas and uses them to make an authorization decision based on inspecting them and allows access to a specific set of underlying resources in the target environment or platform. This abstraction allows for a variety of models for how systems consume these Visas in order to provide access to resources. Access can be granted by either issuing new access tokens for downstream services (i.e. the Passport Clearinghouse may act like an authorization server) or by providing access to the underlying resources directly (i.e. the Passport Clearinghouse may act like a resource server). Some Passport Clearinghouses may issue Passports that contain a new set or subset of Visas for downstream consumption.

Passport-Scoped Access Token – An OIDC access token with scope including the identifier ga4gh_passport_v1.

The access token MUST be a JWS-encoded JWT token containing openid and ga4gh_passport_v1 entries in the value of its scope Claim. It is RECOMMENDED that Passport-Scoped Access Tokens follow the JWT Profile for OAuth 2.0 Access Tokens specification [RFC9068].

Passport – A signed and verifiable JWT that contains Visas.

Passport Issuer – A service that creates and signs Passports.

Token Endpoint – a Broker’s implementation of the [OIDC-Core] Token Endpoint.

Token Exchange – The protocol defined in [RFC 8693] as an extension of OAuth 2.0 for exchanging access tokens for other tokens. A token exchange is performed by calling the Token Endpoint.

UserInfo Endpoint – a Broker’s implementation of the [OIDC-Core] UserInfo Endpoint.

Visa – A Visa encodes a Visa Assertion in compact and digitally signed format that can be passed as a URL-safe string value.

A Visa MUST be signed by a Visa Issuer. A Visa MAY be passed through various Brokers as needed while retaining the signature of the original Visa Issuer.

Visa Assertion – a piece of information about a user that is asserted by a Visa Assertion Source. It is then encoded by a Visa Issuer into a Visa.

Visa Assertion Source – the source organization of a Visa Assertion, which SHOULD include the organization associated with making the assertion, although it MAY optionally identify a sub-organization or a specific assignment within the organization that made the assertion.

This is NOT necessarily the organization that signs the Visa; it is the organization that has the authority to make the assertion on behalf of the user and is responsible for making and maintaining the assertion.

Visa Issuer – A service that signs Visas. This service:

may be a Broker itself
may be used by a Broker as part of collecting Visas.

Relevant Specifications

[IANA-JWT] – Standard JWT Claim name assignments, Internet Assigned Numbers Authority

[OIDC-Core] – OpenID Connect Core 1.0 (OIDC) – Authorization Code Flow will generate id_tokens and access_tokens from the Broker.

[OIDC-Client] – OpenID Connect Basic Client Implementer’s Guide 1.0

[OIDC-Discovery] – OpenID Connect Discovery 1.0

[Passport] – GA4GH Passport Specification, Data Use and Researcher Identity (DURI) Work Stream – Defines Passport and Visa formats.

[Researcher-ID] – GA4GH Passport Specification, Data Use and Researcher Identity (DURI) Work Stream – Defines researcher identities for GA4GH Passports and Visas.

[RFC2119] - Key words for use in RFCs to Indicate Requirement Levels

[RFC5246] - Transport Layer Security (TLS). Information passed among clients, applications, resource servers, Brokers, and Passport Clearinghouses MUST be protected using TLS.

[RFC6749] – The OAuth 2.0 Authorization Framework

[RFC6819] - Lodderstedt, T, McGloin, M., and P. Hunt, “OAuth 2.0 Threat Model and Security Considerations”, RFC 6819, January 2013.

[RFC7515] – JSON Web Signature (JWS) is the specific JWT to use for this spec.

[RFC7519] – JSON Web Token (JWT) – Specific implementations MAY extend this structure with their own service-specific JWT Claim names as top-level members of this JSON object. The JWTs specified here follow the JWS specification [RFC7515].

[RFC7636] – Proof Key for Code Exchange by OAuth Public Clients (PKCE)

[RFC7662] – J. Richer, Ed., “OAuth 2.0 Token Introspection”, October 2015

[RFC8693] - Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., and C. Mortimore, “OAuth 2.0 Token Exchange”, RFC 8693, DOI 10.17487/RFC8693, January 2020.

[RFC8725] - Sheffer, Y., Hardt, D., and M. Jones, “JSON Web Token Best Current Practices”, BCP 225, RFC 8725, DOI 10.17487/RFC8725, February 2020.

[RFC9068] – JWT Profile for OAuth 2.0 Access Tokens

Overview of Interactions

In the full token exchange flow recommended in this document, the client does not ever distribute the initial Passport-Scoped Access Token to other services. A token exchange operation is executed by the client, in exchange for a Passport JWT that may be used downstream to access resources. In this example flow, the Passport is included as authorization in the POST to a Clearinghouse that holds data.

Notable differences between this diagram and interaction specified in AAI/Passport v1.0:

The Passport Clearinghouse is no longer required to be a Client of the Broker
The Passport-Scoped Access Token is only ever shared between the Client and the Broker
An additional Token Exchange request is used to exchange the Passport-Scoped Access Token for a Passport Token, which can be sent to a Passport Clearinghouse. The Passport Token carries only the authorization in a user’s Visas, whereas the Passport-Scoped Access Token contains authorizations above and beyond the Visas.

Flow of Assertions

The above diagram shows how Visa Assertions flow from a Visa Assertion Source to a Passport Clearinghouse that uses them.

Implementations may introduce clients, services, and protocols to provide the mechanisms to move the data between the Visa Assertion Sources and the Broker. These mechanisms are unspecified by the scope of this specification except that they MUST adhere to security and privacy best practices, such as those outlined in this specification, in their handling of protocols, claims, tokens and related data. The flow between these components MAY be indirect or conversely services shown as being separate MAY be combined into one service. For example, some implementations MAY deploy one service that handles the responsibilities of both the Visa Issuer and the Broker.

Here are two non-normative examples illustrating two of many possible mechanisms:

Profile Requirements

Conformance for Clients/Applications

Clients are applications which want to access data on behalf of users, and are responsible for using the standard described here to do so securely.

OAuth defines two client types in section 2.1 of [RFC6749].
1. Confidential clients (which are able to keep the client secret secure, typically server-side web-applications) MUST implement OAuth2 Authorization Code Flow (see OIDC Basic Client Implementer’s Guide 1.0 [OIDC-Client]).
2. Public clients (single pages apps or mobile apps) SHOULD implement Authorization Code Flow with [PKCE].
Protection of Confidential Information
1. Sensitive information (e.g., including client secrets, authorization codes, id_tokens, access_tokens) MUST be passed over encrypted channels as per [OIDC-Client].
2. All responses that contain tokens, secrets, or other sensitive information MUST include the following HTTP response header fields and values as per [OIDC-Client].
  1. Cache-Control: no-cache, no-store
  2. Pragma: no-cache
Clients MUST provide protection against client attacks as outlined in [RFC6819].

Conformance for Brokers

Brokers operate downstream from IdPs or provide their own IdP service. They issue id_tokens and access_tokens (and potentially refresh tokens) for consumption within the GA4GH compliant environment.

Broker MUST be an OpenID Provider
1. Broker MUST conform to the OIDC Core specification [OIDC-Core].
2. Broker MUST support the OIDC Discovery specification [OIDC-Discovery] and provide proper metadata (i.e. must have a jwks_uri as required that’s reachable by a Passport Clearinghouse)
3. A Broker MUST issue Passport-Scoped Access Tokens (access_tokens).
  1. This document makes no specifications beyond those in [OIDC-Core].
4. Access tokens MUST be in JWS format
  1. Access tokens for GA4GH use MUST be a GA4GH JWT using Passport-Scoped Access Token format.
  2. Access tokens MUST NOT contain GA4GH Claims directly in the access token.
  3. Access tokens MAY contain additional non-GA4GH Claims directly in the access token.
Broker MUST support a Token Endpoint and UserInfo Endpoint.
1. Token Exchange at the Token Endpoint SHOULD be used for Visas in preference to the UserInfo Endpoint.
2. When presented with a valid Passport-scoped Access Token, the UserInfo endpoint MUST provide Visas as described in the section Visas provided by a Broker via UserInfo Endpoint.
Brokers operate downstream from IdPs or provide their own IdP service. They issue id_tokens and access_tokens (and potentially refresh tokens) for consumption within the GA4GH compliant environment.
Broker MAY support Token Exchange. If implemented, it MUST behave as described for passport issuance in Conformance For Passport Issuers.
Broker MUST provide protection against attacks as outlined in [RFC6819].
The user represented by the identity of the access token MUST have agreed to release claims related to the requested scopes as part of generating tokens. Brokers MUST adhere to section 3.1.2.4 of [OIDC-Core].
1. The user represented by a researcher identity MUST approve the release of these claims to relying parties with sufficient granularity to allow for responsible disclosure of information best practices as well as to meet privacy regulations that may be applicable within or between jurisdictions where the user’s identity will be used (e.g. GDPR for a European Union user).
2. If the user’s release agreement has been remembered as part of a user’s settings such that the user no longer needs to be prompted, then the user MUST have the ability to remove this setting (i.e. be prompted again in the future). If a feature is to bypass prompts by remembering settings is available, it MUST only be used as an opt-in feature with explicit controls available to the user.
3. A user’s withdrawal of this agreement does not need to apply to previously generated access tokens.
When a Broker acts as a Visa Issuer then it MUST adhere to the Conformance for Visa Issuers section of this specification.

When a Broker provides Visas from other Visa Issuers, it is providing them “as is” (i.e. it provides no additional assurance as to the quality, authenticity, or trustworthiness of the Claims from such tokens and any such assurances are made by the issuer of the Visa, i.e. the Visa Issuer).

Conformance for Visa Issuers

Visa Issuers issue signed JWTs (Visas) asserting facts about researchers, which may be used by Passport Clearinghouses to justify granting access to data. This specification defines the format of the Visas and endpoints Visa Issuers should have in order for Passport Clearinghouses to validate those Visas. This document does not specify how a Broker obtains Visas contained in a Passport or returned from the Userinfo Endpoint.

A Visa Issuer MUST provide one or more of the following types of Visas:
1. Visa Document Token – The Visa Issuer does not need to be an OIDC provider, and MAY provide tokens of this type without any revocation process.
  1. The token MUST conform with JWS format [RFC7515] requirements
  2. The token MUST be signed by a Visa Issuer.
  3. The JWS header MUST contain jku as specified by section 4.1.2 of [RFC7515], and MUST provide the corresponding endpoint to fetch the public key used to sign the Visa Document Token.
  4. The token is not treated as an access token, but validity checks outlined elsewhere in this specification still apply.
  5. Visas MUST be signed with a conformant signing algorithm.
  6. The scope Claim, if included, MUST NOT contain “openid” as a space-delimited substring of the scope JWT Claim.
  7. Payload Claims are specified in Visa Format in [Passport].
2. Visa Access Token – The Visa Issuer is providing an OIDC provider service and issues OIDC-compliant access tokens in a specific format that can be used as a Visa. Details are specified in the AAI Profile 1.0 specification.
The Visa Access Token is proposed for removal in a future version of the specification. Current and future specifications emphasize use of Visas embedded in a Passport, which are not access tokens. New implementations should issue Visas as Visa Document Tokens.
By signing a Visa, a Visa Issuer asserts that the Visa Assertions made available by the Visa were legitimately derived from their Visa Assertion Sources, and the content is presented and/or transformed without misrepresenting the original intent.

Conformance for Passport Issuers

Passport Issuers are used to package Visas into signed Passports. Passports are signed JWTs that use this format to contain Visas.

Passport Issuers MUST be Brokers.
Passports MUST be signed with a conformant signing algorithm.
Passports MAY be issued from a Token Endpoint using Token Exchange, with the following clarifications:
1. The Token Endpoint MAY also support other OAuth2 grant types.
2. Client authentication is REQUIRED (using OAuth2 client authentication in [RFC6749] is RECOMMENDED).
3. The requested_token_type parameter MUST be present with the value urn:ga4gh:params:oauth:token-type:passport.
4. The subject_token parameter value MUST be a valid Passport-Scoped Access Token.
5. The subject_token_type parameter value MUST be urn:ietf:params:oauth:token-type:access_token.
6. The Token Endpoint MAY accept or require any other optional parameters defined in [RFC8693].

Passport Issuing via Token Exchange (non-normative example)

Conformance for Passport Clearinghouses

Passport Clearinghouses consume Passports containing Visas in order to grant access to data.

Passport Clearinghouses MUST trust at least one Broker.
1. Passport Clearinghouses MAY trust more than one Broker
2. The Passport Clearinghouse is responsible for assessing the risk in choosing to trust a token from a Broker.
Passport Clearinghouses MUST process access tokens to access a Broker’s Token or UserInfo Endpoint to get access to Visas OR MUST process Passports directly.
1. For access token flows, Passport Clearinghouses MUST either check the validity of the access token or treat the access token as opaque.
2. For Passport flows, Passport Clearinghouses MUST check the validity of the Passport.
A Passport Clearinghouse service can be a Broker itself and would follow the Conformance For Brokers.
Passport Clearinghouses MUST provide protection against attacks as outlined in [RFC6819].
1. Section 5.1.6 of [RFC6819] states Ensure that client applications do not share tokens with 3rd parties. This profile provides a mechanism for Clearinghouses to consume access tokens from multiple brokers in a manner that does not involve 3rd parties. Client applications SHOULD take care to not spread the tokens to any other services that would be considered 3rd parties.
If making use of Visas:
1. The Passport Clearinghouse MUST validate that all JWT checks pass (such as the JWT hasn’t expired) as described elsewhere in this specification and the underlying OIDC specifications.
2. If making use of Visa Access Tokens:
  1. Token checks MUST be performed to ensure it complies with the access token specification.
  2. In addition to other validation checks, a Visa is considered invalid if it is more than 1 hour old (as per the iat Claim) AND Access Token Polling does not confirm that the token is still valid (e.g. provide a success status code).
3. If making use of Visa Document Tokens:
  1. Fetching the public keys using the jku is not required if a Passport Clearinghouse has received the keys for the given iss via a trusted, out-of-band process.
  2. If a Passport Clearinghouse is to use the jku URL to fetch the public keys to verify the signature, then it MUST verify that the jku is trusted for the given iss as part of the Passport Clearinghouse’s trusted issuer configuration. This check MUST be performed before calling the jku endpoint.
Access Token Polling: Clients MAY use access tokens, including Visas, to occasionally check which Visas are still valid at the associated Token or UserInfo Endpoint in order to establish whether the user still meets the access requirements.

This MUST NOT be done more than once per hour (excluding any optional retries) per Passport Clearinghouse. Any request retries MUST include exponential backoff delays based on best practices (e.g. include appropriate jitter). At a minimum, the client MUST stop checking once any of the following occurs:
1. The system can reasonably determine that authorization related to these Claims is no longer needed by the user. For example, all downstream cloud tasks have terminated and the related systems will no longer be using the access token nor any downstream tokens that were authorized by evaluating access requirements against Claims in the token.
2. The JWT access token has expired as per the exp field.
3. The client has detected that the user owning the identity or a system administrator has revoked the access token or a refresh token related to minting the access token.
4. The endpoint returns an HTTP status that is not retryable, e.g. HTTP status 400.
5. If the endpoint returns an updated set of Visas (this is an OPTIONAL feature of a Visa Issuer), then the Passport Clearinghouse MUST use the updated Visas and ignore the original GA4GH Claim values in the Visa Access Token. If the Passport Clearinghouse is unable to adjust for the updated Visas, then it MUST act as though the token was revoked.

GA4GH JWT Formats

This specification builds on the JWT format defined in [RFC7519]. A well-formed JWS-Encoded JSON Web Token (JWT) consists of three concatenated Base64url-encoded strings, separated by dots (.) The three sections are: header, payload and signature. These JWTs follow JWS [RFC7515] and utilize a number of standard JWT Claim names [IANA-JWT] as per the registration process. This profile is agnostic to the format of the id_token.

Passport-Scoped Access Token

This is the format for the token that is issued by Brokers, extending the definition of the [OIDC-Core] access token.

Header

{
 "typ": "<jwt-type-identifier>",
 "alg": "<algorithm-identifier>",
 "kid": "<key-identifier>"
}

typ: REQUIRED. Media type of the JWT. Value should be either JWT as recommended in [RFC7519] or at+jwt as required in [RFC9068] if the token format follows [RFC9068].
alg: REQUIRED. See Signing Algorithms.
kid: REQUIRED. Key ID, see section 4.1.4 of [RFC7515].

Payload

{
 "iss": "https://<issuer-website>/",
 "sub": "<subject-identifier>",
 "idp": "<short-idp-identifier>",
 "aud": [
  "<client-id1>",
  "<client-id2>" ...
 ],
 "iat": <seconds-since-epoch>,
 "exp": <seconds-since-epoch>,
 "jti": <token-identifier>,
 "scope": "openid ga4gh_passport_v1 <additional-scopes>",
 <additional claims>
}

iss: REQUIRED. MUST be able to be appended with .well-known/openid-configuration to get spec of Broker.
sub: REQUIRED. Authenticated user unique identifier.
idp: OPTIONAL. SHOULD contain the IDP the user used to auth with. This does not have to be unique and can be used just to help inform if that is what a Visa Issuer or Data Holder needs.
aud: OPTIONAL. If provided, it MUST contain the OAuth Client ID of the relying party.
iat: REQUIRED. Time issued.
exp: REQUIRED. Time expired.
jti: RECOMMENDED. a unique identifier for the token as per section 4.1.7 of [RFC7519]
scope: REQUIRED. Includes verified scopes. MUST include openid and ga4gh_passport_v1. The scope Claim is defined by section 4.2 of [RFC8693].
GA4GH Claims (ga4gh_passport_v1 or ga4gh_visa_v1): MUST NOT be included.
additional Claims: OPTIONAL. Any other additional non-GA4GH Claims are allowed. This specification does not dictate the format of other Claims.

Visas provided by a Broker via UserInfo Endpoint

The UserInfo Endpoint MAY use application/json or application/jwt response content type. It is RECOMMENDED that if desiring to return a JWT, a Token Endpoint supporting Token Exchange exists to do that and that the UserInfo Endpoint returns an application/json response. Only the GA4GH claims must be as prescribed here. Refer to [OIDC-Core] for more information.

The UserInfo response MUST include a ga4gh_passport_v1 Claim with a list of Visas if a Passport-Scoped Access Token was used for accessing it.

Passport Format

Passport Issuers MUST issue a Passport conforming to the requirements in this section when a Token Exchange with the requested_token_type=urn:ga4gh:params:oauth:token-type:passport is successfully performed (as described in the Conformance for Passport Issuers section).

Passports are defined as signed JWTs. The JWT specification [RFC7519] states that JWTs can be either signed and encoded using JWS Compact Serialization, or encrypted and encoded using JWE Compact Serialization. Passports are signed JWTs, which implies that they must be encoded using JWS Compact Serialization [RFC7515].