Passports v1.2 Technical Update

Montreal Connect April 2022

​

Martin Kuba <makub@ics.muni.cz>

Outline

• brief overview of OIDC, OAuth 2, JWT, JWS, claims
• GA4GH Passport and AAI OIDC Profile specifications
• published version 1.0
• unpublished NIH version 1.1
• future versions 1.2 and 2.0

GA4GH AAI and Passport Specifications

• two intertwined specifications approved in 2019 in version 1.0:
• GA4GH Authentication and Authorization Infrastructure (AAI) OpenID Connect (OIDC) Profile http://bit.ly/ga4gh-aai-profile
• GA4GH Passport http://bit.ly/ga4gh-passport-v1
• GA4GH AAI OIDC Profile defines involved parties and how they interact using OIDC protocol and digitally signed JSON Web Tokens (JWT) to exchange claims about a user
• claim is a term defined in specification of JWT and inherited in OIDC
• GA4GH Passport defines the content of ga4gh_passport_v1 claim as a list of Visas - JWTs carrying user attributes; also defines format and meaning of several types of Visas

JSON Web Tokens and Claims

• JSON (JavaScript Object Notation) is a data interchange format using syntax for objects from the JavaScript programming language
• JWT (JSON Web Token) is a JSON message digitally signed and encoded using JSON Web Signature
• JWS (JSON Web Signature) is a specification for signing any binary data and encoding them in the form of a triple <header>.<message>.<signature> where all 3 parts are encoded using base64-url-safe encoding and joined by dot characters
• claim is defined in JWT specification (RFC 7519): “A piece of information asserted about a subject. A claim is represented as a name/value pair consisting of a Claim Name and a Claim Value. A Claim Name is always a string. A Claim Value can be any JSON value.”

OAuth 2.0 and OpenID Connect

• OAuth 2.0 (RFC 6749) is an open standard for access delegation, commonly used as a way for internet users to grant applications access to their information on other websites but without giving them their passwords
• OpenID Connect (https://openid.net/connect/) is an authentication layer on top of the OAuth 2.0 authorization framework
• OAuth 2.0 defines an authorization server with 3 endpoints: authorization endpoint, token endpoint and introspection endpoint
• OpenID Connect adds userinfo endpoint as API for obtaining user information in the form of claims

OIDC / OAuth 2 Authorization Code Grant Flow

GA4GH AAI OpenID Connect Profile

defines involved parties:

• Identity Provider (IdP) - provides primary authentication, e.g. Google, Facebook, ORCID, university’s IdP from eduGAIN federation
• Broker - OIDC Provider issuing GA4GH Passports, e.g. ELIXIR AAI, NIH RAS
• Claim Clearinghouse - OIDC Relying Party that consumes GA4GH Passports
• Claim Source - organization that asserts a claim about a user
• Claim Repository - a database of claims
• Embedded Token Issuer - a service that issues digitally signed Visas

GA4GH Passport Specification

defines claim ga4gh_passport_v1 that contains a list of strings representing visas

• a visa is a signed JWT containing special ga4gh_visa_v1 object
• predefined types of visas:
• AffiliationAndRole - role within the users’ affiliated institution
• AcceptedTermsAndPolicies - user accepted specific terms, policies, conditions or meets particular criteria (e.g. ethics compliance)
• ResearcherStatus - the user has been acknowledged to be a researcher of a particular type or standard
• LinkedIdentities - assertions of differing user identifiers to identify the same person
• ControlledAccessGrants - grants of controlled access to data sets
• custom visa types are allowed

Example of a UserInfo Response with Passport

passport claim

visas

Example of a Decoded Passport Visa

signing key id

user id

visa type

issuer

URL of claim source organization

visa value

JSON Web Keys URL

signing algorithm

assertion time in seconds since 1970-01-01

issued at time

GA4GH Passport Three-tiered Data-access Model

GA4GH AAI and Passport Implementations

• for the approval of version 1.0 of AAI and Passport specifications, two implementations were required:
• Google
• ELIXIR AAI
• produces all 5 types of Visas, uses both registered and controlled access
• datasets are available from European Genome-Phenome Archive (EGA)
• U.S. National Institute of Health (NIH) Researcher Auth Service (RAS)
• produces only a single custom type Visa for controlled access
• proposed version 1.1 of passports

NIH’s Proposed Passport version 1.1

• Passport specification version 1.0 says that
• ga4gh_passport_v1 claim contains a list of individually signed visas
• the claim is obtained from /userinfo OIDC endpoint
• response of /userinfo is plain unsigned JSON text
• NIH needs to pass Passports to systems disconnected from the internet for security reasons, for validation Passports need to be wrapped in a signed token
• NIH proposed version 1.1 where the /userinfo response contains passport_jwt_v11 claim containing signed JWT containing ga4gh_passport_v1 claim with a list of visas
• version 1.1 was not accepted, to avoid confusion 1.1 will be skipped

Upcoming AAI/Passport version 1.2

• the next planned version is minor version 1.2 - approval not needed
• this version adds issuing of Passports as signed tokens using the mechanism of OAuth 2.0 Token Exchange (RFC 8693)
• Token Exchange is done at /token endpoint by exchanging a Passport-scoped access token for a new type of token
• for backward compatibility with version 1.0, visas will be still issued also from /userinfo as unsigned plain JSON text
• this version solves a use case for mutually trusting systems that need to pass signed tokens among them
• this version does not solve the problem of tokens that need to fit into HTTP Authorization headers (8 kB limit)

Planned AAI/Passport version 2.0

• new major version - will need approval from the Steering Committee
• version 2.0 will define a new type of token - work-order token
• a Passport carries all user’s visas thus gives access to all user’s datasets
• for obtaining datasets from DRS (Data Repository Service) and processing them in Task Execution Service (TES) securely, only the minimal needed access should be given, not to everything
• work-order token
• will be limited to specific datasets and TESes for a given workflow
• will not be a bearer token, will be usable by specified agents only
• will be small, not containing visas, fitting into HTTP headers
• will be also issued using the OAuth 2.0 Token Exchange mechanism introduced in version 1.2

GA4GH Cloud Work Stream standardized APIs

Working Subgroup

If you are interested in the development of AAI/Passport specs, join the Passports/AAI Technical Working subgroup, a collaboration between the Data Security and DURI Work Streams, meeting weekly on Thursdays at 12:00 UTC

Thank you for your attention