A collection of questions (and hopefully useful answers).
-
-
-
-
Background
-
-
Why Brokers?
-
-
We have found that there are widely used Identity Providers (IdP).
-These authentication mechanisms provide no authorization
-information (custom claims or scopes) but are ubiquitous for authentication at the institution level.
-The use of a Broker and Clearinghouse
-enables attaching information to the usual OIDC flow so that IdPs
-can be used with customized claims and scopes.
-
-
Here is a diagram of a single broker. This is one possible way to use this spec.
-
-
-
-
In this diagram, the Broker relies on a separate service for fetching visas, which
-stores assertions from multiple sources. The visa assertions are obtained by the
-Clearinghouse after a successful login, and used to determine a researcher’s
-access in the Clearinghouse system.
-
-
The Broker, Clearinghouse, and Visa Issuer may be separate services (as shown
-in this diagram), but in other configurations they may be run as parts of a single
-service, or as separate services run by single organization. Data holders and data
-controllers should explore their options to decide what best fits their needs.
-
-
Flows
-
-
The following sequence diagrams are included to help explain the intended flows
-documented in the accompanying specification.
-
-
What is the complete end to end flow using token exchange?
-
-
(last updated June 2022)
-
-
This flow is the preferred flow for v1.2+ of the specification.
-
-
The exchange flow does not ever distribute the initial Passport-Scoped Access Token beyond
-the client application. 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 DRS server. The token
-exchange has also specified known resources that will limit the audience
-of the Passport.
-
-
-
-
-
-
What is the complete end to end flow using /userinfo?
-
-
(last updated June 2022)
-
-
This flow is the flow for v1.0 implementations of the specification.
-
-
The flow as used by Elixir uses the initial Passport-Scoped Access Token as
-a token handed to downstream resource servers. These servers can use this token, in conjunction
-with a callback to the broker’s Userinfo Endpoint, to obtain the Passport content in
-JSON format.
-
-
-
-
-
-
Trust
-
-
What’s with all the signed passports and visas etc? Why so complex?
-
-
(last updated July 2022)
-
-
The practical operation of a loosely coupled
-federated ecosystem like GA4GH Passports requires establishing trust
-relationships between the participating entities (see
-OpenID Connect Federation
-for an interesting discussion of the properties of multilateral federations).
-
-
Any entity that is asked to make a decision about sharing data needs to have a priori
-made the decision “which other entities do I trust?”. In genomics, a single decision
-to allow data sharing might involve simultaneous trusting of
-multiple entities - human genomics is complex!
-
-
When presented with a
-Passport and Visas from entities that they trust - they can rely on the information (claims) provided
-to make data sharing decisions. If presented with information from entities that are
-untrusted - the content of the message is irrelevant as there is no basis on which to believe
-the content.
-
-
So we can see that trust is a crucial element of a working federation. How do we establish
-these trust relationships?
-
-
GA4GH Passports and Visas leverage the mechanisms
-present in JWT as used
-by the OIDC standards
-to cryptographically “sign” tokens containing claims. Signed tokens can be
-“verified” using public/private keys.
-
-
Why are the Visa claims formatted as JWTs inside the Passport?
-
-
(last updated August 2022)
-
-
If visas were not signed separately from a Passport, then Clearinghouses would require a high degree of confidence that
-the signing Passport Issuer or Broker was accurately representing the contents of Visas from the original Visa Issuer;
-there would be no mechanisms to prevent a malicious or defective Passport Issuer from misrepresenting Visa contents.
-By signing Visas separately from Passports, we prevent intermediate parties from tampering with Visa contents,
-allowing Clearinghouses to safely rely on Visa contents based on their trust relationship with the Visa Issuer.
-
-
What are the ways that key management is done in practice?
-
-
(last updated July 2022)
-
-
There are a variety of approaches that can be used for key
-management for Passports and Visas. We will first detail those that can be used for Passports
-and then discuss some extra wrinkles for Visas.
-
-
For this discussion we assume there is a concrete JWT from issuer https://issuer.example.org
-(possibly a Broker or a Visa Issuer).
-
-
My clearinghouse service ‘trusts’ the above issuer to help make data
-access decisions - and that trust is stated probably through some sort of explicit
-configuration. For our example, let’s imagine it has a hypothetical YAML configuration file
For our concrete example we say that it is a JSON file residing
-at https://issuer.example.org/public-keys.json (see
-RFC 7517 “JSON Web Key”).
-
-
IMPORTANTLY, for the secure use of this key management technique - the JKU
-MUST also be allow-listed as part of the configuration of OUR service.
-For example:
It is NEVER valid to even attempt to access a JKU from a JWT header - unless the URL
-is already known to belong to the given issuer. See
-“JWT Forgery via unvalidated jku parameter”.
-
-
To verify a JWT, the content of the JKU file is loaded and the kid is
-looked up in key set. The signature is validated using the public key found.
-
-
Although this configuration requires explicit registration of JKUs, the content
-of the key sets can allow the best practice of key rotation.
-
-
The content of the JKU file is designed to be cached aggressively, but as long as
-the file is fetched every few days/weeks, the set of keys
-can evolve/rotate.
-
-
-
-
Use the kid in the header of the JWT along with OIDC Discovery
-
-
The OpenID Connect Discovery
-protocol allows the use of the JWT issuer URL - in conjunction with a fetch
-of a /.well-known/openid-configuration - to look up the location of the public key set file. See
-OpenID Provider Metadata specification
-and the jwks_uri entry.
-
-
As with JKU - it is important that OIDC discovery is limited only to JWT issuer URLs that are
-in some way allow-listed. It is NEVER valid to perform discovery on an arbitrary issuer
-encountered in a JWT. Luckily, the concept of allow-listing issuers is already in some way
-inherent to the way trust relationships are established, and hence this allow list should
-already be present in the system.
-
-
Also as with JKU, the content of the discovery protocol and key sets can be cached
-aggressively. This means that the double step of the discovery protocol is not
-required on every JWT verification.
-
-
-
-
Exchange public keys beforehand with each trusted entity
-
-
This is an approach used by the NIH - and is appropriate if the number
-of trusted entities is small - such that the public keys of each trusted entity can be exchanged
-out of band (and their rotation/updating can also be managed out of band).
For any kid
-encountered in a JWT, the corresponding public key is already available for signature validation.
-
-
An even safer version of this approach is to perform
-the key verification across every public key you hold before even decoding the JWT JSON
-and then confirm the kid. This avoids ever even needing to JSON decode
-data from untrusted entities.
-
-
-
-
Requirement for JKU in Visas
-
-
When it comes to Visas, there is an extra wrinkle - unlike Brokers, Visa Issuers do not
-need to have been part of an OIDC flow. It is possible that the visa issuer URI is not
-even a locatable reference
-(e.g. urn:example.com:dac-world-visa-issuer).
-
-
Therefore the OIDC Discovery technique is not appropriate and hence the requirements
-of the AAI standard regarding the presence of JKUs.
-
-
-
-
Client Software
-
-
Use of GA4GH passport/visas in Single Page Apps (SPAs)
-
-
It is currently recommended that single page apps (SPA) such as a React/VueJS websites
-are NOT used for scenarios where the single page app code is solely responsible for the handling of
-genomic passports and tokens.
-
-
A SPA contains all the source of the application in public - and hence cannot
-possess a ‘client secret’ in an OIDC flow (the ‘client secret’ is used to prove the identity of the
-client software and is an important risk mitigation that prevents unconstrained
-use of an accidentally leaked/stolen token).
-
-
Techniques such as PKCE can be used to allow a SPA to participate in an OIDC flow - and this is not
-forbidden by the specification - but there
-are still unresolved questions about how SPAs can prove client identity in things like the token
-exchange that retrieves passports or other tokens.
-
-
Therefore if writing SPA websites for genomic data handling, it is recommended to use
-a backend set of services to execute OIDC flows and token exchanges (even if the rest of the SPA
-can operate purely on the front end). These
-backend service can hold secrets and hence can prove client identity - and the backend
-service can then securely participate in token exchange and retain tokens/passports.
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.
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.
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.
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.
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_v1Claim 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 scopeClaim.
-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 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.
-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:
-[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
-
-
Full Login and Token Exchange Interaction
-
-
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.
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.
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]).
-
-
-
Public clients (single pages apps or mobile apps) SHOULD implement Authorization Code Flow
- with [PKCE].
-
-
-
-
-
Protection of Confidential Information
-
-
-
-
Sensitive information (e.g., including client secrets,
-authorization codes, id_tokens, access_tokens) MUST be passed over
-encrypted channels as per [OIDC-Client].
-
-
-
All responses that contain tokens, secrets, or other sensitive
-information MUST include the following HTTP response header fields and
-values as per [OIDC-Client].
-
-
-
-
Cache-Control: no-cache, no-store
-
-
-
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
-
-
-
-
Broker MUST conform to the OIDC Core specification [OIDC-Core].
-
-
-
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)
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 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].
-
-
-
-
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).
-
-
-
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.
-
-
-
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:
-
-
-
-
-
-
-
-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.
-
-
-
The token MUST conform with JWS format [RFC7515] requirements
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.
-
The token is not treated as an access token, but validity
-checks outlined elsewhere in this specification still apply.
-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.
The subject_token_type parameter value MUST be urn:ietf:params:oauth:token-type:access_token.
-
-
-
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.
-
-
-
-
Passport Clearinghouses MAY trust more than one Broker
-
-
-
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.
-
-
-
-
For access token flows, Passport Clearinghouses MUST either check the validity of the access token or treat the access
-token as opaque.
-
-
-
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].
-
-
-
-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.
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.
Token checks MUST be performed to ensure it complies with the access
-token specification.
-
-
-
In addition to other validation checks, a Visa is considered
-invalid if it is more than 1 hour old (as per the iatClaim) AND
-Access Token Polling does not confirm that the token is still
-valid (e.g. provide a success status code).
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.
-
-
-
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:
-
-
-
-
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.
-
-
-
The JWT access token has expired as per the exp field.
-
-
-
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.
-
-
-
The endpoint returns an HTTP status that is not retryable, e.g. HTTP status 400.
-
-
-
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.
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.
scope: REQUIRED. Includes verified scopes. MUST include openid and ga4gh_passport_v1.
-The scopeClaim 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.
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].
-
-
Header
-
-
This spec prescribes the following JWS headers for Passports
-in addition to the guidelines established in [RFC7515]:
-
-
-
-typ: REQUIRED where the value must be vnd.ga4gh.passport+jwt for Passports.
-
-
-
Payload
-
-
Only the GA4GH claims must be as prescribed here. See the
-JWT specification [RFC7519] for more details.
sub: REQUIRED. Please note that [OIDC-Core] in its section
- Subject Identifier Types
- allows the use of PPIDs (Pairwise Pseudonymous Identifiers) providing different sub value to each client
- to preclude correlation of user’s activities at different clients. Even if a public identifier is used (same for all clients),
- the value of the sub claim of a Passports may be different from the values of sub claims of its Visas,
- and the values may need to be linked using LinkedIdentities
- visas.
-
-
-
aud: OPTIONAL.
-
-
-
iat: REQUIRED.
-
-
-
exp: REQUIRED.
-
-
-
jti: RECOMMENDED.
-
-
-
ga4gh_passport_v1: REQUIRED. An array of GA4GH Visas. May be empty if a
- user has no visas. See the [Passport] specification
- for more details on types of visas.
-
-
-
-
-
-
Signing Algorithms
-
-
JWTs MUST be issued with signatures using the ES256 or RS256 algorithm.
-Passport - A signed and verifiable JWT container for holding Visas.
-
-Passport Issuer - a service that creates and signs Passports.
-
-Token Endpoint – as defined by OIDC
-
-UserInfo Endpoint - as defined by OIDC
-
-
-
Introduced Token Exchange mechanism
-
-
The standardized mechanism for exchanging access tokens for other tokens defined in RFC 8693 OAuth 2.0 Token Exchange
-was added and used for releasing Passports.
-
-
Redefined Passport as a JWT containing Visas
-
-
In version 1.0, Passport was defined as ”GA4GH-compatible access token along with the Passport Claim that is returned from Passport Broker service endpoints using such an access token“,
-thus as a tuple of an access token and a list of Visas that can be obtained from UserInfo endpoint using the access token.
-
-
In version 1.2, Passport is defined as “a signed and verifiable JWT container for holding Visas“, thus as a token that can be passed among systems.
-
-
For backward compatibility with version 1.0, list of Visas is still provided as a claim value from UserInfo endpoint.
-
-
Defined Passport Issuer
-
-
A Passport Issuer is a service that creates and signs Passports.
-A Broker is an OIDC Provider service that collects Visas from Visa Issuers and provides them to Passport Clearinghouses.
-
-
Broker may optionally become a Passport Issuer by supporting Token Exchange for issuance of Passports.
-
-
Brokers conforming to version 1.0 are still compatible with version 1.2, because Token Exchange support is optional.
-
-
Added more signing algorithms
-
-
The version 1.0 allowed only RS256 algorithm for JWT signing.
-It is RSA-based algorithm using keys of size 2048 bits or larger and SHA-256 hash function.
-
-
The AAI specification version 1.2 allows also the ES256 algorithm which is
-ECDSA-based using P-256 elliptic curve and SHA-256 hash function.
-
-
Elliptic Curve Cryptography allows much shorter keys and signatures than RSA.
-A short Elliptic Curve key of around 256 bits provides the same security as a 3072 bit RSA key.
In version 1.0, all the mentioned JWTs (access tokens, visas) used in their typ (media type) header parameter
-the generic value JWT that marks a generic JWT.
-
-
In version 1.2, the typ header parameter is used to distinguish the various types of JWTs:
-
-
-
access tokens conforming to RFC9038
-use the value at+jwt
-
-
Passports use the value vnd.ga4gh.passport+jwt
-
-
Visas are recommended to use the value vnd.ga4gh.visa+jwt but allowed to use JWT
-for backward compatibility with version 1.0
-
-
-
Proposed Deprecations
-
-
Visa Access Tokens (also referred to as Embedded Access Tokens)
-
-
It is proposed that the 1.x versions of this specification will be the last to support
-Visa Access Tokens. New implementations should issue Visas
-as Visa Document Tokens.
For more information about this process, please refer to the Passport
-Custom Visa Types
-section of the Passport specification or reach out to maintainers
-on the Update Procedure page.
-
-
Custom Visa Registry
-
-
-
-
-
Date
-
Visa Name
-
Visa Type String
-
Short Description
-
Documentation Links
-
-
-
-
-
2020-06-30
-
NIH RAS Controlled Access
-
https://ras.nih.gov/visas/v1.1
-
Multiple controlled access authorizations encoded into a single visa with a more detailed list of attributes per authorization. Currently encodes a detailed list of attribrutes that come from NIH’s dbGaP visa source repository.
Work Stream Name: Data Use and Researcher Identity (DURI)
-
-
Product Name: GA4GH Passport
-
-
Product Description: This document provides the GA4GH technical
-specification for a GA4GH Passport to be
-consumed by Passport Clearinghouses in a
-standardized approach to determine whether or not data access should be
-granted. Additionally, the specification provides guidance on encoding
-specific use cases, including
-Visas for Registered Access as
-described in the “Registered access: authorizing data
-access” publication.
-Refer to the Overview for an introduction to how data
-objects and services defined in this specification fit together.
-
-
Table of Contents
-
-
-
toc
-
-
-
Terminology
-
-
Inherited Definitions
-
-
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
-“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be
-interpreted as described in RFC 2119.
-
-
This specification inherits terminology from the
-GA4GH AAI OIDC Profile
-specification, namely these terms:
The {sub, iss} pair of JWT standard claims (RFC7519 section
-4.1.1) that are
-included within a Visa that represents a
-given user (sub for subject) within the issuer’s (iss) system.
-
-
-
Visa Object
-
-
-
-
A claim value for
- the ga4gh_visa_v1 claim name. The claim value is a JSON object
- that provides claims that describe Visa’s
- properties that cannot be described by the standard JWT claims like sub or exp.
-
-
-
The ga4gh_visa_v1 claim is required to define a GA4GH v1 visa and
- contains controlled vocabulary as defined in this document. This object
- is not the entire visa, and there are other important claims within
- Visa JWTs that MAY be specific to its visa type as well as other
- JWT claims that are required as per this specification and the GA4GH
- AAI OIDC specification.
-
-
-
For claim definitions, refer to the Visa Object Claims section of this specification.
-
-
-
-
Visa Type
-
-
-
-
The “type” claim value of a Visa Object
-that represents the semantics of the assertion and informs all parties
-involved in the authoring or handling the assertion how to interpret
-other Visa Object Claims.
-
-
-
For example, a Visa Type of “AffiliationAndRole” per the
-Standard Visa Type Definitions
-specifies the semantics of the Visa as well as the
-expected encoding of the “value” claim value for this purpose.
-
-
-
In addition to Standard Visa Type Definitions, there
-MAY also be Visas with Custom Visa Types.
-
-
-
-
Overview
-
-
Please see the Flow of Assertions
-section in the GA4GH AAI OIDC Profile specification for an overview of interaction among the specified parties.
-
-
General Requirements
-
-
-
-
Each Visa may have a different expiry.
-
-
-
Visas MUST have an indication of
-which organization made the Visa Assertion (i.e. the
-“source” claim), but Visas do not generally indicate
-individual persons involved in making the assertion (i.e. who assigned/signed
-the assertion) as detailed identity information is not needed to make an
-access decision.
-
-
-
Additional information about identity
-that is not needed to make an access decision SHOULD not be included in the
-Visas. Identity description, encoding audit details, other data
-for non-access purposes are not the intent of these Visas,
-and must be handled via other means beyond the scope of this specification
-should they be needed for entities and systems with sufficient authority to
-process such information.
If the Broker is the Visa Issuer,
-it MUST set the iss to itself and sign such Visas with an
-appropriate private key as described in the GA4GH AAI OIDC specification.
-
-
-
Visas are designed for machine
-interpretation only in order to make an access decision and is a non-goal to
-support rich user interface requirements nor do these claims fully encode the
-audit trail.
-
-
-
A Visa Object MAY
-contain the “conditions” claim to restrict the Visa
-to only be valid when the conditions are met.
-
-
-
For example, an identity can have several affiliations and a
-Visa with type “ControlledAccessGrants” MAY establish a
-dependency on one of them being present in the Passport by using the
-conditions claim.
-
-
-
-
Processing a Passport within a Passport Clearinghouse MUST abide by the following:
-
-
-
-
Passport Clearinghouses MUST reject all requests that include Passports
-that fail the necessary checks as described in the GA4GH AAI OIDC specification.
-
-
-
A Passport Clearinghouse MUST ignore all Visas it does not
-need to process a particular request.
-
-
-
Passport Clearinghouses MUST ignore Passports and Visas
-unless:
The Passport Clearinghouse can rely on a trusted service that
-provides sufficient trust of any of the Broker,
-Visa Assertion Source and/or Visa Issuer
-such that the Passport Clearinghouse can establish trust of all
-three such parties.
-
-
-
-
-
When combining Visas with multiple Visa Identities for the purposes of evaluating
-authorization, a Passport Clearinghouse MUST check the
-LinkedIdentities Visas by trusted issuers
-and ensure that trusted sources have asserted that these
-Visa Identities represent the same end user.
-
-
-
-
-
-
Support for User Interfaces
-
-
(e.g. mapping a URI string to a human-readable description for a user
-interface.)
-
-
For example, a user interface mapping of
-“https://doi.org/10.1038/s41431-018-0219-y” to a human readable description
-such as “this person is a bona fide researcher as described by the ‘Registered
-access: authorizing data access’ publication”.
-
-
It is a non-goal for this specification to consider the processes and data for
-the purpose of supporting user interfaces.
Visa Issuers, Brokers, and Passport Clearinghouses
-MUST conform to the
-GA4GH AAI Specification
-requirements for Visas in their use of Visas.
-
-
-
Validation, as outlined elsewhere in this specification and the
-GA4GH AAI Specification, MUST be performed before Visas are
-used for identity or authorization.
-
-
-
-
Visa Format
-
-
Visas are signed JWTs encoded into strings using JWS Compact Serialization.
-When decoded, their structure is:
The standard JWT payload claims iss, sub, iat, exp are all REQUIRED.
-
-
One of scope or jku MUST be present as described in
-Conformance for Visa Issuers
-within the AAI specification.
-
-
Claims within the ga4gh_visa_v1Visa Object are as described
-in the Visa Object Claims section of this specification.
-
-
“typ”
-
-
-
OPTIONAL. The value of the typ header claim is RECOMMENDED to be vnd.ga4gh.visa+jwt
-for Visa Document Token Format
-visas. The value JWT marking general JWTs MAY also be used.
The typ header claim is specified by section 5.1 of JWT RFC
-to contain media type of the JWT for disambiguation.
-The full recommended media type for GA4GH Visas is application/vnd.ga4gh.visa+jwt where the subtype consist of
-the “vendor tree” prefix vnd, the “producer name” ga4gh, and the “product designation” visa
-followed by the +jwt structured syntax suffix (specified in section 3.2
-and section 4.2.8 of RFC 6838).
-Then section 4.1.9 of JWS RFC recommends to omit the prefix
-application/ to keep messages compact.
-
-
-
“alg”
-
-
-
REQUIRED.The section Signing Algorithms
-in the AAI specification lists possible algorithms used in the alg header claim.
-
-
-
“exp”
-
-
-
-
REQUIRED. Generally, it is seconds since unix epoch of when the
-Visa Assertion Source
-requires such an assertion to be no longer valid. A Visa
-Assertion Source MAY choose to make an assertion very long lived.
-However, a Visa Issuer MAY
-choose an earlier timestamp in order to limit the assertion’s duration
-within downstream Passport Clearinghouses.
-
-
-
Access is NOT necessarily removed by the exp timestamp. Instead,
-this timestamp may be viewed as a cut-off after which no new access
-will be granted and action to remove any existing access may
-commence anytime shortly after this cut-off period.
Although standard claims within a Visa Object
-are defined in this section, other claims MAY exist within the object
-and should be ignored by any Passport Clearinghouse that is not familiar
-with the use of such claims. Claim names are reserved for definition by
-GA4GH (or a body it elects).
REQUIRED. Seconds since unix epoch that represents when the
- Visa Assertion Source made the claim.
-
-
-
Note that the standard iat JWT claim on the Visa reflects the timestamp
- of when the Visa was minted whereas the asserted claim
- reflects when the Visa Assertion Source made the assertion.
-
-
-
asserted MAY be used by a Passport Clearinghouse as described in the
- Visa Expiry section.
-
-
-
If a Visa Assertion repository does not include enough
- information to construct an asserted timestamp, a Visa Issuer MAY use a recent timestamp (for
- example, the current timestamp) if the Visa Assertion repository
- is kept up to date such that the Visa Issuer can ensure that
- the assertion is valid at or near the time of minting the Visa.
- However, generally it is RECOMMENDED to have the
- Visa Assertion repository provide more accurate asserted information.
-
-
-
-
“value”
-
-
-
-
REQUIRED. A string that represents any of the scope, process, identifier and
- version of the assertion. The format of the string can vary by the
- Visa Type.
-
-
-
For example, value: "https://doi.org/10.1038/s41431-018-0219-y" when type: "ResearcherStatus"
- represents a version of Registered Access Bona Fide
- researcher status. Note that Registered Access requires more than one
- Visa as outlined in the Registered
- Access section.
-
-
-
For the purposes of enforcing its policies for access, a Passport
- Clearinghouse evaluating the value claim MUST:
-
-
-
-
Validate URL strings as per the URL Claim
-requirements if the Visa Type definition indicates the value
-is a URL (as indicated by the type claim).
-
-
-
Value strings MUST be full string case-sensitive matches
-unless the Visa Type defines a safe and reliable format for
-partitioning the value into substrings and matching on the various
-substrings. For example, the standard
-AffiliationAndRole Visa Type can be
-reliably partitioned by splitting the string at the first “@” sign if such
-exists, or otherwise producing an error (i.e. denying permission).
-
-
-
-
-
-
“source”
-
-
-
-
REQUIRED. A URL Claim that provides at a minimum the
-organization that made the assertion. If there is no organization
-making the assertion, the source claim value MUST be set to
-“https://no.organization”.
-
-
-
For complex organizations that may require more specific information
-regarding which part of the organization made the assertion, this claim MAY
-also encode some substructure to the organization that represents the
-origin of the authority of the assertion. When this approach is chosen, then:
-
-
-
-
The additional substructure MUST only encode the sub-organization or
-department but no other details or variables that would make it
-difficult to enumerate the full set of possible values or cause Passport
-Clearinghouses confusion about which URLs to whitelist.
-
-
-
The additional information SHOULD be encoded into the subdomain or path
-whenever possible and SHOULD generally avoid the use of query parameters
-or anchors to represent the sub-organization.
-
-
-
Some organizations MAY wish to attribute the source to a particular
-Data Access Committee (DAC), especially for
-ControlledAccessGrants Visa Types.
-For example:
could represent one particular logical “DAC” organization as referred
-to by the EBI organization, and could be maintained by the EBI as a
-permanent identifier for this DAC.
-
-
-
-
-
-
“conditions”
-
-
-
-
OPTIONAL. A set of conditions on a
-Visa Object indicates that the Visa is
-only valid if the clauses of the conditions match other Visas
-elsewhere in the Passport and such content is both valid
-(e.g. hasn’t expired; signature of Visa has been verified against
-the public key; etc.) and if such content is accepted by the Passport
-Clearinghouse (e.g. the issuer is trusted; the source claim meets any
-policy criteria that has been established, etc.).
-
-
-
A Passport Clearinghouse MUST always check for the presence of
-the conditions claim and if present it MUST only accept the
-Visa if it can confirm that the conditions have been met.
-
-
-
Although it is RECOMMENDED to always implement full condition checking
-capabilities as described in this section, if a Passport Clearinghouse will be
-deployed for a more limited purpose where it is not expected to ever receive
-Visas with conditions, then such a Passport Clearinghouse MAY choose to
-not implement full condition checking. However, even in this case it MUST
-still check for the presence of the conditions claim on Visa
-Objects and reject (ignore) any Visas that contain a non-empty
-conditions claim value. Likewise if not all condition matching algorithms
-are implemented, it MUST reject any Visas that contain patterns
-that are not supported.
The conditions value is a two-nested-lists structure in Disjunctive
-Normal Form:
-
-
-
-
The outer level list is a set of OR clauses
-
-
-
The inner level list is a set of AND clauses that contain “Condition
-Clauses”
-
-
-
A Condition Clause MUST specify a “type” claim with a value as a
-Visa Type plus it MUST include at least one other claim with a
-name that matches a valid Visa Object claim name.
-
-
-
The values of Condition Clause claims MUST have a string prefix followed
-by a colon and then string suffix, except for type where it MUST be
-assumed to be “const” and is not specified.
-
-
-
-
If prefix is “const”, then suffix MUST use case sensitive full string
-matching.
-
-
-
If prefix is “pattern”, then suffix MUST use full string Pattern
-Matching to match input.
-
-
-
If prefix is “split_pattern”, then the full suffix MUST use full
-string Pattern Matching on each full
-substring from splitting the corresponding Visa Object
-claim value that is being compared by the “;” character. If any one
-full substring matches, then the Condition Clause claim has found a
-match. “split_pattern” SHOULD only be used on claims where the
-Visa Type has been specified in a format that makes splitting
-on this character to be reliable, such as URI-encoded substrings with
-semicolon separators (see LinkedIdentities as an
-example).
-
-
-
For example: a Condition Clause claim value of
-“split_pattern:123,https:%2F%2Fexample?.org” will match a
-Visa Object claim value of
-“001,https::%2F%2Fexample1.org;123,https::%2F%2Fexample2.org;456,https::%2F%2Fexample3.org”
-because this comparison value will be split into:
-
and the second entry in that list is a match using the Pattern
-Matching definition with 123,https:%2F%2Fexample?.org as the
-pattern to use.
-
-
-
-
-
If prefix is unknown or unsupported, then the Condition Clause must
-fail to match.
-
-
-
-
-
-
-
Condition Clause claims are restricted to only Visa Object Claims
-(e.g. value, source, etc.) with string value
-definitions.
-
-
-
-
It MUST NOT include conditions (i.e. a condition cannot be placed on
-another condition)
-
-
-
It MUST NOT contain a timestamp claim such as asserted.
-
-
-
-
-
The Passport Clearinghouse MUST verify that for each Condition Clause
-present, there exists a valid single corresponding
-Visa Object such that:
-
-
-
-
Checking the correctness of the Condition Clause MUST be performed first.
-For example, a type claim MUST be present.
-
-
-
Ignore Visa Objects that have the conditions claim present.
-This will avoid deep nesting of condition evaluation (i.e. avoid condition
-loops, stack overflows, etc).
-
-
-
A Condition Clause claim matches when the <match-type> algorithm
-matches a corresponding Visa Object’s claim in the Passport.
-
-
-
Visa Object Claims that are not specified
-in the Condition Clause are not required to match (i.e. any value will be
-accepted within that claim, including if the claim is not present in the
-Visa Object).
-
-
-
All Condition Clause claims that are specified within one Condition
-Clause MUST match the same Visa Object in the Passport.
OR, alternative acceptance is matching just one Visa:
-
-
-
-
type = “AffilationAndRole”; AND
-
-
-
value starts with “faculty\@”; AND
-
-
-
source = “https://visas.elixir.org”; AND
-
-
-
by = “system”
-
-
-
-
-
-
-
-
Pattern Matching
-
-
-
-
Pattern Matching is only for use as specified by
-“conditions”.
-
-
-
MUST Use full string case-sensitive character pattern comparison.
-
-
-
MUST support special meaning characters as the specification of patterns:
-
-
-
-
? : A <question-mark> is a pattern that SHALL match any single
-character.
-
-
-
* : An <asterisk> is a pattern that SHALL match multiple characters:
-
-
-
-
Match any string, including the empty string and null string.
-
-
-
Match the greatest possible number of characters that still allows
-the remainder of the pattern to match the string.
-
-
-
-
-
-
-
There is no escape character for special characters such as patterns.
-? is always treated as the <question-mark> pattern and * is always
-treated as the <asterisk> pattern.
-
-
-
A method evaluating a pattern on a string of input SHALL return a true if
-the input has found one or more possible ways to match or false if it does
-not.
-
-
-
-
“by”
-
-
-
-
OPTIONAL. The level or type of authority within the “source” organization
-of the assertion.
-
-
-
A Passport Clearinghouse MAY use this claim as part of an authorization
-decision based on the policies that it enforces.
-
-
-
Fixed vocabulary values for this claim are:
-
-
-
-
self: The Visa Identity for which the assertion is being made
-and the person who made the assertion is the same person.
-
-
-
peer: A person at the source organization has made this assertion on
-behalf of the Visa Identity’s person, and the person who is making
-the assertion has the same Visa Type and value in that source
-organization. The source claim represents the peer’s
-organization that is making the assertion, which is not necessarily
-the same organization as the Visa Identity’s organization.
-
-
-
system: The source organization’s information system has made the
-assertion based on system data or metadata that it stores.
-
-
-
so: The person (also known as “signing official”) making the assertion
-within the source organization possesses direct authority (as part of
-their formal duties) to bind the organization to their assertion that the
-Visa Identity did possess such authority at the time the
-assertion was made.
-
-
-
dac: A Data Access Committee or other authority that is responsible
-as a grantee decision-maker for the given value and source claims
-pair.
-
-
-
-
-
If this claim is not provided, then none of the above values can be assumed
-as the level or type of authority and the authority MUST be assumed to be
-“unknown”. Any policy expecting a specific value as per the list above MUST
-fail to accept an “unknown” value.
For the purposes of evaluating access, the URL MUST be treated as a simple
-unique persistent string identifier.
-
-
-
The URL is a canonical identifier and as such it is important that Passport
-Clearinghouses MUST match this identifier consistently using a
-case-sensitive full string comparison.
-
-
-
-
If TLS is available on the resource, then its persistent identifier URL
-SHOULD use the “https” scheme even if the resource will also resolve using
-the “http” scheme.
-
-
-
When the URL is being used to represent an organization or a well defined
-child organization within a “source” claim, it is RECOMMENDED
-to use a URL as a persistent organizational ontology identifier, whether
-managed directly or by a third-party service such as
-GRID when reasonable to do so.
-
-
-
-
-
The URL SHOULD also be as short as reasonably possible while avoiding
-collisions, and MUST NOT exceed 255 characters.
-
-
-
The URL MUST NOT be fetched as part of policy evaluation when making an
-access decision. For policy evaluation, it is considered an opaque string.
-
-
-
URLs SHOULD resolve to a human readable document for a policy maker to
-reason about.
-
-
-
-
GA4GH Standard Visa Type Definitions
-
-
Note: in addition to these GA4GH standard Visa Types, there is also
-the ability to for a Visa Issuer to encode Custom Visa Types.
-
-
AffiliationAndRole
-
-
-
-
The Visa Identity’s role within the identity’s affiliated institution
-as specified by one of the following:
-
-
-
-
eduPersonScopedAffiliation
-attributed value of: faculty, student, or member.
-This term is defined by eduPerson by the affiliated organization
-(organization after the \@-sign).
-
-
-
-
Example: “faculty\@cam.ac.uk”
-
-
-
Note: based on the eduPerson specification, it is possible that
-institutions use a different definition for the meaning of “faculty”
-ranging from “someone who does research”, to “someone who teaches”,
-to “someone in education that works with students”.
-
-
-
-
-
A custom role that includes a namespace prefix followed by a dot (“.”)
-where implementers introducing a new custom role MUST coordinate
-with GA4GH (or a body it elects) to align custom role use cases in order
-to maximize interoperability and avoid fragmentation across
-implementations.
-
-
-
-
Non-normative example: “ega.researcher\@med.stanford.edu” where “ega”
-is the namespace and “researcher” is the custom role within that
-namespace.
-
-
-
Custom roles and their prefixes MUST be limited to characters: a-z,
-dash (“-“), underscore (“_”), digits (0-9). Custom roles and prefixes
-MUST start with characters a-z.
-
-
-
-
-
-
-
If there is no affiliated institution associated with a given assertion, the
-affiliation portion of AffliationAndRole MUST be set to “no.organization”.
AffiliationAndRole can be safely partitioned into a {role, affiliation} pair
-by splitting the value string at the first “@” sign.
-
-
-
-
AcceptedTermsAndPolicies
-
-
-
-
The Visa Identity or the
- “source” organization has acknowledged the specific terms,
- policies, and conditions (or meet particular criteria) as indicated by the
- value claim.
-
-
-
The value claim value conforms to URL Claim format.
-
-
-
The URL SHOULD resolve to a public-facing, human readable web page that
- describe the terms and policies.
-
-
-
Example value: "https://doi.org/10.1038/s41431-018-0219-y"
- acknowledges ethics compliance for a particular version of Registered
- Access. Note that more
- Visas are needed to meet the requirements for Registered
- Access status.
The person has been acknowledged to be a researcher of a particular type or
-standard.
-
-
-
The value claim conforms to URL Claim format, and it
-indicates the minimum standard and/or type of researcher that describes
-the person represented by the given Visa Identity.
-
-
-
The URL SHOULD resolve to a human readable web page that describes the
-process that has been followed and the qualifications this person has met.
-
-
-
Example value: "https://doi.org/10.1038/s41431-018-0219-y"
-acknowledges a particular version of the registration process as needed
-for Registered Access Bona Fide researcher
-status. Note that more Visas are needed to meet
-the requirements for Registered Access status.
-
-
-
-
ControlledAccessGrants
-
-
-
-
A dataset or other object for which controlled access has been granted to
-this Visa Identity.
The identity as indicated by the {“sub”, “iss”} pair (aka
-Visa Identity) of the
-Visa is the same as the identity or identities listed
-in the “value” claim.
-
-
-
The “value” claim format is a semicolon-delimited list of
-“<uri-encoded-sub>,<uri-encoded-iss>” entries with no added whitespace
-between entries.
-
-
-
-
The “sub” and “iss” that are used to encode the “value” claim do
-not need to conform to URL Claim
-requirements since they must match the corresponding Visa
-“sub” and “iss” claims that may be issued.
-
-
-
By URI encoding (RFC 3986) the
-“iss”, special characters (such as “,” and “;”) are encoded within the URL
-without causing parsing conflicts.
The “source” claim refers to the Visa Assertion
-Source that is making the assertion. This is
-typically the same organization as the Visa
-Issuer (iss) that signs the Visa, but the
-source MAY also refer to another Visa Assertion Source depending
-on which organization collected the information.
-
-
-
As a non-normative example, if a policy needs 3 Visas and
-there are three Visas that meet the criteria on one Passport
-but they use 3 different sub values (“1234”, “567”, “890123”), then
-any of the following, if from a trusted issuers and sources, may
-allow these Visas to be combined (shown with JSON payload only
-and without the REQUIRED URI-encoding in order to improve readability of
-the example).
In addition to the
-GA4GH Standard Visa Type Definitions,
-Visas MAY be added using custom type names so long as the
-encoding of these Visas will abide by the requirements described
-elsewhere in this specification.
-
-
-
Custom Visa Types MUST limit personally identifiable information
-to only that which is necessary to provide authorization.
-
-
-
The custom type name MUST follow the format prescribed in the
-URL Claims section of the specification.
-
-
-
Implementers introducing a new custom type name MUST coordinate with the
-GA4GH (or a body it elects) to align custom type use cases to maximize
-interoperability and avoid unnecessary fragmentation across implementations.
-
-
-
-
To review the custom visa registry, including any visa descriptions,
-examples and links that have been provided through proposals using this
-process, visit the Custom Visa Type Registry
-page.
-
-
-
Documentation on encoding and interpreting the claims SHOULD
-be provided as part of the proposal and for inclusion in a public custom
-visa type registry maintained by GA4GH. This documentation SHOULD also include
-examples and links to relevant documentation and/or open source software
-that MAY be available.
-
-
-
-
-
Passport Clearinghouses MUST ignore all Visas containing a custom
-type name that they do not support.
-
-
-
Non-normative example custom type name:
-type: "https://example.org/passportVisaTypes/researcherStudies".
-
-
-
-
Encoding Use Cases
-
-
Use cases include, but are not limited to the following:
-
-
Registered Access
-
-
-
-
To meet the requirements of Registered Access to data as defined by
-publication https://doi.org/10.1038/s41431-018-0219-y as a specific
-version of Registered Access, a user needs to have all of the following
-Visas:
-
-
-
-
Meeting the ethics requirements is represented by:
If other versions of Registered Access are introduced, then the value
-claims for AcceptedTermsAndPolicies as well as ResearcherStatus MAY
-refer to the document or publication or sections thereof to act as the
-permanent identifiers for such versions of Registered Access.
-
-
-
The Passport Clearinghouse (e.g. to
-authorize a registered access beacon) needs to evaluate the
-multiple Visas listed above to ensure their values match
-before granting access.
-
-
-
If combining Visas from multiple
-Visa Identities, the Passport
-Clearinghouse MUST also check the
-LinkedIdentities Visas and
-determine if combining these identities came from a trusted
-Visa Issuer.
-
-
-
-
-
Controlled Access
-
-
-
-
Controlled Access to data utilizes the following Visa Types:
-
-
-
-
MUST utilize one or more
-ControlledAccessGrants and/or custom
-controlled access visa type(s) for permissions associated with specific
-data or datasets. There MAY be more standard visa types introduced for
-encoding controlled access in future revisions of the Passport
-specification.
-
-
-
MAY utilize the conditions claim on
-“ControlledAccessGrants” to cause such a grant to require
-a Visa from a trusted Visa Assertion Source to
-assert that the identity has a role within a specific organization.
-This can be achieved by using the
-AffiliationAndRole Visa Type on
-the conditions.
-
-
-
MAY utilize any other valid Visa Type or conditions claim
-that may be required to meet controlled access policies.
-
-
-
-
-
-
Visa Expiry
-
-
In addition to any other policy restrictions that a Passport Clearinghouse
-may enforce, Passport Clearinghouses that provide access for a given
-duration provided by the user (excluding any revocation policies) MUST
-enforce one of the following algorithm options to ensure that Visa
-expiry is accounted for:
-
-
Option A: use the following algorithm to determine if the Visa
-is valid for the entire duration of the requested duration:
requestedTTL represents the duration for which access is being requested.
-Alternatively a solution may choose to have a stronger revocation policy
-instead of requiring such a duration.
-
-
-
maxAuthzTTL represents any additional expiry policy that the Passport
-Clearinghouse may choose to enforce. If this is not needed, it can
-effectively ignored by using a large number of years or otherwise have
-token.ga4gh_visa_v1.asserted+maxAuthzTTL removed and simplify the right
-hand side expression accordingly.
-
-
-
-
Option B: if tokens are sufficiently short lived and/or the authorization
-system has an advanced revocation scheme that does not need to specify a
-maxAuthzTTL as per Option A, then the check can be simplified:
-
-
now()+accessTokenTTL < token.exp
-
-
-
Where:
-
-
-
-
accessTokenTTL represents the duration for which an access token will be
-accepted and is bounded by the next refresh token cycle or Access Token
-Polling
-cycle or any larger propagation delay before access is revoked, which
-needs to be assessed based on the revocation model.
-
-
-
For example, accessTokenTTL may be set to one hour, after which time
-more access tokens may be minted using a corresponding refresh token if
-it has not yet been revoked.
-
-
-
-
-
Expiry when using multiple Visas: if multiple Visas are
-required as part of an access policy evaluation, then the expiry to be used MUST
-be the minimum expiry timestamp, as calculated by the appropriate option above,
-across all Visas (token set) that were accepted as part of evaluating
-the access policy.
Visa Objects have an “asserted” claim to allow
-downstream policies to limit the life, if needed, of how long assertions
-will be accepted for use with access and refresh tokens.
-
-
-
Visas have an “exp” claim to allow Brokers and
-Passport Clearinghouses to limit the duration of access.
-
-
-
-
At a minimum, these Visa Claims MUST be checked by all Passport
-Clearinghouses and systems MUST be in place to begin to take action to remove access
-by the expiry timestamp or shortly thereafter. Propagation of these permission
-changes may also require some reasonable delay.
-
-
Systems employing Visas MUST provide mechanisms to
-limit the life of access, and specifically MUST conform to the GA4GH AAI
-Specification requirements in this regard. Systems utilizing Visas MAY also
-employ other mechanisms outlined in the GA4GH AAI Specification, such as Access
-Token Polling
-if the Visa is encoded as a Visa Access Token.
-
-
Example Passport Claim
-
-
This non-normative example illustrates a Passport Claim
-that has Visas representing Registered Access bona fide researcher
-status along with other Visas for access to specific Controlled Access
-data. The Visa Types for this example are:
-
-
-
-
AffiliationAndRole: The person is a member of faculty at Stanford
-University as asserted by a Signing Official at Stanford.
-
-
-
ControlledAccessGrants: The person has approved access by the DAC at the
-Example Institute for datasets 710 and approval for dataset 432 for a dataset
-from EGA.
-
-
-
-
In this example, assume dataset 710 does not have any
-“conditions” based on the
-AffiliationAndRole because the system that is asserting the assertion has an
-out of band process to check the researcher’s affiliation and role and
-withdraw the dataset 710 claim automatically, hence it does not need the
-conditions claim to accomplish this.
-
-
-
In this example, assume that dataset 432 does not use an out of band
-mechanism to check affiliation and role, so it makes use of the
-“conditions” claim mechanism to
-enforce the affiliation and role. The dataset 432 assertion is only valid if
-accompanied with a valid AffiliationAndRole claim for
-“faculty\@med.stanford.edu”.
-
-
-
-
-
AcceptedTermsAndPolicies: The person has accepted the Ethics terms and
-conditions as defined by Registered Access. They took this action
-themselves.
-
-
-
ResearcherStatus: A Signing Official at Stanford Medicine has asserted
-that this person is a bona fide researcher as defined by the Registered
-Access model.
-
-
-
LinkedIdentities: A Broker at example3.org has provided
-software functionality to allow a user to link their own accounts together.
-After the user has successfully logged into the two accounts and passed all
-auth challenges, the Broker added the
-LinkedIdentities Visa for those two accounts:
-(1) “10001” from example1.org, and (2) “abcd” from example2.org.
-Since the Broker is signing the “LinkedIdentities”
-Visa, it is acting as the Visa Issuer.
-
-
-
-
Normally a Passport like this would include Visa
-Format entries as JWS Compact Serialization strings,
-however this example shows the result after the Visas have been
-unencoded into JSON (and reduced to include only the payload) to be more
-reader-friendly.
-
-
-
-
diff --git a/driver-project-usage/AAI/AbstractAAI.drawio.svg b/driver-project-usage/AAI/AbstractAAI.drawio.svg
deleted file mode 100644
index 67b2770..0000000
--- a/driver-project-usage/AAI/AbstractAAI.drawio.svg
+++ /dev/null
@@ -1,4 +0,0 @@
-
-
-
-
\ No newline at end of file
diff --git a/driver-project-usage/AAI/GA4GH_JWT-only_flow.png b/driver-project-usage/AAI/GA4GH_JWT-only_flow.png
deleted file mode 100644
index b1c50b3..0000000
Binary files a/driver-project-usage/AAI/GA4GH_JWT-only_flow.png and /dev/null differ
diff --git a/driver-project-usage/AAI/LifeScienceAAI.drawio.svg b/driver-project-usage/AAI/LifeScienceAAI.drawio.svg
deleted file mode 100644
index efcd988..0000000
--- a/driver-project-usage/AAI/LifeScienceAAI.drawio.svg
+++ /dev/null
@@ -1,4 +0,0 @@
-
-
-
-
\ No newline at end of file
diff --git a/driver-project-usage/AAI/README.md b/driver-project-usage/AAI/README.md
deleted file mode 100644
index 3881caa..0000000
--- a/driver-project-usage/AAI/README.md
+++ /dev/null
@@ -1,81 +0,0 @@
-# Authentication and Authorization Infrastructure
-
-## [Link to Specification](https://ga4gh.github.io/data-security/)
-
-## Introduction
-
-The Authentication and Authorizations Infrastructure (AAI) 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. In parallel, the Data Use and Researcher Identity (DURI) Work Stream has developed a standard
-representation for researcher authorizations and attributes known as Researcher-ID.
-At its core, the AAI specification defines cryptographically secure tokens for exchanging
-these researcher attributes called Visas and how various
-participants can interact to authenticate researchers, and obtain and validate Visas.
-
-This specification also provides for federated multilateral authorization infrastructure for greater
-interoperability between biomedical institutions sharing restricted datasets.
-
-### What is OpenID Connect?
-
-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. The AAI specification extends this to define 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.
-
-## Passports specification
-The AAI and Passports specifications rely on each other for full functionality and will likely be merged in a future version. The Passports specification from the Data Use and Researcher Identities Work Stream can be found [here](https://ga4gh-duri.github.io/researcher_ids/ga4gh_passport_v1.html).
-
-## Version history
-
-[Changelog](https://ga4gh.github.io/data-security/changes-1_2) for v1.2
-
-Full version history available [here](https://ga4gh.github.io/data-security/aai-openid-connect-profile#specification-revision-history)
-
-
-## Contributors
-
-GA4GH is an open community and contribution is not limited to those named below.
-Names listed alphabetically by surname. Repository maintainers listed [here](./MAINTAINER.md).
-
-### Core Developers for v1.2
-
-- Max Barkley - DNAstack
-- Tom Conner - Broad Institute
-- Martin Kuba - ELIXIR Czech Republic
-- Andrew Patterson - The University of Melbourne Centre for Cancer Research
-- Kurt Rodarmer - National Center for Biotechnology Information - NIH
-
-### Reviewers for v1.2
-
-- Francis Jeanson - Peter Munk Cardiac Centre and Ted Rogers Centre for Heart Research
-- David Glazer - Verily Life Sciences
-- Timothy Slade - RTI International
-- Dylan Spalding - ELIXIR Finland
-
-### Technical Programme Manager
-
-- Fabio Liberante - Global Alliance for Genomics and Health
-
-## Work Stream Leadership
-
-### Data Security
-
-- David Bernick - Broad Institute
-- Lucila Ohno-Machado - Yale University School of Medicine
-- Previously - Jean-Pierre Hubaux - Swiss Federal Institute of Technology Lausanne
-
-### Data Use and Researcher Identities
-
-- Jaime Guidry-Auvil - National Cancer Institute - NIH
-- Tommi Nyrönen - ELIXIR Finland
-
-
-## Demonstration Implementation
-
-[Life Science RI](https://lifescience-ri.eu/) have implemented this v1.2 specification from the finalised draft for use across the Life Science RI platforms.
-Information on creating an account is available [here](https://lifescience-ri.eu/ls-login/users/how-to-get-and-use-life-science-id.html).
-With an account, the test service [here](https://echo.aai.elixir-czech.org/) will return a technical view of the various tokens created and shared in an example flow using Passport/AAI 1.2.
\ No newline at end of file
diff --git a/driver-project-usage/AAI/aai background fig 1.JPG b/driver-project-usage/AAI/aai background fig 1.JPG
deleted file mode 100644
index f1da29f..0000000
Binary files a/driver-project-usage/AAI/aai background fig 1.JPG and /dev/null differ
diff --git a/driver-project-usage/AAI/aai background fig 2.png b/driver-project-usage/AAI/aai background fig 2.png
deleted file mode 100644
index b90fe23..0000000
Binary files a/driver-project-usage/AAI/aai background fig 2.png and /dev/null differ
diff --git a/driver-project-usage/AAI/claim_flow_of_data_basic.svg b/driver-project-usage/AAI/claim_flow_of_data_basic.svg
deleted file mode 100644
index 73b5c2b..0000000
--- a/driver-project-usage/AAI/claim_flow_of_data_basic.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/driver-project-usage/AAI/embedded_Claims_flow.png b/driver-project-usage/AAI/embedded_Claims_flow.png
deleted file mode 100644
index 407aaa4..0000000
Binary files a/driver-project-usage/AAI/embedded_Claims_flow.png and /dev/null differ
diff --git a/driver-project-usage/AAI/flow.png b/driver-project-usage/AAI/flow.png
deleted file mode 100644
index 904f685..0000000
Binary files a/driver-project-usage/AAI/flow.png and /dev/null differ
diff --git a/driver-project-usage/AAI/implementations.md b/driver-project-usage/AAI/implementations.md
deleted file mode 100644
index 93d07d7..0000000
--- a/driver-project-usage/AAI/implementations.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# Implementations
-
-## What would a 300,000 foot view of AAI look like?
-
-
-
-## How bout ELIXIR / Life Sciences AAI?
-
-
-
-## Which GA4GH driver projects implement AAI and Passports?
-
-As of November 2023, the following driver projects implement AAI / Passports:
-
-- Biomedical Research Hub
-- EJP RD
-- ELIXIR
-- Human Cell Atlas
-
-These driver projects are planning or developing an implementation of AAI / Passports:
-
-- All of Us
-- Australian Genomics
-- Autism Sharing Initiative
-- GDI
-- Genomics England
-- H3Africa
-- ICGC ARGO
-- IPCHiP
-- Monarch Initiative
-- NCI CRDC
-- NCPI
-- NHLBI BioData Catalyst
-
-[Source](https://docs.google.com/spreadsheets/d/11pPTKVW3j3_WHigWw4UOvlkQbPkM_z-ICgksE5L1vEY)
diff --git a/driver-project-usage/aai-faq.html b/driver-project-usage/aai-faq.html
deleted file mode 100644
index 8930786..0000000
--- a/driver-project-usage/aai-faq.html
+++ /dev/null
@@ -1,607 +0,0 @@
-
-
-
-
-
-
-
-
-AAI FAQ | GA4GH Data Security
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
A collection of questions (and hopefully useful answers).
-
-
-
-
Background
-
-
Why Brokers?
-
-
We have found that there are widely used Identity Providers (IdP).
-These authentication mechanisms provide no authorization
-information (custom claims or scopes) but are ubiquitous for authentication at the institution level.
-The use of a Broker and Clearinghouse
-enables attaching information to the usual OIDC flow so that IdPs
-can be used with customized claims and scopes.
-
-
Here is a diagram of a single broker. This is one possible way to use this spec.
-
-
-
-
In this diagram, the Broker relies on a separate service for fetching visas, which
-stores assertions from multiple sources. The visa assertions are obtained by the
-Clearinghouse after a successful login, and used to determine a researcher’s
-access in the Clearinghouse system.
-
-
The Broker, Clearinghouse, and Visa Issuer may be separate services (as shown
-in this diagram), but in other configurations they may be run as parts of a single
-service, or as separate services run by single organization. Data holders and data
-controllers should explore their options to decide what best fits their needs.
-
-
Flows
-
-
The following sequence diagrams are included to help explain the intended flows
-documented in the accompanying specification.
-
-
What is the complete end to end flow using token exchange?
-
-
(last updated June 2022)
-
-
This flow is the preferred flow for v1.2+ of the specification.
-
-
The exchange flow does not ever distribute the initial Passport-Scoped Access Token beyond
-the client application. 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 DRS server. The token
-exchange has also specified known resources that will limit the audience
-of the Passport.
-
-
-
-
-
-
What is the complete end to end flow using /userinfo?
-
-
(last updated June 2022)
-
-
This flow is the flow for v1.0 implementations of the specification.
-
-
The flow as used by Elixir uses the initial Passport-Scoped Access Token as
-a token handed to downstream resource servers. These servers can use this token, in conjunction
-with a callback to the broker’s Userinfo Endpoint, to obtain the Passport content in
-JSON format.
-
-
-
-
-
-
Trust
-
-
What’s with all the signed passports and visas etc? Why so complex?
-
-
(last updated July 2022)
-
-
The practical operation of a loosely coupled
-federated ecosystem like GA4GH Passports requires establishing trust
-relationships between the participating entities (see
-OpenID Connect Federation
-for an interesting discussion of the properties of multilateral federations).
-
-
Any entity that is asked to make a decision about sharing data needs to have a priori
-made the decision “which other entities do I trust?”. In genomics, a single decision
-to allow data sharing might involve simultaneous trusting of
-multiple entities - human genomics is complex!
-
-
When presented with a
-Passport and Visas from entities that they trust - they can rely on the information (claims) provided
-to make data sharing decisions. If presented with information from entities that are
-untrusted - the content of the message is irrelevant as there is no basis on which to believe
-the content.
-
-
So we can see that trust is a crucial element of a working federation. How do we establish
-these trust relationships?
-
-
GA4GH Passports and Visas leverage the mechanisms
-present in JWT as used
-by the OIDC standards
-to cryptographically “sign” tokens containing claims. Signed tokens can be
-“verified” using public/private keys.
-
-
Why are the Visa claims formatted as JWTs inside the Passport?
-
-
(last updated August 2022)
-
-
If visas were not signed separately from a Passport, then Clearinghouses would require a high degree of confidence that
-the signing Passport Issuer or Broker was accurately representing the contents of Visas from the original Visa Issuer;
-there would be no mechanisms to prevent a malicious or defective Passport Issuer from misrepresenting Visa contents.
-By signing Visas separately from Passports, we prevent intermediate parties from tampering with Visa contents,
-allowing Clearinghouses to safely rely on Visa contents based on their trust relationship with the Visa Issuer.
-
-
What are the ways that key management is done in practice?
-
-
(last updated July 2022)
-
-
There are a variety of approaches that can be used for key
-management for Passports and Visas. We will first detail those that can be used for Passports
-and then discuss some extra wrinkles for Visas.
-
-
For this discussion we assume there is a concrete JWT from issuer https://issuer.example.org
-(possibly a Broker or a Visa Issuer).
-
-
My clearinghouse service ‘trusts’ the above issuer to help make data
-access decisions - and that trust is stated probably through some sort of explicit
-configuration. For our example, let’s imagine it has a hypothetical YAML configuration file
For our concrete example we say that it is a JSON file residing
-at https://issuer.example.org/public-keys.json (see
-RFC 7517 “JSON Web Key”).
-
-
IMPORTANTLY, for the secure use of this key management technique - the JKU
-MUST also be allow-listed as part of the configuration of OUR service.
-For example:
It is NEVER valid to even attempt to access a JKU from a JWT header - unless the URL
-is already known to belong to the given issuer. See
-“JWT Forgery via unvalidated jku parameter”.
-
-
To verify a JWT, the content of the JKU file is loaded and the kid is
-looked up in key set. The signature is validated using the public key found.
-
-
Although this configuration requires explicit registration of JKUs, the content
-of the key sets can allow the best practice of key rotation.
-
-
The content of the JKU file is designed to be cached aggressively, but as long as
-the file is fetched every few days/weeks, the set of keys
-can evolve/rotate.
-
-
-
-
Use the kid in the header of the JWT along with OIDC Discovery
-
-
The OpenID Connect Discovery
-protocol allows the use of the JWT issuer URL - in conjunction with a fetch
-of a /.well-known/openid-configuration - to look up the location of the public key set file. See
-OpenID Provider Metadata specification
-and the jwks_uri entry.
-
-
As with JKU - it is important that OIDC discovery is limited only to JWT issuer URLs that are
-in some way allow-listed. It is NEVER valid to perform discovery on an arbitrary issuer
-encountered in a JWT. Luckily, the concept of allow-listing issuers is already in some way
-inherent to the way trust relationships are established, and hence this allow list should
-already be present in the system.
-
-
Also as with JKU, the content of the discovery protocol and key sets can be cached
-aggressively. This means that the double step of the discovery protocol is not
-required on every JWT verification.
-
-
-
-
Exchange public keys beforehand with each trusted entity
-
-
This is an approach used by the NIH - and is appropriate if the number
-of trusted entities is small - such that the public keys of each trusted entity can be exchanged
-out of band (and their rotation/updating can also be managed out of band).
For any kid
-encountered in a JWT, the corresponding public key is already available for signature validation.
-
-
An even safer version of this approach is to perform
-the key verification across every public key you hold before even decoding the JWT JSON
-and then confirm the kid. This avoids ever even needing to JSON decode
-data from untrusted entities.
-
-
-
-
Requirement for JKU in Visas
-
-
When it comes to Visas, there is an extra wrinkle - unlike Brokers, Visa Issuers do not
-need to have been part of an OIDC flow. It is possible that the visa issuer URI is not
-even a locatable reference
-(e.g. urn:example.com:dac-world-visa-issuer).
-
-
Therefore the OIDC Discovery technique is not appropriate and hence the requirements
-of the AAI standard regarding the presence of JKUs.
-
-
-
-
Client Software
-
-
Use of GA4GH passport/visas in Single Page Apps (SPAs)
-
-
It is currently recommended that single page apps (SPA) such as a React/VueJS websites
-are NOT used for scenarios where the single page app code is solely responsible for the handling of
-genomic passports and tokens.
-
-
A SPA contains all the source of the application in public - and hence cannot
-possess a ‘client secret’ in an OIDC flow (the ‘client secret’ is used to prove the identity of the
-client software and is an important risk mitigation that prevents unconstrained
-use of an accidentally leaked/stolen token).
-
-
Techniques such as PKCE can be used to allow a SPA to participate in an OIDC flow - and this is not
-forbidden by the specification - but there
-are still unresolved questions about how SPAs can prove client identity in things like the token
-exchange that retrieves passports or other tokens.
-
-
Therefore if writing SPA websites for genomic data handling, it is recommended to use
-a backend set of services to execute OIDC flows and token exchanges (even if the rest of the SPA
-can operate purely on the front end). These
-backend service can hold secrets and hence can prove client identity - and the backend
-service can then securely participate in token exchange and retain tokens/passports.
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.
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.
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.
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.
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_v1Claim 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 scopeClaim.
-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 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.
-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:
-[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
-
-
Full Login and Token Exchange Interaction
-
-
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.
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.
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]).
-
-
-
Public clients (single pages apps or mobile apps) SHOULD implement Authorization Code Flow
- with [PKCE].
-
-
-
-
-
Protection of Confidential Information
-
-
-
-
Sensitive information (e.g., including client secrets,
-authorization codes, id_tokens, access_tokens) MUST be passed over
-encrypted channels as per [OIDC-Client].
-
-
-
All responses that contain tokens, secrets, or other sensitive
-information MUST include the following HTTP response header fields and
-values as per [OIDC-Client].
-
-
-
-
Cache-Control: no-cache, no-store
-
-
-
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
-
-
-
-
Broker MUST conform to the OIDC Core specification [OIDC-Core].
-
-
-
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)
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 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].
-
-
-
-
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).
-
-
-
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.
-
-
-
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:
-
-
-
-
-
-
-
-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.
-
-
-
The token MUST conform with JWS format [RFC7515] requirements
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.
-
The token is not treated as an access token, but validity
-checks outlined elsewhere in this specification still apply.
-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.
The subject_token_type parameter value MUST be urn:ietf:params:oauth:token-type:access_token.
-
-
-
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.
-
-
-
-
Passport Clearinghouses MAY trust more than one Broker
-
-
-
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.
-
-
-
-
For access token flows, Passport Clearinghouses MUST either check the validity of the access token or treat the access
-token as opaque.
-
-
-
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].
-
-
-
-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.
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.
Token checks MUST be performed to ensure it complies with the access
-token specification.
-
-
-
In addition to other validation checks, a Visa is considered
-invalid if it is more than 1 hour old (as per the iatClaim) AND
-Access Token Polling does not confirm that the token is still
-valid (e.g. provide a success status code).
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.
-
-
-
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:
-
-
-
-
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.
-
-
-
The JWT access token has expired as per the exp field.
-
-
-
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.
-
-
-
The endpoint returns an HTTP status that is not retryable, e.g. HTTP status 400.
-
-
-
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.
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.
scope: REQUIRED. Includes verified scopes. MUST include openid and ga4gh_passport_v1.
-The scopeClaim 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.
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].
-
-
Header
-
-
This spec prescribes the following JWS headers for Passports
-in addition to the guidelines established in [RFC7515]:
-
-
-
-typ: REQUIRED where the value must be vnd.ga4gh.passport+jwt for Passports.
-
-
-
Payload
-
-
Only the GA4GH claims must be as prescribed here. See the
-JWT specification [RFC7519] for more details.
sub: REQUIRED. Please note that [OIDC-Core] in its section
- Subject Identifier Types
- allows the use of PPIDs (Pairwise Pseudonymous Identifiers) providing different sub value to each client
- to preclude correlation of user’s activities at different clients. Even if a public identifier is used (same for all clients),
- the value of the sub claim of a Passports may be different from the values of sub claims of its Visas,
- and the values may need to be linked using LinkedIdentities
- visas.
-
-
-
aud: OPTIONAL.
-
-
-
iat: REQUIRED.
-
-
-
exp: REQUIRED.
-
-
-
jti: RECOMMENDED.
-
-
-
ga4gh_passport_v1: REQUIRED. An array of GA4GH Visas. May be empty if a
- user has no visas. See the [Passport] specification
- for more details on types of visas.
-
-
-
-
-
-
Signing Algorithms
-
-
JWTs MUST be issued with signatures using the ES256 or RS256 algorithm.
-Passport - A signed and verifiable JWT container for holding Visas.
-
-Passport Issuer - a service that creates and signs Passports.
-
-Token Endpoint – as defined by OIDC
-
-UserInfo Endpoint - as defined by OIDC
-
-
-
Introduced Token Exchange mechanism
-
-
The standardized mechanism for exchanging access tokens for other tokens defined in RFC 8693 OAuth 2.0 Token Exchange
-was added and used for releasing Passports.
-
-
Redefined Passport as a JWT containing Visas
-
-
In version 1.0, Passport was defined as ”GA4GH-compatible access token along with the Passport Claim that is returned from Passport Broker service endpoints using such an access token“,
-thus as a tuple of an access token and a list of Visas that can be obtained from UserInfo endpoint using the access token.
-
-
In version 1.2, Passport is defined as “a signed and verifiable JWT container for holding Visas“, thus as a token that can be passed among systems.
-
-
For backward compatibility with version 1.0, list of Visas is still provided as a claim value from UserInfo endpoint.
-
-
Defined Passport Issuer
-
-
A Passport Issuer is a service that creates and signs Passports.
-A Broker is an OIDC Provider service that collects Visas from Visa Issuers and provides them to Passport Clearinghouses.
-
-
Broker may optionally become a Passport Issuer by supporting Token Exchange for issuance of Passports.
-
-
Brokers conforming to version 1.0 are still compatible with version 1.2, because Token Exchange support is optional.
-
-
Added more signing algorithms
-
-
The version 1.0 allowed only RS256 algorithm for JWT signing.
-It is RSA-based algorithm using keys of size 2048 bits or larger and SHA-256 hash function.
-
-
The AAI specification version 1.2 allows also the ES256 algorithm which is
-ECDSA-based using P-256 elliptic curve and SHA-256 hash function.
-
-
Elliptic Curve Cryptography allows much shorter keys and signatures than RSA.
-A short Elliptic Curve key of around 256 bits provides the same security as a 3072 bit RSA key.
In version 1.0, all the mentioned JWTs (access tokens, visas) used in their typ (media type) header parameter
-the generic value JWT that marks a generic JWT.
-
-
In version 1.2, the typ header parameter is used to distinguish the various types of JWTs:
-
-
-
access tokens conforming to RFC9038
-use the value at+jwt
-
-
Passports use the value vnd.ga4gh.passport+jwt
-
-
Visas are recommended to use the value vnd.ga4gh.visa+jwt but allowed to use JWT
-for backward compatibility with version 1.0
-
-
-
Proposed Deprecations
-
-
Visa Access Tokens (also referred to as Embedded Access Tokens)
-
-
It is proposed that the 1.x versions of this specification will be the last to support
-Visa Access Tokens. New implementations should issue Visas
-as Visa Document Tokens.
For more information about this process, please refer to the Passport
-Custom Visa Types
-section of the Passport specification or reach out to maintainers
-on the Update Procedure page.
-
-
Custom Visa Registry
-
-
-
-
-
Date
-
Visa Name
-
Visa Type String
-
Short Description
-
Documentation Links
-
-
-
-
-
2020-06-30
-
NIH RAS Controlled Access
-
https://ras.nih.gov/visas/v1.1
-
Multiple controlled access authorizations encoded into a single visa with a more detailed list of attributes per authorization. Currently encodes a detailed list of attribrutes that come from NIH’s dbGaP visa source repository.
Work Stream Name: Data Use and Researcher Identity (DURI)
-
-
Product Name: GA4GH Passport
-
-
Product Description: This document provides the GA4GH technical
-specification for a GA4GH Passport to be
-consumed by Passport Clearinghouses in a
-standardized approach to determine whether or not data access should be
-granted. Additionally, the specification provides guidance on encoding
-specific use cases, including
-Visas for Registered Access as
-described in the “Registered access: authorizing data
-access” publication.
-Refer to the Overview for an introduction to how data
-objects and services defined in this specification fit together.
-
-
Table of Contents
-
-
-
toc
-
-
-
Terminology
-
-
Inherited Definitions
-
-
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
-“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be
-interpreted as described in RFC 2119.
-
-
This specification inherits terminology from the
-GA4GH AAI OIDC Profile
-specification, namely these terms:
The {sub, iss} pair of JWT standard claims (RFC7519 section
-4.1.1) that are
-included within a Visa that represents a
-given user (sub for subject) within the issuer’s (iss) system.
-
-
-
Visa Object
-
-
-
-
A claim value for
- the ga4gh_visa_v1 claim name. The claim value is a JSON object
- that provides claims that describe Visa’s
- properties that cannot be described by the standard JWT claims like sub or exp.
-
-
-
The ga4gh_visa_v1 claim is required to define a GA4GH v1 visa and
- contains controlled vocabulary as defined in this document. This object
- is not the entire visa, and there are other important claims within
- Visa JWTs that MAY be specific to its visa type as well as other
- JWT claims that are required as per this specification and the GA4GH
- AAI OIDC specification.
-
-
-
For claim definitions, refer to the Visa Object Claims section of this specification.
-
-
-
-
Visa Type
-
-
-
-
The “type” claim value of a Visa Object
-that represents the semantics of the assertion and informs all parties
-involved in the authoring or handling the assertion how to interpret
-other Visa Object Claims.
-
-
-
For example, a Visa Type of “AffiliationAndRole” per the
-Standard Visa Type Definitions
-specifies the semantics of the Visa as well as the
-expected encoding of the “value” claim value for this purpose.
-
-
-
In addition to Standard Visa Type Definitions, there
-MAY also be Visas with Custom Visa Types.
-
-
-
-
Overview
-
-
Please see the Flow of Assertions
-section in the GA4GH AAI OIDC Profile specification for an overview of interaction among the specified parties.
-
-
General Requirements
-
-
-
-
Each Visa may have a different expiry.
-
-
-
Visas MUST have an indication of
-which organization made the Visa Assertion (i.e. the
-“source” claim), but Visas do not generally indicate
-individual persons involved in making the assertion (i.e. who assigned/signed
-the assertion) as detailed identity information is not needed to make an
-access decision.
-
-
-
Additional information about identity
-that is not needed to make an access decision SHOULD not be included in the
-Visas. Identity description, encoding audit details, other data
-for non-access purposes are not the intent of these Visas,
-and must be handled via other means beyond the scope of this specification
-should they be needed for entities and systems with sufficient authority to
-process such information.
If the Broker is the Visa Issuer,
-it MUST set the iss to itself and sign such Visas with an
-appropriate private key as described in the GA4GH AAI OIDC specification.
-
-
-
Visas are designed for machine
-interpretation only in order to make an access decision and is a non-goal to
-support rich user interface requirements nor do these claims fully encode the
-audit trail.
-
-
-
A Visa Object MAY
-contain the “conditions” claim to restrict the Visa
-to only be valid when the conditions are met.
-
-
-
For example, an identity can have several affiliations and a
-Visa with type “ControlledAccessGrants” MAY establish a
-dependency on one of them being present in the Passport by using the
-conditions claim.
-
-
-
-
Processing a Passport within a Passport Clearinghouse MUST abide by the following:
-
-
-
-
Passport Clearinghouses MUST reject all requests that include Passports
-that fail the necessary checks as described in the GA4GH AAI OIDC specification.
-
-
-
A Passport Clearinghouse MUST ignore all Visas it does not
-need to process a particular request.
-
-
-
Passport Clearinghouses MUST ignore Passports and Visas
-unless:
The Passport Clearinghouse can rely on a trusted service that
-provides sufficient trust of any of the Broker,
-Visa Assertion Source and/or Visa Issuer
-such that the Passport Clearinghouse can establish trust of all
-three such parties.
-
-
-
-
-
When combining Visas with multiple Visa Identities for the purposes of evaluating
-authorization, a Passport Clearinghouse MUST check the
-LinkedIdentities Visas by trusted issuers
-and ensure that trusted sources have asserted that these
-Visa Identities represent the same end user.
-
-
-
-
-
-
Support for User Interfaces
-
-
(e.g. mapping a URI string to a human-readable description for a user
-interface.)
-
-
For example, a user interface mapping of
-“https://doi.org/10.1038/s41431-018-0219-y” to a human readable description
-such as “this person is a bona fide researcher as described by the ‘Registered
-access: authorizing data access’ publication”.
-
-
It is a non-goal for this specification to consider the processes and data for
-the purpose of supporting user interfaces.
Visa Issuers, Brokers, and Passport Clearinghouses
-MUST conform to the
-GA4GH AAI Specification
-requirements for Visas in their use of Visas.
-
-
-
Validation, as outlined elsewhere in this specification and the
-GA4GH AAI Specification, MUST be performed before Visas are
-used for identity or authorization.
-
-
-
-
Visa Format
-
-
Visas are signed JWTs encoded into strings using JWS Compact Serialization.
-When decoded, their structure is:
The standard JWT payload claims iss, sub, iat, exp are all REQUIRED.
-
-
One of scope or jku MUST be present as described in
-Conformance for Visa Issuers
-within the AAI specification.
-
-
Claims within the ga4gh_visa_v1Visa Object are as described
-in the Visa Object Claims section of this specification.
-
-
“typ”
-
-
-
OPTIONAL. The value of the typ header claim is RECOMMENDED to be vnd.ga4gh.visa+jwt
-for Visa Document Token Format
-visas. The value JWT marking general JWTs MAY also be used.
The typ header claim is specified by section 5.1 of JWT RFC
-to contain media type of the JWT for disambiguation.
-The full recommended media type for GA4GH Visas is application/vnd.ga4gh.visa+jwt where the subtype consist of
-the “vendor tree” prefix vnd, the “producer name” ga4gh, and the “product designation” visa
-followed by the +jwt structured syntax suffix (specified in section 3.2
-and section 4.2.8 of RFC 6838).
-Then section 4.1.9 of JWS RFC recommends to omit the prefix
-application/ to keep messages compact.
-
-
-
“alg”
-
-
-
REQUIRED.The section Signing Algorithms
-in the AAI specification lists possible algorithms used in the alg header claim.
-
-
-
“exp”
-
-
-
-
REQUIRED. Generally, it is seconds since unix epoch of when the
-Visa Assertion Source
-requires such an assertion to be no longer valid. A Visa
-Assertion Source MAY choose to make an assertion very long lived.
-However, a Visa Issuer MAY
-choose an earlier timestamp in order to limit the assertion’s duration
-within downstream Passport Clearinghouses.
-
-
-
Access is NOT necessarily removed by the exp timestamp. Instead,
-this timestamp may be viewed as a cut-off after which no new access
-will be granted and action to remove any existing access may
-commence anytime shortly after this cut-off period.
Although standard claims within a Visa Object
-are defined in this section, other claims MAY exist within the object
-and should be ignored by any Passport Clearinghouse that is not familiar
-with the use of such claims. Claim names are reserved for definition by
-GA4GH (or a body it elects).
REQUIRED. Seconds since unix epoch that represents when the
- Visa Assertion Source made the claim.
-
-
-
Note that the standard iat JWT claim on the Visa reflects the timestamp
- of when the Visa was minted whereas the asserted claim
- reflects when the Visa Assertion Source made the assertion.
-
-
-
asserted MAY be used by a Passport Clearinghouse as described in the
- Visa Expiry section.
-
-
-
If a Visa Assertion repository does not include enough
- information to construct an asserted timestamp, a Visa Issuer MAY use a recent timestamp (for
- example, the current timestamp) if the Visa Assertion repository
- is kept up to date such that the Visa Issuer can ensure that
- the assertion is valid at or near the time of minting the Visa.
- However, generally it is RECOMMENDED to have the
- Visa Assertion repository provide more accurate asserted information.
-
-
-
-
“value”
-
-
-
-
REQUIRED. A string that represents any of the scope, process, identifier and
- version of the assertion. The format of the string can vary by the
- Visa Type.
-
-
-
For example, value: "https://doi.org/10.1038/s41431-018-0219-y" when type: "ResearcherStatus"
- represents a version of Registered Access Bona Fide
- researcher status. Note that Registered Access requires more than one
- Visa as outlined in the Registered
- Access section.
-
-
-
For the purposes of enforcing its policies for access, a Passport
- Clearinghouse evaluating the value claim MUST:
-
-
-
-
Validate URL strings as per the URL Claim
-requirements if the Visa Type definition indicates the value
-is a URL (as indicated by the type claim).
-
-
-
Value strings MUST be full string case-sensitive matches
-unless the Visa Type defines a safe and reliable format for
-partitioning the value into substrings and matching on the various
-substrings. For example, the standard
-AffiliationAndRole Visa Type can be
-reliably partitioned by splitting the string at the first “@” sign if such
-exists, or otherwise producing an error (i.e. denying permission).
-
-
-
-
-
-
“source”
-
-
-
-
REQUIRED. A URL Claim that provides at a minimum the
-organization that made the assertion. If there is no organization
-making the assertion, the source claim value MUST be set to
-“https://no.organization”.
-
-
-
For complex organizations that may require more specific information
-regarding which part of the organization made the assertion, this claim MAY
-also encode some substructure to the organization that represents the
-origin of the authority of the assertion. When this approach is chosen, then:
-
-
-
-
The additional substructure MUST only encode the sub-organization or
-department but no other details or variables that would make it
-difficult to enumerate the full set of possible values or cause Passport
-Clearinghouses confusion about which URLs to whitelist.
-
-
-
The additional information SHOULD be encoded into the subdomain or path
-whenever possible and SHOULD generally avoid the use of query parameters
-or anchors to represent the sub-organization.
-
-
-
Some organizations MAY wish to attribute the source to a particular
-Data Access Committee (DAC), especially for
-ControlledAccessGrants Visa Types.
-For example:
could represent one particular logical “DAC” organization as referred
-to by the EBI organization, and could be maintained by the EBI as a
-permanent identifier for this DAC.
-
-
-
-
-
-
“conditions”
-
-
-
-
OPTIONAL. A set of conditions on a
-Visa Object indicates that the Visa is
-only valid if the clauses of the conditions match other Visas
-elsewhere in the Passport and such content is both valid
-(e.g. hasn’t expired; signature of Visa has been verified against
-the public key; etc.) and if such content is accepted by the Passport
-Clearinghouse (e.g. the issuer is trusted; the source claim meets any
-policy criteria that has been established, etc.).
-
-
-
A Passport Clearinghouse MUST always check for the presence of
-the conditions claim and if present it MUST only accept the
-Visa if it can confirm that the conditions have been met.
-
-
-
Although it is RECOMMENDED to always implement full condition checking
-capabilities as described in this section, if a Passport Clearinghouse will be
-deployed for a more limited purpose where it is not expected to ever receive
-Visas with conditions, then such a Passport Clearinghouse MAY choose to
-not implement full condition checking. However, even in this case it MUST
-still check for the presence of the conditions claim on Visa
-Objects and reject (ignore) any Visas that contain a non-empty
-conditions claim value. Likewise if not all condition matching algorithms
-are implemented, it MUST reject any Visas that contain patterns
-that are not supported.
The conditions value is a two-nested-lists structure in Disjunctive
-Normal Form:
-
-
-
-
The outer level list is a set of OR clauses
-
-
-
The inner level list is a set of AND clauses that contain “Condition
-Clauses”
-
-
-
A Condition Clause MUST specify a “type” claim with a value as a
-Visa Type plus it MUST include at least one other claim with a
-name that matches a valid Visa Object claim name.
-
-
-
The values of Condition Clause claims MUST have a string prefix followed
-by a colon and then string suffix, except for type where it MUST be
-assumed to be “const” and is not specified.
-
-
-
-
If prefix is “const”, then suffix MUST use case sensitive full string
-matching.
-
-
-
If prefix is “pattern”, then suffix MUST use full string Pattern
-Matching to match input.
-
-
-
If prefix is “split_pattern”, then the full suffix MUST use full
-string Pattern Matching on each full
-substring from splitting the corresponding Visa Object
-claim value that is being compared by the “;” character. If any one
-full substring matches, then the Condition Clause claim has found a
-match. “split_pattern” SHOULD only be used on claims where the
-Visa Type has been specified in a format that makes splitting
-on this character to be reliable, such as URI-encoded substrings with
-semicolon separators (see LinkedIdentities as an
-example).
-
-
-
For example: a Condition Clause claim value of
-“split_pattern:123,https:%2F%2Fexample?.org” will match a
-Visa Object claim value of
-“001,https::%2F%2Fexample1.org;123,https::%2F%2Fexample2.org;456,https::%2F%2Fexample3.org”
-because this comparison value will be split into:
-
and the second entry in that list is a match using the Pattern
-Matching definition with 123,https:%2F%2Fexample?.org as the
-pattern to use.
-
-
-
-
-
If prefix is unknown or unsupported, then the Condition Clause must
-fail to match.
-
-
-
-
-
-
-
Condition Clause claims are restricted to only Visa Object Claims
-(e.g. value, source, etc.) with string value
-definitions.
-
-
-
-
It MUST NOT include conditions (i.e. a condition cannot be placed on
-another condition)
-
-
-
It MUST NOT contain a timestamp claim such as asserted.
-
-
-
-
-
The Passport Clearinghouse MUST verify that for each Condition Clause
-present, there exists a valid single corresponding
-Visa Object such that:
-
-
-
-
Checking the correctness of the Condition Clause MUST be performed first.
-For example, a type claim MUST be present.
-
-
-
Ignore Visa Objects that have the conditions claim present.
-This will avoid deep nesting of condition evaluation (i.e. avoid condition
-loops, stack overflows, etc).
-
-
-
A Condition Clause claim matches when the <match-type> algorithm
-matches a corresponding Visa Object’s claim in the Passport.
-
-
-
Visa Object Claims that are not specified
-in the Condition Clause are not required to match (i.e. any value will be
-accepted within that claim, including if the claim is not present in the
-Visa Object).
-
-
-
All Condition Clause claims that are specified within one Condition
-Clause MUST match the same Visa Object in the Passport.
OR, alternative acceptance is matching just one Visa:
-
-
-
-
type = “AffilationAndRole”; AND
-
-
-
value starts with “faculty\@”; AND
-
-
-
source = “https://visas.elixir.org”; AND
-
-
-
by = “system”
-
-
-
-
-
-
-
-
Pattern Matching
-
-
-
-
Pattern Matching is only for use as specified by
-“conditions”.
-
-
-
MUST Use full string case-sensitive character pattern comparison.
-
-
-
MUST support special meaning characters as the specification of patterns:
-
-
-
-
? : A <question-mark> is a pattern that SHALL match any single
-character.
-
-
-
* : An <asterisk> is a pattern that SHALL match multiple characters:
-
-
-
-
Match any string, including the empty string and null string.
-
-
-
Match the greatest possible number of characters that still allows
-the remainder of the pattern to match the string.
-
-
-
-
-
-
-
There is no escape character for special characters such as patterns.
-? is always treated as the <question-mark> pattern and * is always
-treated as the <asterisk> pattern.
-
-
-
A method evaluating a pattern on a string of input SHALL return a true if
-the input has found one or more possible ways to match or false if it does
-not.
-
-
-
-
“by”
-
-
-
-
OPTIONAL. The level or type of authority within the “source” organization
-of the assertion.
-
-
-
A Passport Clearinghouse MAY use this claim as part of an authorization
-decision based on the policies that it enforces.
-
-
-
Fixed vocabulary values for this claim are:
-
-
-
-
self: The Visa Identity for which the assertion is being made
-and the person who made the assertion is the same person.
-
-
-
peer: A person at the source organization has made this assertion on
-behalf of the Visa Identity’s person, and the person who is making
-the assertion has the same Visa Type and value in that source
-organization. The source claim represents the peer’s
-organization that is making the assertion, which is not necessarily
-the same organization as the Visa Identity’s organization.
-
-
-
system: The source organization’s information system has made the
-assertion based on system data or metadata that it stores.
-
-
-
so: The person (also known as “signing official”) making the assertion
-within the source organization possesses direct authority (as part of
-their formal duties) to bind the organization to their assertion that the
-Visa Identity did possess such authority at the time the
-assertion was made.
-
-
-
dac: A Data Access Committee or other authority that is responsible
-as a grantee decision-maker for the given value and source claims
-pair.
-
-
-
-
-
If this claim is not provided, then none of the above values can be assumed
-as the level or type of authority and the authority MUST be assumed to be
-“unknown”. Any policy expecting a specific value as per the list above MUST
-fail to accept an “unknown” value.
For the purposes of evaluating access, the URL MUST be treated as a simple
-unique persistent string identifier.
-
-
-
The URL is a canonical identifier and as such it is important that Passport
-Clearinghouses MUST match this identifier consistently using a
-case-sensitive full string comparison.
-
-
-
-
If TLS is available on the resource, then its persistent identifier URL
-SHOULD use the “https” scheme even if the resource will also resolve using
-the “http” scheme.
-
-
-
When the URL is being used to represent an organization or a well defined
-child organization within a “source” claim, it is RECOMMENDED
-to use a URL as a persistent organizational ontology identifier, whether
-managed directly or by a third-party service such as
-GRID when reasonable to do so.
-
-
-
-
-
The URL SHOULD also be as short as reasonably possible while avoiding
-collisions, and MUST NOT exceed 255 characters.
-
-
-
The URL MUST NOT be fetched as part of policy evaluation when making an
-access decision. For policy evaluation, it is considered an opaque string.
-
-
-
URLs SHOULD resolve to a human readable document for a policy maker to
-reason about.
-
-
-
-
GA4GH Standard Visa Type Definitions
-
-
Note: in addition to these GA4GH standard Visa Types, there is also
-the ability to for a Visa Issuer to encode Custom Visa Types.
-
-
AffiliationAndRole
-
-
-
-
The Visa Identity’s role within the identity’s affiliated institution
-as specified by one of the following:
-
-
-
-
eduPersonScopedAffiliation
-attributed value of: faculty, student, or member.
-This term is defined by eduPerson by the affiliated organization
-(organization after the \@-sign).
-
-
-
-
Example: “faculty\@cam.ac.uk”
-
-
-
Note: based on the eduPerson specification, it is possible that
-institutions use a different definition for the meaning of “faculty”
-ranging from “someone who does research”, to “someone who teaches”,
-to “someone in education that works with students”.
-
-
-
-
-
A custom role that includes a namespace prefix followed by a dot (“.”)
-where implementers introducing a new custom role MUST coordinate
-with GA4GH (or a body it elects) to align custom role use cases in order
-to maximize interoperability and avoid fragmentation across
-implementations.
-
-
-
-
Non-normative example: “ega.researcher\@med.stanford.edu” where “ega”
-is the namespace and “researcher” is the custom role within that
-namespace.
-
-
-
Custom roles and their prefixes MUST be limited to characters: a-z,
-dash (“-“), underscore (“_”), digits (0-9). Custom roles and prefixes
-MUST start with characters a-z.
-
-
-
-
-
-
-
If there is no affiliated institution associated with a given assertion, the
-affiliation portion of AffliationAndRole MUST be set to “no.organization”.
AffiliationAndRole can be safely partitioned into a {role, affiliation} pair
-by splitting the value string at the first “@” sign.
-
-
-
-
AcceptedTermsAndPolicies
-
-
-
-
The Visa Identity or the
- “source” organization has acknowledged the specific terms,
- policies, and conditions (or meet particular criteria) as indicated by the
- value claim.
-
-
-
The value claim value conforms to URL Claim format.
-
-
-
The URL SHOULD resolve to a public-facing, human readable web page that
- describe the terms and policies.
-
-
-
Example value: "https://doi.org/10.1038/s41431-018-0219-y"
- acknowledges ethics compliance for a particular version of Registered
- Access. Note that more
- Visas are needed to meet the requirements for Registered
- Access status.
The person has been acknowledged to be a researcher of a particular type or
-standard.
-
-
-
The value claim conforms to URL Claim format, and it
-indicates the minimum standard and/or type of researcher that describes
-the person represented by the given Visa Identity.
-
-
-
The URL SHOULD resolve to a human readable web page that describes the
-process that has been followed and the qualifications this person has met.
-
-
-
Example value: "https://doi.org/10.1038/s41431-018-0219-y"
-acknowledges a particular version of the registration process as needed
-for Registered Access Bona Fide researcher
-status. Note that more Visas are needed to meet
-the requirements for Registered Access status.
-
-
-
-
ControlledAccessGrants
-
-
-
-
A dataset or other object for which controlled access has been granted to
-this Visa Identity.
The identity as indicated by the {“sub”, “iss”} pair (aka
-Visa Identity) of the
-Visa is the same as the identity or identities listed
-in the “value” claim.
-
-
-
The “value” claim format is a semicolon-delimited list of
-“<uri-encoded-sub>,<uri-encoded-iss>” entries with no added whitespace
-between entries.
-
-
-
-
The “sub” and “iss” that are used to encode the “value” claim do
-not need to conform to URL Claim
-requirements since they must match the corresponding Visa
-“sub” and “iss” claims that may be issued.
-
-
-
By URI encoding (RFC 3986) the
-“iss”, special characters (such as “,” and “;”) are encoded within the URL
-without causing parsing conflicts.
The “source” claim refers to the Visa Assertion
-Source that is making the assertion. This is
-typically the same organization as the Visa
-Issuer (iss) that signs the Visa, but the
-source MAY also refer to another Visa Assertion Source depending
-on which organization collected the information.
-
-
-
As a non-normative example, if a policy needs 3 Visas and
-there are three Visas that meet the criteria on one Passport
-but they use 3 different sub values (“1234”, “567”, “890123”), then
-any of the following, if from a trusted issuers and sources, may
-allow these Visas to be combined (shown with JSON payload only
-and without the REQUIRED URI-encoding in order to improve readability of
-the example).
In addition to the
-GA4GH Standard Visa Type Definitions,
-Visas MAY be added using custom type names so long as the
-encoding of these Visas will abide by the requirements described
-elsewhere in this specification.
-
-
-
Custom Visa Types MUST limit personally identifiable information
-to only that which is necessary to provide authorization.
-
-
-
The custom type name MUST follow the format prescribed in the
-URL Claims section of the specification.
-
-
-
Implementers introducing a new custom type name MUST coordinate with the
-GA4GH (or a body it elects) to align custom type use cases to maximize
-interoperability and avoid unnecessary fragmentation across implementations.
-
-
-
-
To review the custom visa registry, including any visa descriptions,
-examples and links that have been provided through proposals using this
-process, visit the Custom Visa Type Registry
-page.
-
-
-
Documentation on encoding and interpreting the claims SHOULD
-be provided as part of the proposal and for inclusion in a public custom
-visa type registry maintained by GA4GH. This documentation SHOULD also include
-examples and links to relevant documentation and/or open source software
-that MAY be available.
-
-
-
-
-
Passport Clearinghouses MUST ignore all Visas containing a custom
-type name that they do not support.
-
-
-
Non-normative example custom type name:
-type: "https://example.org/passportVisaTypes/researcherStudies".
-
-
-
-
Encoding Use Cases
-
-
Use cases include, but are not limited to the following:
-
-
Registered Access
-
-
-
-
To meet the requirements of Registered Access to data as defined by
-publication https://doi.org/10.1038/s41431-018-0219-y as a specific
-version of Registered Access, a user needs to have all of the following
-Visas:
-
-
-
-
Meeting the ethics requirements is represented by:
If other versions of Registered Access are introduced, then the value
-claims for AcceptedTermsAndPolicies as well as ResearcherStatus MAY
-refer to the document or publication or sections thereof to act as the
-permanent identifiers for such versions of Registered Access.
-
-
-
The Passport Clearinghouse (e.g. to
-authorize a registered access beacon) needs to evaluate the
-multiple Visas listed above to ensure their values match
-before granting access.
-
-
-
If combining Visas from multiple
-Visa Identities, the Passport
-Clearinghouse MUST also check the
-LinkedIdentities Visas and
-determine if combining these identities came from a trusted
-Visa Issuer.
-
-
-
-
-
Controlled Access
-
-
-
-
Controlled Access to data utilizes the following Visa Types:
-
-
-
-
MUST utilize one or more
-ControlledAccessGrants and/or custom
-controlled access visa type(s) for permissions associated with specific
-data or datasets. There MAY be more standard visa types introduced for
-encoding controlled access in future revisions of the Passport
-specification.
-
-
-
MAY utilize the conditions claim on
-“ControlledAccessGrants” to cause such a grant to require
-a Visa from a trusted Visa Assertion Source to
-assert that the identity has a role within a specific organization.
-This can be achieved by using the
-AffiliationAndRole Visa Type on
-the conditions.
-
-
-
MAY utilize any other valid Visa Type or conditions claim
-that may be required to meet controlled access policies.
-
-
-
-
-
-
Visa Expiry
-
-
In addition to any other policy restrictions that a Passport Clearinghouse
-may enforce, Passport Clearinghouses that provide access for a given
-duration provided by the user (excluding any revocation policies) MUST
-enforce one of the following algorithm options to ensure that Visa
-expiry is accounted for:
-
-
Option A: use the following algorithm to determine if the Visa
-is valid for the entire duration of the requested duration:
requestedTTL represents the duration for which access is being requested.
-Alternatively a solution may choose to have a stronger revocation policy
-instead of requiring such a duration.
-
-
-
maxAuthzTTL represents any additional expiry policy that the Passport
-Clearinghouse may choose to enforce. If this is not needed, it can
-effectively ignored by using a large number of years or otherwise have
-token.ga4gh_visa_v1.asserted+maxAuthzTTL removed and simplify the right
-hand side expression accordingly.
-
-
-
-
Option B: if tokens are sufficiently short lived and/or the authorization
-system has an advanced revocation scheme that does not need to specify a
-maxAuthzTTL as per Option A, then the check can be simplified:
-
-
now()+accessTokenTTL < token.exp
-
-
-
Where:
-
-
-
-
accessTokenTTL represents the duration for which an access token will be
-accepted and is bounded by the next refresh token cycle or Access Token
-Polling
-cycle or any larger propagation delay before access is revoked, which
-needs to be assessed based on the revocation model.
-
-
-
For example, accessTokenTTL may be set to one hour, after which time
-more access tokens may be minted using a corresponding refresh token if
-it has not yet been revoked.
-
-
-
-
-
Expiry when using multiple Visas: if multiple Visas are
-required as part of an access policy evaluation, then the expiry to be used MUST
-be the minimum expiry timestamp, as calculated by the appropriate option above,
-across all Visas (token set) that were accepted as part of evaluating
-the access policy.
Visa Objects have an “asserted” claim to allow
-downstream policies to limit the life, if needed, of how long assertions
-will be accepted for use with access and refresh tokens.
-
-
-
Visas have an “exp” claim to allow Brokers and
-Passport Clearinghouses to limit the duration of access.
-
-
-
-
At a minimum, these Visa Claims MUST be checked by all Passport
-Clearinghouses and systems MUST be in place to begin to take action to remove access
-by the expiry timestamp or shortly thereafter. Propagation of these permission
-changes may also require some reasonable delay.
-
-
Systems employing Visas MUST provide mechanisms to
-limit the life of access, and specifically MUST conform to the GA4GH AAI
-Specification requirements in this regard. Systems utilizing Visas MAY also
-employ other mechanisms outlined in the GA4GH AAI Specification, such as Access
-Token Polling
-if the Visa is encoded as a Visa Access Token.
-
-
Example Passport Claim
-
-
This non-normative example illustrates a Passport Claim
-that has Visas representing Registered Access bona fide researcher
-status along with other Visas for access to specific Controlled Access
-data. The Visa Types for this example are:
-
-
-
-
AffiliationAndRole: The person is a member of faculty at Stanford
-University as asserted by a Signing Official at Stanford.
-
-
-
ControlledAccessGrants: The person has approved access by the DAC at the
-Example Institute for datasets 710 and approval for dataset 432 for a dataset
-from EGA.
-
-
-
-
In this example, assume dataset 710 does not have any
-“conditions” based on the
-AffiliationAndRole because the system that is asserting the assertion has an
-out of band process to check the researcher’s affiliation and role and
-withdraw the dataset 710 claim automatically, hence it does not need the
-conditions claim to accomplish this.
-
-
-
In this example, assume that dataset 432 does not use an out of band
-mechanism to check affiliation and role, so it makes use of the
-“conditions” claim mechanism to
-enforce the affiliation and role. The dataset 432 assertion is only valid if
-accompanied with a valid AffiliationAndRole claim for
-“faculty\@med.stanford.edu”.
-
-
-
-
-
AcceptedTermsAndPolicies: The person has accepted the Ethics terms and
-conditions as defined by Registered Access. They took this action
-themselves.
-
-
-
ResearcherStatus: A Signing Official at Stanford Medicine has asserted
-that this person is a bona fide researcher as defined by the Registered
-Access model.
-
-
-
LinkedIdentities: A Broker at example3.org has provided
-software functionality to allow a user to link their own accounts together.
-After the user has successfully logged into the two accounts and passed all
-auth challenges, the Broker added the
-LinkedIdentities Visa for those two accounts:
-(1) “10001” from example1.org, and (2) “abcd” from example2.org.
-Since the Broker is signing the “LinkedIdentities”
-Visa, it is acting as the Visa Issuer.
-
-
-
-
Normally a Passport like this would include Visa
-Format entries as JWS Compact Serialization strings,
-however this example shows the result after the Visas have been
-unencoded into JSON (and reduced to include only the payload) to be more
-reader-friendly.
-
-
-
-
diff --git a/feed.xml b/feed.xml
index 37ffa8f..204c1ec 100644
--- a/feed.xml
+++ b/feed.xml
@@ -1 +1 @@
-Jekyll2023-07-20T18:50:00+00:00/data-security/feed.xmlGA4GH Data SecurityAAI
\ No newline at end of file
+Jekyll2023-12-21T14:19:18+00:00/data-security/feed.xmlGA4GH Data SecurityAAI
\ No newline at end of file
