Integrate MemoID with OAuth 2.0 and OpenID Connect. Start with architecture, then follow the request and token flow, verify callbacks and handle sign-out.
issuer: https://id.memolab.me flow: Authorization Code + PKCE S256 grants: authorization_code, refresh_token client auth: Basic | post | private_key_jwt | none advanced: PAR | DPoP
Use sub as the permanent MemoID identity key. Keep roles, teams, tenant membership, subscription entitlements and business permissions inside the destination application. This separation limits the impact of identity-layer mistakes and keeps business authorization explicit.
The most important design decision is where secrets and tokens are allowed to exist. Treat the browser and distributed client applications as environments that users, extensions, malware or reverse engineering may inspect. Put confidential credentials and long-lived tokens on a trusted backend whenever your architecture allows it.
state per transaction · nonce for OIDC · exact redirect URI · JWKS validation · server-side secrets · refresh rotation
Use this model during architecture review: anything crossing from an untrusted client into a trusted backend must be validated rather than assumed to be authentic.
A Client Secret is useful only when the runtime can actually keep it secret. Copying a secret into JavaScript, a mobile binary or desktop package does not make that client confidential.
Prefer a Confidential client. Exchange codes and hold refresh tokens server-side. Give the browser only your own Secure, HttpOnly application session cookie.
Use a Public client when there is no trusted backend. Do not invent a frontend Client Secret. Keep token lifetime and browser exposure small; a BFF is preferable for high-value applications.
Use a Public client with PKCE. Register redirect destinations precisely and prefer platform-supported verified links or secure application callback mechanisms where available.
Most integration failures are configuration mismatches. Confirm client type, exact redirect destinations, scopes and token-endpoint authentication method before debugging application code.
Choose Public or Confidential from the architecture above. Record the Client ID and, only for confidential clients, protect the issued Client Secret immediately.
Scheme, host, port and path must match. Use HTTPS in production and keep callback endpoints dedicated to authentication rather than general-purpose redirects.
Document where Client Secret, private keys, PKCE verifier, access tokens and refresh tokens may be stored. This prevents accidental movement of secrets into frontend code later.
Configure the issuer as the stable trust anchor and let a standards-compliant OIDC library discover endpoint URLs, supported client-authentication methods, signing algorithms and capabilities. This makes key and capability rotation operationally safer.
https://id.memolab.mehttps://id.memolab.me/.well-known/openid-configurationhttps://id.memolab.me/.well-known/jwks.jsonauthorization_code refresh_tokenopenid profile email offline_accessThe browser carries the user through authorization. Your application creates and validates transaction state. MemoID authenticates the user and issues a one-time code. The trusted client exchanges that code and verifies the returned identity before creating an application session.
Green-lined rows are security checks, not optional implementation details.
state + nonce + code_verifier → code_challengeGET /oauth/authorize?...&code_challenge=...error? → state equal? → code present?code + redirect_uri + code_verifier + client authsignature + iss + aud + exp + nonce → subGenerate cryptographically random state and nonce, plus a PKCE verifier. Never reuse transaction values across sign-ins.
Send the browser to /oauth/authorize, or use PAR first when you need server-side request registration or the client requires PAR.
Handle OAuth error, verify state, ensure the transaction exists and has not already completed, then continue to token exchange.
Send code with the original verifier and redirect URI. Validate the ID token using JWKS or a compliant OIDC library.
Map sub to your own account and authorization model. Do not grant business roles merely because authentication succeeded.
The callback URL is reachable from the public internet. Do not assume its query parameters are genuine simply because they contain a MemoID-looking code. Build an explicit validation gate and reject the transaction before token exchange when any required check fails.
A useful implementation pattern is to make each security decision explicit and observable without logging the secret values themselves.
A callback that fails a security binding should be terminated. Do not silently regenerate state, ignore nonce, swap redirect_uri, or retry a used code.
state mismatch → possible forged/mixed transactioninvalid_grant → restart from authorizationnonce mismatch → reject identity resultstate · Bind response to requestGenerate per transaction and verify before token exchange.
PKCE · Bind code to client instanceKeep code_verifier private until token exchange; send only its S256 challenge to authorization.
nonce · Bind ID token to sign-inVerify the returned ID token nonce against the stored transaction value.
ID token · Verify issuer identityVerify signature via JWKS plus issuer, audience, expiration and required claims.
An ID token proves an authentication result to the client. An access token authorizes calls to a resource. A refresh token can mint future access and therefore deserves the strongest storage and rotation controls.
MemoID rotates refresh tokens. Your storage update and request concurrency must respect single-use semantics.
Stored securely and used once.
Persist B atomically. A becomes invalid.
Reuse detection revokes the token family.
| Value | Browser-readable storage | Trusted backend | Recommendation |
|---|---|---|---|
| Client ID | Allowed | Allowed | Not a secret. |
| Client Secret / private key | Never | Secret storage | Rotate and restrict access. |
| PKCE verifier | Short-lived only when architecture requires | Preferred | Delete after exchange. |
| Access token | Minimize exposure | Preferred | Do not log or put in URL. |
| Refresh token | Avoid | Strongly preferred | Encrypt/protect at rest and rotate atomically. |
| Application session cookie | Cookie sent by browser | Server validated | Secure; HttpOnly; SameSite |
Security controls are easier to review when each one maps to a concrete threat. The list below is a practical baseline for code review and architecture review.
Control: state per transaction + callback binding
Never continue when state is missing or different.
Control: PKCE S256
An intercepted code is insufficient without the verifier.
Control: exact redirect URI registration
Keep authentication callbacks dedicated and exact.
Control: single-use rotation + family revocation
Serialize refresh updates and replace the stored token atomically.
Control: trusted backend + secret manager
Never ship a confidential credential to browser/mobile code.
Control: structured redaction
Log event type, result and correlation IDs—not raw tokens or secrets.
For each endpoint, understand not only the request shape but also which component should call it, which values are sensitive, and which response properties your application must verify.
Machine-readable protocol metadata. Use it to discover endpoints and capabilities rather than duplicating them in source code.
https://id.memolab.me/.well-known/openid-configuration
Public signing keys for verifying MemoID JWT signatures. Select keys by kid and support rotation.
https://id.memolab.me/.well-known/jwks.json
Browser endpoint for authentication, application-entry checks and consent. It returns a one-time authorization code to the exact registered callback.
| Parameter | Requirement | Where | Type | Meaning and security purpose | Example |
|---|---|---|---|---|---|
response_type | Required | query | enum | Use code. MemoID advertises Authorization Code flow and does not advertise implicit, password or client-credentials grants. | code |
client_id | Required | query | string | Public identifier of the registered application. This is not a password and may appear in browser URLs. | memo-app-prod |
redirect_uri | Required | query | absolute URL | Exact callback destination. MemoID compares it against registered Redirect URIs; do not generate broad wildcard or open-redirect destinations. | https://app.example.com/auth/memoid/callback |
scope | Required | query | space-separated | Requested identity permissions. openid is mandatory; request only profile/email/offline_access your product actually needs. | openid profile email |
state | Required | query | high-entropy string | Per-transaction value used to bind the callback to the request. Store server-side or in protected short-lived state and compare before token exchange. | q4M8... |
nonce | Conditional | query | high-entropy string | Value bound into the ID token. Required when the MemoID client configuration requires nonce and recommended for OIDC sign-in. | n-0S6... |
code_challenge | Required | query | 43–128 chars | Base64URL-encoded SHA-256 digest of the original code_verifier. It prevents an intercepted authorization code from being redeemed without the verifier. | E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM |
code_challenge_method | Required | query | enum | MemoID requires S256. Do not use plain PKCE. | S256 |
prompt | Optional | query | string | Use none only for non-interactive SSO checks. If no MemoID browser session exists, the callback receives login_required. | none |
request_uri | Optional | query | URN | One-time PAR reference. It expires quickly and is consumed once, reducing exposure of full authorization parameters in the browser URL. | urn:ietf:params:oauth:request_uri:par_... |
https://id.memolab.me/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fapp.example.com%2Fauth%2Fmemoid%2Fcallback&scope=openid%20profile%20email&state=RANDOM_STATE&nonce=RANDOM_NONCE&code_challenge=BASE64URL_SHA256_VERIFIER&code_challenge_method=S256
?code=...&state=... on success; OAuth error parameters on failure. Always validate state in both paths.Pre-register authorization parameters through a direct HTTP request and receive a one-time request_uri that expires in 90 seconds.
| Parameter | Requirement | Where | Type | Meaning and security purpose | Example |
|---|---|---|---|---|---|
response_type | Required | form | enum | Use code. MemoID advertises Authorization Code flow and does not advertise implicit, password or client-credentials grants. | code |
client_id | Required | form | string | Public identifier of the registered application. This is not a password and may appear in browser URLs. | memo-app-prod |
redirect_uri | Required | form | absolute URL | Exact callback destination. MemoID compares it against registered Redirect URIs; do not generate broad wildcard or open-redirect destinations. | https://app.example.com/auth/memoid/callback |
scope | Required | form | space-separated | Requested identity permissions. openid is mandatory; request only profile/email/offline_access your product actually needs. | openid profile email |
state | Required | form | high-entropy string | Per-transaction value used to bind the callback to the request. Store server-side or in protected short-lived state and compare before token exchange. | q4M8... |
nonce | Conditional | form | high-entropy string | Value bound into the ID token. Required when the MemoID client configuration requires nonce and recommended for OIDC sign-in. | n-0S6... |
code_challenge | Required | form | 43–128 chars | Base64URL-encoded SHA-256 digest of the original code_verifier. It prevents an intercepted authorization code from being redeemed without the verifier. | E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM |
code_challenge_method | Required | form | enum | MemoID requires S256. Do not use plain PKCE. | S256 |
prompt | Optional | form | string | Use none only for non-interactive SSO checks. If no MemoID browser session exists, the callback receives login_required. | none |
client authentication | Conditional | header/form | configured method | Identify/authenticate the client according to registration. The authenticated client is bound to the PAR object. | Authorization: Basic ... |
curl -X POST 'https://id.memolab.me/oauth/par' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -u 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \ --data-urlencode 'response_type=code' \ --data-urlencode 'redirect_uri=https://app.example.com/auth/memoid/callback' \ --data-urlencode 'scope=openid profile email' \ --data-urlencode 'state=RANDOM_STATE' \ --data-urlencode 'nonce=RANDOM_NONCE' \ --data-urlencode 'code_challenge=BASE64URL_SHA256_VERIFIER' \ --data-urlencode 'code_challenge_method=S256'
{
"request_uri": "urn:ietf:params:oauth:request_uri:par_...",
"expires_in": 90
}Issues token sets for authorization_code and refresh_token grants. This endpoint is a high-value security boundary because it handles one-time codes, client credentials and long-lived refresh access.
| Parameter | Requirement | Where | Type | Meaning and security purpose | Example |
|---|---|---|---|---|---|
grant_type | Required | form | enum | authorization_code exchanges a one-time code; refresh_token rotates a valid refresh token into a new token set. | authorization_code |
client_id | Conditional | form/auth | string | Required directly for public clients and client_secret_post. Other client-auth methods may identify the client through the authentication material. | memo-app-prod |
client_secret | Conditional | form | secret | Only for confidential clients configured for client_secret_post. Never expose this value to browser JavaScript or mobile bundles. | mcs_... |
client_assertion_type | Conditional | form | string | Required with private_key_jwt and must use the OAuth JWT bearer assertion type URI. | urn:ietf:params:oauth:client-assertion-type:jwt-bearer |
client_assertion | Conditional | form | signed JWT | Short-lived JWT signed by the client's registered private key. iss=sub=client_id, aud must be the exact endpoint URL, and jti is replay-protected. | eyJ... |
code | Conditional | form | one-time string | Required for authorization_code. A code that is expired, already used, belongs to another client or uses different redirect data is rejected. | mac_... |
redirect_uri | Conditional | form | absolute URL | Required for authorization_code and must match the same registered redirect used to create the code. | https://app.example.com/auth/memoid/callback |
code_verifier | Conditional | form | 43–128 chars | Original PKCE secret. It must hash to the code_challenge from the authorization request. Treat it as transaction-sensitive data until exchange completes. | dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk |
refresh_token | Conditional | form | secret | Required for refresh_token grant. A successful refresh returns a replacement refresh token; persist the new value atomically and never reuse the old one. | mrt_... |
DPoP | Conditional | header | signed JWT | Proof-of-possession header for DPoP-enabled clients. When a token is bound to a DPoP key, later resource calls must prove possession of the same key. | DPoP: eyJ... |
curl -X POST 'https://id.memolab.me/oauth/token' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -u 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'code=ONE_TIME_AUTHORIZATION_CODE' \ --data-urlencode 'redirect_uri=https://app.example.com/auth/memoid/callback' \ --data-urlencode 'code_verifier=ORIGINAL_PKCE_VERIFIER'
curl -X POST 'https://id.memolab.me/oauth/token' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -u 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'refresh_token=CURRENT_REFRESH_TOKEN'
{
"token_type": "Bearer",
"access_token": "eyJ...",
"expires_in": 900,
"id_token": "eyJ...",
"refresh_token": "mrt_...",
"scope": "openid profile email offline_access"
}Returns claims for the account represented by the access token. Returned fields depend on granted scopes.
| Parameter | Requirement | Where | Type | Meaning and security purpose | Example |
|---|---|---|---|---|---|
Authorization | Required | header | Bearer or DPoP | Use Bearer for normal access tokens. DPoP-bound tokens must use the DPoP scheme. | Bearer eyJ... |
DPoP | Conditional | header | signed JWT | Required for DPoP-bound tokens; the proof key must match the cnf binding. | eyJ... |
curl 'https://id.memolab.me/oauth/userinfo' \ -H 'Authorization: Bearer ACCESS_TOKEN'
{
"sub": "usr_...",
"name": "Example User",
"picture": "https://...",
"locale": "th",
"email": "user@example.com",
"email_verified": true
}Invalidates an access or refresh token owned by the authenticated client. The endpoint deliberately returns 200 even for unknown tokens to avoid token-validity probing.
| Parameter | Requirement | Where | Type | Meaning and security purpose | Example |
|---|---|---|---|---|---|
token | Required | form | string | Access or refresh token to revoke. Treat the value as secret in transport and logs. | mrt_... |
token_type_hint | Optional | form | enum | RFC 7009 compatibility hint. MemoID can identify the token without trusting this hint. | refresh_token |
client authentication | Required | header/form | configured method | Authenticate the token-owning client. | Authorization: Basic ... |
curl -X POST 'https://id.memolab.me/oauth/revoke' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -u 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \ --data-urlencode 'token=TOKEN_TO_REVOKE' \ --data-urlencode 'token_type_hint=refresh_token'
Trusted server-side endpoint that reports whether an access or refresh token is active.
| Parameter | Requirement | Where | Type | Meaning and security purpose | Example |
|---|---|---|---|---|---|
token | Required | form | string | Token to inspect. Do not log it. | eyJ... |
token_type_hint | Optional | form | string | Compatibility hint; not relied upon for trust decisions. | access_token |
client authentication | Required | header/form | configured method | Authenticate before disclosing token state. | Authorization: Basic ... |
curl -X POST 'https://id.memolab.me/oauth/introspect' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -u 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \ --data-urlencode 'token=TOKEN_TO_INSPECT'
{
"active": true,
"client_id": "memo-app-prod",
"sub": "usr_...",
"scope": "openid profile email",
"exp": 1780000000,
"token_type": "access_token"
}RP-initiated browser logout. Clear your application's own local session first, then redirect here when the shared MemoID SSO session should also end.
| Parameter | Requirement | Where | Type | Meaning and security purpose | Example |
|---|---|---|---|---|---|
id_token_hint | Optional | query | ID token | Previously issued ID token used to identify the client context. MemoID validates it before trusting its audience. | eyJ... |
client_id | Conditional | query | string | Required with post_logout_redirect_uri unless id_token_hint already identifies the client. | memo-app-prod |
post_logout_redirect_uri | Optional | query | absolute URL | Must exactly match a registered post-logout URI. Never accept an arbitrary destination from the user. | https://app.example.com/login |
state | Optional | query | string | Application-generated logout transaction value returned after redirect; verify it after return. | logout_... |
https://id.memolab.me/oauth/logout?id_token_hint=LAST_ID_TOKEN&post_logout_redirect_uri=https%3A%2F%2Fapp.example.com%2Flogin&state=RANDOM_LOGOUT_STATE
MemoID Discovery advertises client_secret_basic, client_secret_post, private_key_jwt and none. The correct choice depends on whether the runtime can protect a shared secret or private key.
For Public clients. Send client_id and rely on PKCE S256 rather than pretending a distributed secret is confidential.
Preferred shared-secret method for many Confidential clients. The secret travels in the Authorization header over HTTPS.
Compatibility method that places the secret in the form body. It works, but request-body logging becomes a significant operational risk.
Asymmetric client authentication. The private key stays with the client; MemoID verifies short-lived signed assertions against registered JWKs.
iss = sub = client_idaud = exact endpoint URLexp - iat ≤ 300sjti replay protectedScopes are both an authorization request and a data-minimization boundary. Asking for less reduces consent complexity, downstream data exposure and incident impact.
openidRequired for OIDC identity. Establishes the signed-in subject and enables an ID token.
sub = stable MemoID identityprofileRequests basic profile presentation data.
namepicturelocaleemailRequests email plus verification state. Email can change and should not replace sub as the identity key.
emailemail_verifiedoffline_accessRequests refresh access. This materially increases credential lifetime and storage responsibility, so request it only when the product needs background or long-lived access.
These names are recommendations for the consuming application. Separate development, staging and production clients so secrets, callbacks and incidents do not cross environments.
MEMOID_ISSUER=https://id.memolab.me MEMOID_CLIENT_ID=your-client-id MEMOID_CLIENT_SECRET=server-side-secret-only MEMOID_REDIRECT_URI=https://app.example.com/auth/memoid/callback MEMOID_POST_LOGOUT_REDIRECT_URI=https://app.example.com/login MEMOID_SCOPES=openid profile email offline_access MEMOID_AUDIENCE=https://api.example.com
MEMOID_ISSUERStable trust anchor used for Discovery and issuer validation.
MEMOID_CLIENT_IDPublic application identifier; safe to expose when required.
MEMOID_CLIENT_SECRETsecretConfidential clients only. Server-side secret storage; never NEXT_PUBLIC_*.
MEMOID_REDIRECT_URIExact authorization callback registered in MemoID.
MEMOID_POST_LOGOUT_REDIRECT_URIExact allowed return destination after logout.
MEMOID_SCOPESSpace-separated minimum scopes required by the product.
MEMOID_AUDIENCEOptional resource/API audience when configured for the client.
OAuth errors are protocol outcomes. Preserve enough non-secret context to diagnose them, terminate invalid transactions and give the user a deliberate way to restart sign-in.
invalid_requestMissing or inconsistent parameters, unregistered redirect URI or missing PKCE S256.
invalid_clientClient is unknown/disabled or client authentication does not match registration.
invalid_grantCode/refresh token is expired, used, revoked, mismatched or access is no longer allowed.
invalid_scopeopenid missing or requested scope not allowed for the client.
access_deniedAccount cannot enter the app or authorization was denied. Do not auto-loop.
login_requiredprompt=none had no active MemoID session; restart interactively.
invalid_request_uriPAR request_uri expired, reused, invalid or client-mismatched.
invalid_dpop_proofDPoP proof is missing, invalid or bound to a different key/token.
temporarily_unavailableRate limiting or temporary service protection; retry with bounded exponential backoff.
server_errorUnexpected server failure. Do not expose stack traces or secrets to users.
Production security depends on logging, monitoring, rotation and incident procedures as much as protocol correctness. Design observability so operators can diagnose failures without seeing raw credentials.
Log event type, endpoint, client_id, result, HTTP status, safe correlation ID and coarse timing. Redact Authorization headers, cookies, codes, assertions, access tokens and refresh tokens.
Define owners, rotation cadence, overlap period and rollback. Test rotation before an incident; emergency rotation should be a rehearsed operation, not an improvised deployment.
Use bounded retries with jitter for temporary failures. Do not retry invalid_grant, state mismatch or access_denied automatically because those require a new transaction or user action.
Be able to disable a client, rotate secrets/keys, revoke tokens, invalidate local sessions and identify affected users without exporting raw token material.
A development login that works is not evidence of production security. Exercise failure, rotation and concurrency paths before launch.