m3k-auth - Integration Guide

m3k-auth supports parts of the OAuth 2.0 and OpenID Connect (OIDC) specifications. This page contains hints how you add clients and which parts of the spec are expected to work.

New clients must be administratively whitelisted before authorization is possible. You can request a new client_id from Markus Peröbner. Make sure you can fullfil the following restrictions before you ask to be whitelisted.

The OAuth 2.0 redirect_uri must use the https protocol and it must be an absolute URL.

Currently the following OAuth 2.0 scopes are supported:

• openid: This scope requests access to the OpenID Connect (OIDC) user identity information. You can expect sub to contain a persistent, human readable user identifier.

Authorization Code Flow

The supported grant types are authorization_code and refresh_token. The flow is:

1. Redirect the browser to /authorize with response_type=code, client_id, redirect_uri, and scope=openid.
2. The user authenticates. On success the browser is redirected to your redirect_uri with a code query parameter.
3. Your server exchanges the code for tokens by making a POST /token request.

Token Endpoint

POST /token — form-encoded body.

Authorization code grant parameters:

• grant_type=authorization_code
• code — the code received at your redirect URI
• redirect_uri — must match the one used in the authorization request
• client_id
• client_secret

Refresh token grant parameters:

• grant_type=refresh_token
• refresh_token

A successful authorization code response includes access_token, refresh_token, and id_token. A refresh token response issues a new access_token and refresh_token pair (token rotation).

ID Token

The id_token is an RS256-signed JWT. Its payload contains the following claims:

• iss — issuer URL
• sub — persistent, human-readable user identifier
• aud — your client_id
• iat — issued-at time (Unix timestamp)
• exp — expiry time (Unix timestamp)

The public key for verifying the signature is available at /.well-known/jwks.json (RS256, kid: "1").

UserInfo Endpoint

GET /userinfo — authenticate with Authorization: Bearer <access_token>. Returns a JSON object with the following claims:

• sub — user identifier (always present)
• name — full name, if available
• given_name — if available
• family_name — if available
• nickname — same as sub (always present)
• email — always present
• email_verified — always true
• locale — if available (default de-DE)

Token Lifetimes

• Authorization code: 30 minutes
• Access token: 1 hour
• Refresh token: 30 days

OpenID Configuration

The well-known description of the server can be found in the openid-configuration.