An OAuth 2.0 and OpenID Connect authorization server built with Authlib, configured from a web interface. Run it to test and debug an OAuth 2.0 or OpenID Connect client, or to try the server features of Authlib. For a client to test an authorization server, see Auth Playground.
This page explains how to run, try and configure the server. It assumes basic knowledge of OAuth 2.0 and OpenID Connect. It does not explain how to build a server with Authlib: for that, read the Authlib documentation and the example OAuth 2.0 server.
The web interface has five sections:
- Server: the published metadata, the grants, the client authentication methods, PKCE, the token lifetimes, the scopes and the ID token algorithms. The defaults follow RFC 9700.
- Keys: the keys that sign the ID tokens, one active key per algorithm. A rotation creates a new active key. The old key stays in the JWKS until it is deleted, so clients can still verify the tokens it signed.
- Clients: create and edit the clients by hand, and see the clients that registered themselves. A client can have keys, as a key set or a key set URL. The form marks the values that the server does not support.
- Personas: the users of the server. The server checks no password: at the authorization endpoint, pick the persona to act as. Each persona has the standard claims of OpenID Connect. The persona page lists the consents of the persona, and revokes them.
- Snapshot: export the configuration, the personas, the clients and the signing keys to a JSON file, and import such a file. The file holds the client secrets and the private keys: keep it private. The server refuses a snapshot from an earlier version.
The server supports these grants and endpoints:
- Authorization code grant, with PKCE (RFC 7636). Authorization errors redirect to the client with HTTP 303.
- Implicit grant, off by default.
- Resource owner password credentials grant, off by default.
- Client credentials grant.
- Refresh token grant.
- Token revocation (RFC 7009).
- Dynamic client registration (RFC 7591) and client configuration (RFC 7592), at
/oauth/register. - Client authentication with
client_secret_basic,client_secret_post,private_key_jwtandclient_secret_jwt(RFC 7523 §2.2, OpenID Connect Core §9), and public clients withnone. - Authorization server metadata (RFC 8414), at
/.well-known/oauth-authorization-server. - A protected resource,
/api/resource, that returns the scope, the client and the persona of the access token.
OpenID Connect is on when the scopes of the server hold openid, as in the default configuration.
The server then supports:
- ID tokens in the authorization code flow, signed with RS256, PS256, ES256 or Ed25519.
- The UserInfo endpoint, at
/oauth/userinfo. - Discovery, at
/.well-known/openid-configuration, and the public keys at/oauth/jwks. - The
prompt,max_age,login_hint,ui_localesandacr_valuesparameters.login_hintpreselects a persona, andui_localessets the language of the persona and consent pages. The server accepts anyacrvalue: the ID token holds the first requested value. - A default
max_agefor each client. - The
claimsparameter. The consent page lists the claims that the scopes do not give. - Request objects in the
requestparameter (RFC 9101), unsigned (algnone) or signed with RS256, PS256, ES256, Ed25519 or HS256. A client verifies a signed object with its keys. HS256 uses the client secret, so a public client cannot send one. Therequest_uriparameter is not supported. - Registration of the OpenID Connect client metadata (OpenID Connect Registration).
- The client logo and links (
logo_uri,client_uri,policy_uri,tos_uri) on the persona and consent pages. OnlyhttpandhttpsURLs show.
Run the server from the source code with uv:
$ uv run auth-server-playground
* Serving Flask app 'auth_server_playground'
* Debug mode: off
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
* Running on http://127.0.0.1:3000
Press CTRL+C to quitOpen http://127.0.0.1:3000/ to reach the web interface.
The server stores its data in a SQLite database in the Flask instance folder.
At start, the server creates the missing tables, but it does not change the existing ones.
After an update that changes a table, remove the database: the server creates a new one.
An update can also add keys to the configuration document, and the server does not migrate a stored one.
So remove the database after such an update too.
Run the server with Docker:
docker build -t auth-server-playground .
docker run -p 3000:3000 -v auth-server-playground:/data auth-server-playgroundThe container stores the database in /data.
The volume keeps the data when the container is removed.
The default configuration enables the authorization code, refresh token and client credentials grants. The client credentials grant needs no persona, so it is the shortest way to get a token. Create a client in the web interface:
- Open Clients, then New client.
- Set Client ID to
demo. - Check
client_credentialsin Grant types. - Set Scopes to
profile. - Keep
client_secret_basicas the Authentication method. - Click Save. The client page shows the client secret.
Request a token, with <SECRET> replaced by the client secret:
$ curl -u demo:<SECRET> -d grant_type=client_credentials -d scope=profile http://127.0.0.1:3000/oauth/token
{"token_type": "Bearer", "access_token": "XUpVEr75OavL4VdLKitjwnvypTJx2fn92JxW1LYiXC", "expires_in": 3600, "scope": "profile"}Call the protected resource with the access token:
$ curl -H "Authorization: Bearer <ACCESS_TOKEN>" http://127.0.0.1:3000/api/resource
{"scope":"profile","client_id":"demo"}The password grant is off by default, as RFC 9700 §2.4 requires:
$ curl -u demo:<SECRET> -d grant_type=password -d username=alice -d password=x http://127.0.0.1:3000/oauth/token
{"error": "unsupported_grant_type"}Enable it in Server, then in the client.
The default configuration lets any client register itself.
The registration endpoint is /oauth/register, and the discovery documents publish it as registration_endpoint.
Register a client with a JSON request:
$ curl -s -X POST -H 'Content-Type: application/json' -d '{"client_name":"Demo app","redirect_uris":["http://127.0.0.1:8000/callback"],"token_endpoint_auth_method":"client_secret_basic","scope":"openid profile"}' http://127.0.0.1:3000/oauth/register
{"grant_types": ["authorization_code"], "response_types": ["code"], "redirect_uris": ["http://127.0.0.1:8000/callback"], "token_endpoint_auth_method": "client_secret_basic", "client_name": "Demo app", "scope": "openid profile", "application_type": "web", "id_token_signed_response_alg": "RS256", "require_auth_time": false, "require_signed_request_object": false, "client_id": "WTq5BbF5l2fkN89OqWcLmPhu", "client_secret": "k9wuEF...5qCR", "client_id_issued_at": 1794920968, "client_secret_expires_at": 0, "registration_client_uri": "http://127.0.0.1:3000/oauth/register/WTq5BbF5l2fkN89OqWcLmPhu", "registration_access_token": "6AZu5x...GUc"}The response holds the client secret, shortened here.
It also holds registration_client_uri and registration_access_token.
Per RFC 7592, the client reads, changes and deletes its registration at that URI, with the registration access token as Bearer token:
$ curl -s -H "Authorization: Bearer <REGISTRATION_ACCESS_TOKEN>" http://127.0.0.1:3000/oauth/register/WTq5BbF5l2fkN89OqWcLmPhu
{"client_id": "WTq5BbF5l2fkN89OqWcLmPhu", "client_secret": "k9wuEF...5qCR", "client_id_issued_at": 1794920968, "client_secret_expires_at": 0, "grant_types": ["authorization_code"], "response_types": ["code"], "redirect_uris": ["http://127.0.0.1:8000/callback"], "token_endpoint_auth_method": "client_secret_basic", "client_name": "Demo app", "scope": "openid profile", "application_type": "web", "id_token_signed_response_alg": "RS256", "require_auth_time": false, "require_signed_request_object": false, "registration_client_uri": "http://127.0.0.1:3000/oauth/register/WTq5BbF5l2fkN89OqWcLmPhu", "registration_access_token": "6AZu5x...GUc"}The server applies the defaults of RFC 7591 §2: the authorization_code grant and the code response type.
It refuses invalid metadata, such as private_key_jwt without jwks or jwks_uri:
$ curl -s -X POST -H 'Content-Type: application/json' -d '{"redirect_uris":["http://127.0.0.1:8000/callback"],"token_endpoint_auth_method":"private_key_jwt"}' http://127.0.0.1:3000/oauth/register
{"error": "invalid_client_metadata", "error_description": "private_key_jwt needs jwks or jwks_uri."}Set the mode in Server, under Dynamic registration:
disabled: the registration endpoint and the client configuration endpoint answer 404, and the discovery documents do not publishregistration_endpoint.open: any client can register. This is the default.token: a client must send the initial access token as Bearer token (RFC 7591 §3). The server page shows the token and has a button to replace it. The server creates a token when the mode becomestoken.
The mode and the token are in the configuration document, so a snapshot keeps them.
A client that registered itself is a dynamic client.
The client list marks it with dynamic.
Its page shows the registration URL and the registration access token, and the form edits it like any other client.
One button of the client list, Delete the dynamic clients (N), deletes all the dynamic clients.
The button shows when at least one dynamic client exists.
Clients find the endpoints of the server in its discovery document:
$ curl -s http://127.0.0.1:3000/.well-known/openid-configuration | jq '{issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri}'
{
"issuer": "http://127.0.0.1:3000",
"authorization_endpoint": "http://127.0.0.1:3000/oauth/authorize",
"token_endpoint": "http://127.0.0.1:3000/oauth/token",
"userinfo_endpoint": "http://127.0.0.1:3000/oauth/userinfo",
"jwks_uri": "http://127.0.0.1:3000/oauth/jwks"
}Set up the demo client of the previous section for the authorization code flow:
- Open Clients, then
demo. - Set Redirect URIs to
http://127.0.0.1:8000/callback. No server needs to listen there: the code shows in the address bar of the browser. - Check
authorization_codein Grant types, andcodein Response types. - Set Scopes to
openid profile. - Click Save.
The default configuration requires PKCE for all clients. Create a code verifier, and print an authorization URL with its challenge:
VERIFIER=$(openssl rand -hex 32)
CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=')
echo "http://127.0.0.1:3000/oauth/authorize?response_type=code&client_id=demo&redirect_uri=http://127.0.0.1:8000/callback&scope=openid%20profile&nonce=n-0S6_WzA2Mj&code_challenge=$CHALLENGE&code_challenge_method=S256"Open the URL in a browser, pick a persona, and click Accept.
The browser goes to the redirect URI, such as http://127.0.0.1:8000/callback?code=NfcKoEYKZVGeX3HWX0sfAA6HDZUtwmJl2QpC35gU6saJVXPc.
In the same shell, exchange the code for the tokens, with <CODE> replaced by the code:
$ curl -s -u demo:<SECRET> -d grant_type=authorization_code -d code=<CODE> -d redirect_uri=http://127.0.0.1:8000/callback -d code_verifier=$VERIFIER http://127.0.0.1:3000/oauth/token | tee token.json
{"token_type": "Bearer", "access_token": "BnRYDC5spCh9C4kugcA99yieB5dzFgzDtyTfuBcbk8", "expires_in": 3600, "refresh_token": "Tdh8EtppfPcv7bMcKEQP8FYqz32UrD5Eqos1kCqQQQKnDxzE", "scope": "openid profile", "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImQ4cnMzM2lqd0IxNHdrWmR6ZWUxbWttZFJNakxtVTJWekN4VlE0RDJzNGsifQ..."}The ID token is a JWT, shortened in this output. Read some of its claims:
$ jq '.id_token | split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson | {iss, aud, sub, nonce, auth_time, name}' token.json
{
"iss": "http://127.0.0.1:3000",
"aud": [
"demo"
],
"sub": "c0a1e3d2-7b5f-4e7a-9d2c-1f6b8a4e5c3d",
"nonce": "n-0S6_WzA2Mj",
"auth_time": 1794764875,
"name": "Alice Martin"
}Call the UserInfo endpoint with the access token:
$ curl -s -H "Authorization: Bearer $(jq -r .access_token token.json)" http://127.0.0.1:3000/oauth/userinfo
{"name": "Alice Martin", "given_name": "Alice", "family_name": "Martin", "middle_name": "Claire", "nickname": "Ali", "preferred_username": "alice", "profile": "https://alice.example/profile", "website": "https://alice.example", "gender": "female", "birthdate": "1990-12-10", "zoneinfo": "Europe/Paris", "locale": "fr-FR", "updated_at": 1794764773, "sub": "c0a1e3d2-7b5f-4e7a-9d2c-1f6b8a4e5c3d", "picture": "http://127.0.0.1:3000/personas/1/picture.svg"}The server passes the Config and Basic plans of the OpenID Foundation conformance suite, with a few warnings.
conformance/expected-failures.json lists them, with their reasons.
conformance/README.md explains how to run the suite against the server.
The server reads its configuration from environment variables.
example.env lists them.
Copy it to .env: the auth-server-playground command loads .env from the current directory.
| Variable | Default | Description |
|---|---|---|
SECRET_KEY |
generated | Key that signs the session cookies. Without it, the server generates a key once and stores it in the database. |
DATABASE_URL |
sqlite:///db.sqlite |
SQLAlchemy database URL. A relative SQLite path goes in the Flask instance folder. |
INITIAL_SNAPSHOT |
unset | Snapshot file loaded when the database is empty. An invalid file stops the server. |
PROXY_FIX |
false |
Set to true behind a reverse proxy. |
AUTHLIB_INSECURE_TRANSPORT |
unset | Set to 1 to accept plain HTTP requests. |
FLASK_RUN_HOST |
127.0.0.1 |
Address of the auth-server-playground command. |
FLASK_RUN_PORT |
3000 |
Port of the auth-server-playground command. |
FLASK_DEBUG |
False |
Set to True to enable the Flask debug mode. |
Per RFC 6749 §3.1 and §3.2, the OAuth 2.0 endpoints require TLS.
The server accepts plain HTTP on loopback addresses, such as 127.0.0.1.
On other hosts, plain HTTP requests get an insecure_transport error, unless AUTHLIB_INSECURE_TRANSPORT is set.
Never set it in production.
The Docker image serves the server with Granian, configured by these variables:
| Variable | Value in the image | Description |
|---|---|---|
GRANIAN_HOST |
0.0.0.0 |
Address the server listens on. |
GRANIAN_PORT |
3000 |
Port the server listens on. |
GRANIAN_INTERFACE |
wsgi |
Interface between Granian and the application. |
GRANIAN_LOG_ACCESS_ENABLED |
true |
Log each request. |
GRANIAN_WORKERS |
1 |
Number of worker processes. |
Granian reads its other settings from GRANIAN_* variables too.
The workers share the key stored in the database, so several workers need no SECRET_KEY.
A client has keys when its metadata holds jwks (a JWK Set with public keys) or jwks_uri (the URL of a JWK Set).
The two exclude each other.
The server reads the keys to verify the JWTs of the client.
With several keys, the JWT header needs a kid. With one key, it can omit it.
The private_key_jwt method needs keys.
The client signs an assertion with a private key (RFC 7523 §2.2).
The server accepts RS256, PS256, ES256 and Ed25519.
The client_secret_jwt method uses the client secret.
The client signs the assertion with HS256.
For both methods, the client sends client_assertion_type and client_assertion to the token endpoint, and to the revocation endpoint when it is on.
The aud claim is the issuer or the URL of the token endpoint.
Each jti is accepted once.
The client can set token_endpoint_auth_signing_alg to allow one algorithm only.
In Server, uncheck an algorithm of the token endpoint to refuse it.
The server checks the method registered by the client on every endpoint.
A client_secret_post client that sends Basic credentials to /oauth/revoke is refused.
The server checks a signed request object with the same client keys.
With HS256, the key is the client secret, and a public client gets invalid_request_object.
An algorithm that the server does not support gives invalid_request.
The server fetches jwks_uri when it verifies a JWT.
The fetch accepts http and https only, follows no redirect, waits 5 seconds for each operation and 10 seconds in total, and reads 64 KiB at most.
The Fetch client URLs at private addresses setting of Server controls the addresses.
It is off by default: the server refuses jwks_uri URLs that resolve to private, loopback or link-local addresses.
Switch it on to let a client on localhost work.
The setting is outbound_private_addresses in the configuration document.
The web interface has no authentication. Anyone who reaches it can read the client secrets, export a snapshot, and replace the configuration, the personas and the clients. Only expose the server to people who may change it.
The auth-server-playground command uses the Flask development server.
It is enough for local tests.
For a public deployment, install the granian extra and serve the application with Granian:
uv sync --extra granian
uv run granian --interface wsgi --factory --host 0.0.0.0 --port 3000 --env-files .env auth_server_playground:create_app--workers sets the number of worker processes.
Behind a reverse proxy or a load balancer, enable the proxy support:
export PROXY_FIX=trueThe server then trusts the X-Forwarded-Proto and X-Forwarded-Prefix headers set by the closest proxy.
When the proxy handles TLS, the server sees HTTPS requests and accepts them.
Under a sub-path, the redirections start with the path prefix.
The server also trusts X-Forwarded-For, which only changes the client address in the logs.
Only enable it when a proxy is present.
Without a proxy, clients could forge these headers.
The proxy must set X-Forwarded-Proto and forward the original Host header.
It must also set X-Forwarded-Prefix, or clear it when the server is at the root of the domain.
Otherwise clients could send their own prefix.
With nginx, at the root of the domain:
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Prefix "";
}Under a sub-path, the proxy removes the prefix from the request path and sends it in X-Forwarded-Prefix:
location /auth/ {
proxy_pass http://127.0.0.1:3000/;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Prefix /auth;
}Run the tests:
uv run pytestInstall the Git hooks that check the code style and the commit messages:
uv run prek installAfter a change to a translatable string, update the catalog, then translate the new strings in src/auth_server_playground/translations/fr/LC_MESSAGES/messages.po:
uv run prek run pybabel-extract --all-files
uv run pybabel update -i src/auth_server_playground/translations/messages.pot -d src/auth_server_playground/translationsThe front-end dependencies are listed in package.json and copied in src/auth_server_playground/static/vendor.
To update one, install the new version and copy its files:
npm install <PACKAGE>@<VERSION>
npm run vendorThe server is distributed under the BSD 3-Clause license. See LICENSE. It started from the example OAuth 2.0 server of Authlib.