Skip to content

Instantly share code, notes, and snippets.

@aravindkumarsvg

aravindkumarsvg/oauth_parameters.md

Last active June 23, 2025 17:38
Show Gist options
  • Save aravindkumarsvg/0d9167592e2860511f0bcffeb1459680 to your computer and use it in GitHub Desktop.
Save aravindkumarsvg/0d9167592e2860511f0bcffeb1459680 to your computer and use it in GitHub Desktop.
Download ZIP
OAuth - different parameters
Raw
oauth_parameters.md

OAuth 2.0 Parameters and Possible Values

This document lists various parameters used in OAuth 2.0 flows, including possible values where applicable.

🔐 Authorization Request Parameters

Parameter Description Example / Possible Values
response_type Type of response expected code, token, id_token (OIDC)
client_id Client identifier issued by the auth server abc123, my-client-id
redirect_uri Callback URL https://example.com/callback
scope Space-separated list of scopes openid profile email, read write
state CSRF protection token xyz123securestate
code_challenge Base64URL-encoded challenge (for PKCE) e.g., E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
code_challenge_method Method used to create code_challenge plain, S256
prompt UI behavior control none, login, consent, select_account
login_hint Hint about the user [email protected], username
access_type Indicates if refresh token is needed online, offline
nonce (OIDC) Replay attack protection Random string
display Display mode page, popup, touch, wap
max_age (OIDC) Max authentication age (in seconds) 3600, 0
ui_locales Language preferences en, en fr, es-ES

🔁 Authorization Response Parameters

Parameter Description Example / Possible Values
code Authorization code SplxlOBeZQQYbYS6WxSbIA
access_token Access token 2YotnFZFEjr1zCsicMWpAA
token_type Type of token Bearer
expires_in Token validity in seconds 3600, 7200
refresh_token Refresh token tGzv3JOkF0XG5Qx2TlKWIA
id_token (OIDC) Identity token (JWT) JWT string
scope Authorized scopes read write, openid profile
state Echoed back from request xyz123securestate
error Error type access_denied, invalid_request
error_description Human-readable error info "User denied access"

🔄 Token Request Parameters

Parameter Description Possible Values / Example
grant_type Type of grant authorization_code, client_credentials, refresh_token, password
code Authorization code SplxlOBeZQQYbYS6WxSbIA
redirect_uri Must match original redirect URI https://example.com/callback
client_id Client ID abc123
client_secret Client secret s3cr3tV@lu3
code_verifier PKCE code verifier Same used to create code_challenge
refresh_token Token to obtain new access token tGzv3JOkF0XG5Qx2TlKWIA
username Resource owner's username [email protected]
password Resource owner's password passw0rd!
scope Requested scopes read write, openid

🪪 Token Response Parameters

Parameter Description Example
access_token Access token 2YotnFZFEjr1zCsicMWpAA
token_type Type of token Bearer
expires_in Seconds before expiration 3600
refresh_token Token to refresh access token tGzv3JOkF0XG5Qx2TlKWIA
id_token (OIDC) JWT with user identity info eyJ0eXAiOiJKV1QiLCJhbGciOiJI...
scope Scopes granted openid profile email
error Error code invalid_grant, unauthorized_client
error_description Description of the error "Invalid credentials"

🧨 Common Error Codes

Error Description
invalid_request Request missing required parameters or malformed
unauthorized_client Client not authorized to use the grant type
access_denied Resource owner denied the request
unsupported_response_type Unsupported response_type
invalid_scope Requested scope is invalid
server_error Authorization server encountered an unexpected error
temporarily_unavailable Server is temporarily down or overloaded

🧾 response_mode Parameter

The response_mode parameter specifies how the authorization server returns result parameters to the client.

It is primarily used in OpenID Connect and some OAuth 2.0 extensions to control how the response (e.g., code, access_token) is returned.

🔹 Supported Values

Value Description
query Response parameters are encoded into the URL query string.
fragment Response parameters are encoded into the URL fragment (after #), not sent to server.
form_post Response parameters are sent as form data via HTTP POST to the redirect_uri.
web_message Response is delivered via postMessage to a browser window or iframe (used in browser-based apps).
jwt (Experimental) Response is returned as a JWT (used in JARM - JWT Secured Authorization Response Mode).

🔹 Compatibility with response_type

response_type Default response_mode Allowed Modes
code query query, fragment, form_post, web_message, jwt
token fragment fragment, form_post, web_message, jwt
id_token fragment fragment, form_post, web_message, jwt
code id_token fragment fragment, form_post, web_message, jwt
code token fragment fragment, form_post, web_message, jwt
id_token token fragment fragment, form_post, web_message, jwt
code id_token token fragment fragment, form_post, web_message, jwt

✅ Use form_post to avoid leaking tokens in browser history or referer headers. ❌ Do not use fragment in server-only apps—it’s not accessible on the backend.

🔍 Minor Updates / Additions to Previous Parameters

Below are additions and corrections to make your previous OAuth parameter documentation more complete:

🔐 response_type Additional Values

Value Purpose / Flow
code Authorization Code Flow
token Implicit Flow
id_token OIDC Implicit Flow
code token Hybrid Flow
code id_token Hybrid Flow
id_token token Hybrid Flow
code id_token token Full Hybrid Flow

🧪 grant_type Additional Values

Value Description
authorization_code Standard web app flow
implicit Deprecated; tokens issued directly via browser (not secure)
password Resource Owner Password Credentials (ROPC) flow
client_credentials Server-to-server communication
refresh_token Used to renew tokens
urn:ietf:params:oauth:grant-type:device_code Device Authorization Grant
urn:ietf:params:oauth:grant-type:jwt-bearer JWT Assertion Grant (machine auth)

🛡️ token_type Values

Value Description
Bearer Most common, requires secure HTTPS
MAC Obsolete – used HMAC-signed requests
DPoP Demonstration of Proof of Possession (emerging)

🔐 scope Known Values (examples)

Value Description
openid Required for OpenID Connect
profile Basic profile information (OIDC)
email User’s email address (OIDC)
offline_access Request refresh token (OIDC)
read, write, admin Application-specific scopes

🌐 Other Notable Parameters

Parameter Description Example Values
nonce (OIDC) Prevent replay attacks Random string
ui_locales Language preferences en, fr, en-IN
display UI display mode page, popup, touch, wap
prompt Forces certain behavior in login flow none, login, consent, select_account
max_age Maximum time since last auth (in seconds) 3600, 0
claims (OIDC) Request specific user claims JSON object
request JWT that contains the full authorization request JWT string
request_uri URI referencing a hosted request JWT https://client.com/request.jwt

💡 Notes

  • PKCE is highly recommended for mobile/SPA applications using authorization_code flow.
  • Always validate the state value to prevent CSRF.
  • OIDC parameters are only used if OpenID Connect is implemented on top of OAuth 2.0.
  • OIDC adds many parameters beyond basic OAuth (e.g. nonce, id_token, claims).
  • Security-conscious apps should prefer response_mode=form_post and PKCE.
  • Support for some modes (like web_message, jwt) depends on the authorization server.

Misc

  • Oauth servers have .well-known path, which hosts the metadata. Check the oauth server's documentation
    • /.well-known/oauth-authorization-server
    • /.well-known/openid-configuration

📚 References

🔐 OpenID Connect vs OAuth 2.0 - Key Differences and OpenID Variations

OpenID Connect (OIDC) builds on top of OAuth 2.0 to add identity authentication. While OAuth is designed for authorization (access to resources), OIDC is built for authentication (proving user identity).

⚙️ Purpose & Use Case

Aspect OAuth 2.0 OpenID Connect (OIDC)
Primary Purpose Authorization (access control) Authentication (identity verification)
Main Use Case Granting access to APIs/resources Logging in users to client apps
Example Access user's Google Calendar Login with Google (social login)

📦 Tokens Issued

Token Type OAuth 2.0 OpenID Connect
Access Token ✅ Used to access protected APIs ✅ Same usage
Refresh Token ✅ For getting new access tokens ✅ Same usage
ID Token ❌ Not defined ✅ New JWT token with identity claims

🧾 Token Contents

Token OAuth 2.0 OpenID Connect
Access Token Opaque or JWT, no identity guarantees May still be opaque/JWT, but no identity info
ID Token ❌ Not available ✅ Always JWT, contains claims like email, sub, name, etc.

🔑 Endpoints

Endpoint Type OAuth 2.0 OpenID Connect
/authorize ✅ Present ✅ Present
/token ✅ Present ✅ Present
/userinfo ❌ Not defined in OAuth ✅ Defined
/introspect ✅ Optional ✅ Optional
/jwks_uri ❌ Not standard in OAuth ✅ For verifying ID token signature
/.well-known/openid-configuration ❌ Not defined ✅ Discovery mechanism for OP metadata

🧬 Scopes

Scope OAuth 2.0 OpenID Connect
scope=... Arbitrary scopes for resource APIs Must include openid to trigger OIDC
Special Scopes Defined by API provider openid, profile, email, address, phone, offline_access

👥 User Information

Feature OAuth 2.0 OpenID Connect
User Profile ❌ Not defined ✅ Via ID Token or /userinfo
Session Info ❌ No session-related details ✅ Includes auth_time, acr, amr, etc.
Multi-Login Support Depends on implementation ✅ Native support via prompt, max_age, id_token_hint

🔁 Authentication Flow

Flow Element OAuth 2.0 Only OpenID Connect
Client Auth Flow client_credentials, password Same (but not for authentication use)
Interactive Auth ❌ No direct support (needs extension) ✅ Built-in via response_type=code id_token, nonce, etc.
Nonce ❌ Not defined ✅ Required to prevent replay attacks
IDP Discovery ❌ Manual setup ✅ Dynamic discovery via .well-known/...

🔐 Security Enhancements (OIDC)

  • ID Token Signature Verification: Uses RS256 or ES256 signed JWTs
  • Nonce Parameter: Prevents replay attacks
  • Token Replay Detection: Using auth_time, nonce, and short-lived tokens
  • PKCE: Shared with OAuth 2.1+ and OIDC for public clients
  • ID Token Validation Rules:
    • iss, aud, exp, iat must match client expectations
    • nonce must be validated if sent

🏗️ Protocol Layers

Layer OAuth 2.0 OpenID Connect
Protocol Base Authorization Framework Built on OAuth 2.0
Extension Specs Device Code, JWT, Token Introspection OIDC Core, Discovery, Dynamic Client Reg, Session Mgmt

🧪 Developer Experience Differences

Feature OAuth 2.0 OpenID Connect
Dynamic Client Registration Optional, non-standard ✅ Supported by spec
Well-Known Config ❌ Manual setup ✅ Auto-discovery
JWT Usage Optional ✅ Required for ID Tokens
Logout Support ❌ Manual only ✅ End Session Endpoint (/logout)

🧭 Real-World Example Differences

Use Case OAuth 2.0 OpenID Connect
Logging into app with Google ❌ ✅
Accessing Google Drive API ✅ ❌
Authenticating user with Okta ❌ ✅
Getting user name/email from Microsoft login ❌ ✅

🧾 Summary

Category OAuth 2.0 OpenID Connect
Authentication? ❌ No ✅ Yes
Authorization? ✅ Yes ✅ Yes
ID Token? ❌ No ✅ Yes
User Profile Info? ❌ No ✅ Yes
Standard Discovery? ❌ No ✅ Yes

📌 OpenID Connect Parameter Concepts

This section describes the core OpenID Connect parameters, including where they are used and their purpose.

🔑 Authorization Endpoint Parameters

Parameter Required? Description
client_id ✅ Public identifier for the RP (client) issued by the OP.
response_type ✅ Determines the type of response. Common: code, id_token, token id_token.
redirect_uri ✅ The URI to which the user-agent is redirected after authentication. Must exactly match one of the registered URIs.
scope ✅ Must include openid. Optional: profile, email, address, phone, offline_access, etc.
state ✅ (recommended) Opaque value used to maintain request/response integrity and prevent CSRF attacks.
nonce ✅ (if id_token expected) Used to associate a client session with an ID token and to mitigate replay attacks.
prompt ❌ Specifies user interaction requirements: none, login, consent, select_account.
max_age ❌ Maximum allowable time (in seconds) since last user authentication.
login_hint ❌ Hints to the OP about the user (e.g., email or username) to pre-fill login fields.
acr_values ❌ Requested Authentication Context Class Reference values (e.g., password, MFA).
ui_locales ❌ Requested locale for the UI (e.g., en, fr, de).
idp ❌ (vendor-specific) Forces login via a specific Identity Provider (used in Okta/Auth0).
code_challenge ✅ (for PKCE) Used in public clients to prevent authorization code interception.
code_challenge_method ✅ (for PKCE) Usually S256 (recommended) or plain.

🔄 Token Endpoint Parameters

Parameter Required? Description
grant_type ✅ Type of grant. For OIDC: authorization_code, refresh_token.
code ✅ (for auth code flow) Authorization code received from the authorization endpoint.
redirect_uri ✅ Must match the URI used in the initial authorization request.
client_id ✅ Identifier of the client application.
client_secret ✅ (confidential clients only) Secret associated with the client ID. Not used for public clients.
code_verifier ✅ (for PKCE) Used to validate the code_challenge sent earlier.
refresh_token ✅ (for refresh) Used to obtain new access and ID tokens.

🧾 ID Token Claims

Claim Description
iss Issuer Identifier. Must match OP's discovery doc value.
sub Subject Identifier (unique user ID per OP per client).
aud Audience (your client ID). Must match exactly.
exp Expiration time (UNIX timestamp).
iat Issued At time.
nonce Must match nonce sent in the auth request.
auth_time Time when the user last authenticated.
acr Authentication Context Class Reference (e.g., urn:mace:incommon:iap:silver).
amr Authentication Methods References (e.g., pwd, mfa).
email, name, picture, etc. Optional claims included based on scopes.

🧬 UserInfo Endpoint

Accessed via the access token if scope included profile, email, etc.

  • Method: GET or POST
  • Authorization: Bearer <access_token>
  • Response: JSON object with user claims such as sub, name, email, email_verified, etc.
  • Endpoint is declared in the discovery document.

🧩 Discovery Endpoint (/.well-known/openid-configuration)

  • JSON document providing metadata about the OP
  • Includes:
    • issuer
    • authorization_endpoint
    • token_endpoint
    • userinfo_endpoint
    • jwks_uri
    • response_types_supported
    • subject_types_supported
    • id_token_signing_alg_values_supported

📚 Further Reading

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment