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 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
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
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
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
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
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
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
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"}
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
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
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)
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
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"}
