OAuth2 and OIDC
Get and refresh access tokens from an OAuth 2.0 server, generate PKCE pairs, build the sign-in address and read the OpenID Connect discovery document. Typical uses: call an API that needs OAuth, let users sign in with an identity provider.
oauth tokenoauth refreshoauth pkceoauth pkceoauth authorize_urloauth discoveroauth discover

oauth token <token_url> <json_params>


Description

    Ask a token: JSON {access_token, token_type, expires_in, expires_at, refresh_token, scope, id_token, other}. The missing fields are null, other has the fields not listed here. Parameters: grant_type (client_credentials by default, authorization_code, refresh_token, password or a urn: value with extra), client_id and client_secret (not needed for client_credentials with client_assertion in extra), auth (form by default: in the body; basic: Authorization header with both values encoded as RFC 6749 asks; basic_raw: the same without encoding, for servers that do not decode), scope (string or array), audience, resource, username and password (password grant), code, redirect_uri, code_verifier (authorization code), refresh_token, extra (object of other form fields), now (seconds, for expires_at), timeout_ms (the whole call), max_bytes (of the response), ca_file (PEM file of private certification authorities), insecure (true: no check of the certificate, the result then has tls_verified false), allow_http (true: allow plain http outside the local machine). A refused request is an error with the OAuth code

Parameters

    token_url:   The token endpoint - String - required
    json_params:   The parameters - String - required
admin
oauth token "http://127.0.0.1:22003/token" "{\"client_id\": \"demo-client\", \"client_secret\": \"demo-secret\", \"scope\": \"read write\"}"
mentdb
{"access_token": "XmjUSnsFgTRKrgLkKnLWVw", "token_type": "Bearer", "expires_in": 864000, "expires_at": 1794721283, "refresh_token": null, "scope": "read write", "id_token": null, "other": {}}
Fixed result from a real call to a local test server (127.0.0.1): client credentials, HTTP Basic (authlib server)
admin
oauth token "http://127.0.0.1:22003/token" "{\"client_id\": \"demo-basic\", \"client_secret\": \"demo-secret\", \"auth\": \"basic\"}"
mentdb
{"access_token": "-tvS7n241n-ZSknT91rzHA", "token_type": "Bearer", "expires_in": 864000, "expires_at": 1794721283, "refresh_token": null, "scope": null, "id_token": null, "other": {}}
Fixed result from a real call to a local test server (127.0.0.1): authorization code with PKCE, the code comes from the authorization step (authlib server)
admin
oauth token "http://127.0.0.1:22003/token" "{\"grant_type\": \"authorization_code\", \"client_id\": \"public-client\", \"code\": \"@CODE@\", \"redirect_uri\": \"http://127.0.0.1:22999/cb\", \"code_verifier\": \"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk\"}"
mentdb
{"access_token": "0vZaw3quVtj91U3RtRVlcA", "token_type": "Bearer", "expires_in": 864000, "expires_at": 1794721283, "refresh_token": "H1zZks-UYBZmRzdbFpcBHw", "scope": "openid", "id_token": null, "other": {}}
Fixed result from a real call to a local test server (127.0.0.1): password grant, only when asked for (authlib server)
admin
oauth token "http://127.0.0.1:22003/token" "{\"client_id\": \"demo-client\", \"client_secret\": \"demo-secret\", \"grant_type\": \"password\", \"username\": \"alice\", \"password\": \"p\u00e4 ss&word\"}"
mentdb
{"access_token": "gKM_jSy-2EfXNnfy4C4LAQ", "token_type": "Bearer", "expires_in": 864000, "expires_at": 1794721283, "refresh_token": "cUszf0PaRXOOKRIQNsb3ig", "scope": null, "id_token": null, "other": {}}
Fixed result from a real call to a local test server (127.0.0.1): a wrong secret: the OAuth error, not the secret (authlib server)
admin
oauth token "http://127.0.0.1:22003/token" "{\"client_id\": \"demo-client\", \"client_secret\": \"wrong\"}"
mentdb
Sorry, an error appears (the token server refused: invalid_client (The client cannot authenticate with methods: ['client_secret_post', 'client_secret_basic']), HTTP status 401).
Fixed result from a real call to a local test server (127.0.0.1): nothing listens on this port
admin
oauth token "http://127.0.0.1:22999/token" "{\"client_id\": \"demo-client\", \"client_secret\": \"demo-secret\"}"
mentdb
Sorry, an error appears (the token request failed: connection refused).

oauth refresh <token_url> <refresh_token> <json_params>


Description

    Exchange a refresh token for a new access token. Same result and same parameters as oauth token. The server can send a new refresh token: keep it

Parameters

    token_url:   The token endpoint - String - required
    refresh_token:   The refresh token - String - required
    json_params:   The parameters - String - required
admin
oauth refresh "http://127.0.0.1:22003/token" "@RT@" "{\"client_id\": \"demo-client\", \"client_secret\": \"demo-secret\"}"
mentdb
{"access_token": "3KjiKVCujUN8OOjykR9cIg", "token_type": "Bearer", "expires_in": 3600, "expires_at": 1793860883, "refresh_token": "NDuoEqzWEJ30V89erst22Q", "scope": null, "id_token": null, "other": {}}

oauth pkce


Description

    Generate a PKCE pair (RFC 7636, S256 method): JSON {code_verifier, code_challenge, code_challenge_method}. The verifier stays with you, the challenge goes in the authorization URL

admin
oauth pkce
mentdb
{"code_verifier": "e3DVzCiY7pqoDEmJ0L3lwwLAK3DBPoikJOoDffTXJheZvTbGdK9DxAyA4oLLhE5M", "code_challenge": "uH-aS_AAJyVpnelh05j_yt3n7R4AdGIPcdqVb2WW9xo", "code_challenge_method": "S256"}

oauth pkce <json_params>


Description

    The same with parameters: code_verifier (compute the challenge of this verifier, 43 to 128 characters), or length (of the generated verifier, 64 by default, 43 to 128). Plain is not offered: RFC 7636 keeps it for clients that cannot compute SHA-256

Parameters

    json_params:   The parameters - String - required
admin
oauth pkce "{\"code_verifier\": \"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk\"}"
mentdb
{"code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "code_challenge_method": "S256"}
Used in use cases (1 recipe)

    Web & API developer › Prepare an OAuth 2 sign-in with PKCE
Often used with

    oauth authorize_url

oauth authorize_url <authorize_endpoint> <json_params>


Description

    Build the address where the user signs in: JSON {url, state, code_verifier}. Nothing is sent. Parameters: client_id (required), redirect_uri, scope (string or array), state (random by default: compare it on the callback, it protects against request forgery), nonce, response_type (code), pkce (true: generate a pair, code_verifier is then in the result), or code_challenge given by you, extra, allow_http

Parameters

    authorize_endpoint:   The authorization endpoint - String - required
    json_params:   The parameters - String - required
admin
oauth authorize_url "https://login.example.com/authorize" "{\"client_id\": \"my-app\", \"redirect_uri\": \"https://app.example.com/cb\", \"scope\": [\"openid\", \"email\"], \"state\": \"af0ifjsldkj\", \"code_challenge\": \"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM\"}"
mentdb
{"url": "https://login.example.com/authorize?response_type=code&client_id=my-app&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcb&scope=openid+email&state=af0ifjsldkj&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256", "state": "af0ifjsldkj", "code_verifier": null}
Used in use cases (1 recipe)

    Web & API developer › Prepare an OAuth 2 sign-in with PKCE
Often used with

    oauth pkce

oauth discover <issuer>


Description

    Read the OpenID Connect discovery document of an issuer (issuer + /.well-known/openid-configuration) and return it as JSON. The issuer inside the document must be the expected one, and every address of the document (each key ending in _endpoint or _uri) must be a valid https address outside the local machine; op_policy_uri and op_tos_uri may also be http

Parameters

    issuer:   The issuer, or the full address of the document (OIDC or RFC 8414 form) - String - required
admin
oauth discover "http://127.0.0.1:22003/realm"
mentdb
{"authorization_endpoint": "http://127.0.0.1:22003/authorize", "issuer": "http://127.0.0.1:22003/realm", "jwks_uri": "http://127.0.0.1:22003/jwks", "token_endpoint": "http://127.0.0.1:22003/token"}
Fixed result from a real call to a local test server (127.0.0.1): a document that gives another issuer is refused
admin
oauth discover "http://127.0.0.1:22003/bad"
mentdb
Sorry, an error appears (the issuer of the discovery document is not the expected one ('https://evil.example.com', check_issuer can disable this control)).

oauth discover <issuer> <json_params>


Description

    The same with parameters: well_known (openid-configuration by default, oauth-authorization-server for RFC 8414), check_issuer (true; false disables the control of the issuer), timeout_ms (the whole call), max_bytes (of the response), ca_file (PEM file of private certification authorities), insecure (true: no check of the certificate, the result then has tls_verified false), allow_http (true: allow plain http outside the local machine)

Parameters

    issuer:   The issuer - String - required
    json_params:   The parameters - String - required
admin
oauth discover "http://127.0.0.1:22003/realm" "{\"well_known\": \"oauth-authorization-server\", \"timeout_ms\": 5000}"
mentdb
{"authorization_endpoint": "http://127.0.0.1:22003/authorize", "issuer": "http://127.0.0.1:22003/realm", "jwks_uri": "http://127.0.0.1:22003/jwks", "token_endpoint": "http://127.0.0.1:22003/token"}