Gen3 Auth Helper

class gen3.auth.Gen3Auth(endpoint=None, refresh_file=None, refresh_token=None, idp=None, client_credentials=None, client_scopes=None, access_token=None)[source]

Bases: AuthBase

Gen3 auth helper class for use with requests auth.

Implements requests.auth.AuthBase in order to support JWT authentication. Generates access tokens from the provided refresh token file or string. Automatically refreshes access tokens when they expire.

Parameters:

  • refresh_file (str, opt) – The file containing the downloaded JSON web token. Optional if working in a Gen3 Workspace. Defaults to (env[“GEN3_API_KEY”] || “credentials”) if refresh_token and idp not set. Includes ~/.gen3/ in search path if value does not include /. Interprets “idp://wts/<idp>” as an idp. Interprets “accesstoken:///<token>” as an access token

  • refresh_token (str, opt) – The JSON web token. Optional if working in a Gen3 Workspace.

  • idp (str, opt) – If working in a Gen3 Workspace, the IDP to use can be specified - “local” indicates the local environment fence idp

  • client_credentials (tuple, opt) – The (client_id, client_secret) credentials for an OIDC client that has the ‘client_credentials’ grant, allowing it to obtain access tokens.

  • client_scopes (str, opt) – Space-separated list of scopes requested for access tokens obtained from client credentials. Default: “user data openid”

  • access_token (str, opt) – provide an access token to override the use of any API key/refresh token. This is intended for cases where you may want to pass a token that was issued to a particular OIDC client (rather than acting on your own direct behalf, you can provide a key that was client-issued to your user)

Examples

This generates the Gen3Auth class pointed at the sandbox commons while using the credentials.json downloaded from the commons profile page and installed in ~/.gen3/credentials.json

>>> auth = Gen3Auth()

or use ~/.gen3/crdc.json:

>>> auth = Gen3Auth(refresh_file="crdc")

or use some arbitrary file:

>>> auth = Gen3Auth(refresh_file="./key.json")

or set the GEN3_API_KEY environment variable rather than pass the refresh_file argument to the Gen3Auth constructor.

If working with an OIDC client that has the ‘client_credentials’ grant, allowing it to obtain access tokens, provide the client ID and secret:

Note: client secrets should never be hardcoded!

>>> auth = Gen3Auth(
    endpoint="https://datacommons.example",
    client_credentials=("client ID", os.environ["GEN3_OIDC_CLIENT_CREDS_SECRET"])
)

If working in a Gen3 Workspace, initialize as follows:

>>> auth = Gen3Auth()
curl(path, request=None, data=None)[source]

Curl the given endpoint - ex: gen3 curl /user/user. Return requests.Response

Parameters:

  • path (str) – path under the commons to curl (/user/user, /index/index, /authz/mapping, …)

  • request (str in GET|POST|PUT|DELETE) – default to GET if data is not set, else default to POST

  • data (str) – json string or “@filename” of a json file

get_access_token()[source]

Get the access token - auto refresh if within 5 minutes of expiration

get_access_token_from_wts(endpoint=None)[source]

Try to fetch an access token for the given idp from the wts in the given namespace. If idp is not set, then default to “local”

refresh_access_token(endpoint=None)[source]

Get a new access token