beacon_api.permissions.ga4gh

Parse permissions and statuses from ELIXIR token for GA4GH claim.

Current implementation is based on https://github.com/ga4gh/data-security/blob/master/AAI/AAIConnectProfile.md

The ELIXIR AAI JWT payload contains a GA4GH Passport claim in the scope:

{
    "scope": "openid ga4gh_passport_v1",
    ...
}

The token is then intended to be delivered to the /userinfo endpoint at ELIXIR AAI, which will respond with a list of assorted third party JWTs that need to be sifted through to find the relevant tokens. Initially it can not be determined which tokens contain the desired information.

{
    "ga4gh_passport_v1": [
        "JWT",
        "JWT",
        "JWT",
        ...
    ]
}

Each third party token (JWT, RFC 7519) consists of three parts separated by dots, in the following manner: header.payload.signature. This module processes the assorted tokens to extract the information they carry and to validate that data.

The process is carried out as such: 1. Take token (JWT) 2. Decode token 3a. Extract type key from the payload portion and check if the token type is of interest 3b. If the token is of the desired type, add it to list and continue, if not, discard this token and move to the next one 4. Extract jku key from the header portion (value is a URL that returns a JWK public key set) 5. Decode the complete token with the received public key 6. Validate the token claims 7. Extract the sought-after value from the ga4gh_visa_v1 object’s value key

Dataset permissions are read from GA4GH RI claims of the type “ControlledAccessGrants”

{
    "ga4gh_visa_v1": {
        "type": "ControlledAccessGrants",
        "value": "https://www.ebi.ac.uk/ega/EGAD000000000001",
        "source": "https://ega-archive.org/dacs/EGAC00000000001",
        "by": "dac",
        "asserted": 1546300800,
        "expires": 1577836800
    }
}

Bona Fide status is read from GA4GH RI claims of the type “AcceptedTermsAndPolicies” and “ResearcherStatus”, each being in their respective tokens.

{
    "ga4gh_visa_v1": {
        "type": "AcceptedTermsAndPolicies",
        "value": "https://doi.org/10.1038/s41431-018-0219-y",
        "source": "https://ga4gh.org/duri/no_org",
        "by": "self",
        "asserted": 1539069213,
        "expires": 4694742813
    }
}

{
    "ga4gh_visa_v1": {
        "type": "ResearcherStatus",
        "value": "https://doi.org/10.1038/s41431-018-0219-y",
        "source": "https://ga4gh.org/duri/no_org",
        "by": "peer",
        "asserted": 1539017776,
        "expires": 1593165413
    }
}

Functions

check_ga4gh_token(decoded_data, token, …)	Check the token for GA4GH claims.
decode_passport(encoded_passport)	Return decoded header and payload from encoded passport JWT.
get_ga4gh_bona_fide(passports)	Retrieve Bona Fide status from GA4GH JWT claim.
get_ga4gh_controlled(passports)	Retrieve dataset permissions from GA4GH passport visas.
get_ga4gh_permissions(token)	Retrieve GA4GH passports (JWTs) from ELIXIR AAI and process them into tangible permissions.
get_jwk(url)	Get JWK set keys to validate JWT.
retrieve_user_data(token)	Retrieve GA4GH user data.
validate_passport(passport)	Decode a passport and validate its contents.