Quickstart: authorization code with PKCE
Connect to M7 Identity
Issuer: https://sso.user.m7.org
Discovery JSON: https://sso.user.m7.org/.well-known/openid-configuration
- Discovery and signing keys
- Integration quickstart
- Provider profile
- M7 Identity SDK and current downloads
Live discovery supplies endpoint locations and advertised capabilities. Use the provider profile for the integration contract and current testing status.
Use authorization code flow with PKCE for every user-facing application:
server-rendered web apps, browser-based backends, native apps, and SPAs.
M7 requires PKCE for this flow and accepts only the exact method S256.
plain, a missing method, and unknown methods are rejected.
Before starting, register an OAuth client with an exact HTTPS redirect URI. You can use the registration endpoint or manage the client through the M7 User API.
1. Create state and PKCE values
For each sign-in attempt, generate:
state: a high-entropy, single-use value stored with the user's browser session. M7 requires it on authorization requests and returns it unchanged.code_verifier: a high-entropy secret retained only by your application.code_challenge: base64url-encoded SHA-256 of the verifier, without padding.nonce: recommended when requestingopenid; validate the returned value in the ID token.
Example shell commands for illustration only:
CODE_VERIFIER="$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n')"
CODE_CHALLENGE="$(printf %s "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')"
STATE="$(openssl rand -hex 32)"
NONCE="$(openssl rand -hex 32)"
Keep the verifier and state server-side or in a platform-protected native-app store. They are not values to expose in URLs, logs, analytics, or referrer headers.
2. Redirect the browser to M7
Build a GET request to https://sso.user.m7.org/authorize:
https://sso.user.m7.org/authorize?
client_id=YOUR_CLIENT_ID&
redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback&
response_type=code&
scope=openid%20profile%20email&
state=STATE&
nonce=NONCE&
code_challenge=CODE_CHALLENGE&
code_challenge_method=S256
Use a top-level browser navigation. M7 handles sign-in, account selection, and
any required user interaction. This quickstart uses the default query mode.
For popup or approved iframe sign-in, use the separate
Web Message setup.
See Authorization requests for the complete parameter reference and PAR if you do not want authorization parameters in the browser URL.
3. Validate the callback
After approval, M7 redirects to the exact registered redirect_uri with query
parameters like:
https://app.example.com/oauth/callback?code=AUTHORIZATION_CODE&state=STATE
Before using the code:
- Verify the returned
stateis exactly the one associated with this browser session. - Require exactly one terminal shape:
codeorerror, never both or neither. - If the callback contains
error, do not exchange a code. Useerroranderror_reasonfor program behavior; do not parseerror_description. - Treat unknown error or reason values as a terminal authorization failure, never as success.
- Do not expose the code, state, or raw callback URL to application logs, analytics, screenshots, or telemetry.
Authorization codes are short-lived and single-use.
Read Authorization callback outcomes for the complete success and error contract, including cancellation, interaction-required, policy, configuration, protocol, and retryable server outcomes.
A user cancellation can return:
https://app.example.com/oauth/callback?error=access_denied&error_reason=login_cancelled&error_description=login_cancelled&state=STATE
A non-interactive request that needs sign-in can return:
https://app.example.com/oauth/callback?error=login_required&error_reason=session_required&state=STATE
Validate state before classifying either result. Start a fresh interactive
authorization request after login_required; do not call /token for either
error.
4. Exchange the code at /token
Make a server-to-server POST request. A public client sends its client_id;
a confidential client authenticates using its registered method.
curl --fail-with-body --silent --show-error \
--request POST 'https://sso.user.m7.org/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--user "CLIENT_ID:CLIENT_SECRET" \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=AUTHORIZATION_CODE' \
--data-urlencode 'redirect_uri=https://app.example.com/oauth/callback' \
--data-urlencode 'code_verifier=CODE_VERIFIER'
redirect_uri must exactly match both the registered URI and the URI used in
the authorization request. For the full client-authentication and response
contract, see Token endpoint.
A successful package includes an access token, expiry, granted scope, and normally the M7 refresh material:
{
"token_type": "Bearer",
"access_token": "ACCESS_TOKEN",
"expires_in": 900,
"refresh_token": "REFRESH_TOKEN",
"refresh_expires_in": 2592000,
"binding_chain": "BINDING_CHAIN",
"binding_link": "BINDING_LINK",
"scope": "openid profile email",
"id_token": "ID_TOKEN"
}
id_token is returned when the granted scope includes openid. Actual
lifetimes and optional fields are controlled by the client and service policy.
Persist the complete refresh package atomically and protect every credential
field, not only refresh_token. This example is unbound. A DPoP-bound access
token is returned with token_type: "DPoP"; branch on that exact value and
retain the corresponding private key.
5. Retrieve claims and use the access token
For the unbound Bearer response shown above, call /userinfo with the access
token. M7 derives the owning OAuth client from the validated token:
curl --fail-with-body --silent --show-error \
--header 'Authorization: Bearer ACCESS_TOKEN' \
'https://sso.user.m7.org/userinfo'
See UserInfo and scopes for returned claims. Verify an ID
token before trusting it; see Discovery and signing keys.
If /token returned DPoP, use the DPoP authorization scheme plus one fresh
UserInfo proof documented in the UserInfo guide. M7 creates any required
internal downstream attestations; clients do not send them.
Production checklist
- Use an exact HTTPS redirect URI; no wildcards or partial matching.
- Generate and validate
statefor every browser authorization. - Use PKCE
S256and retain the verifier until the exchange succeeds or expires. - Keep code exchange and client secrets off the browser for confidential clients.
- Persist a replacement refresh package before discarding the prior one.
- Follow the returned
token_type: useAuthorization: Bearerfor an unbound token and the documented resource-specific DPoP contract for a bound token. Review the complete authorization and credential lifecycle before storing or refreshing credentials.
Add an organization selector
Register orgs for your consumer client, include it in the hosted authorization
scope string (for example openid profile email orgs), and obtain consent.
Then resolve m7_orgs_endpoint and make a separate
org discovery request. Keep the existing PKCE/state/nonce,
client/token policy, exact endpoint DPoP and certificate bindings. For CLI or
native clients, explicitly request orgs and complete
device consent. For websites, use
SDK website acquisition
and check its current-source installation requirement before enabling it.