OAuth2 General Flow

• User Click Third Party Login on Client Web App.
• Client Web App redirect user to Auth Provider Login Page, and user login there.
• Auth Provider redirect back user to Client Web App with Authorization Code as part of URL search parameters.
• Client Web App use the code to fetch tokens from Auth Server from backend.
• Auth Server return Tokens.
  • Access Token or refresh token based on Auth providers implementation.
  • ID Token if using OpenID Connect
• Use Access Token for backend resources access.

Note:

• Auth Server would need the client web app URL in advance, so it will not redirect user to malicious location after they login.
• Authorization Code is extremely short living and one time only.
• Access token and Refresh token both are sensitive data, should never be exposed in URL.
• Access Token is usually short lived, is exchanged every time needed using Refresh Token.
• Refresh Token is long lived, and usually has rotating mechanism to extend.

OpenID Connect

One related concept is OpenID Connect, which is a simple identity layer on top of the OAuth 2.0 protocol. So when client exchange tokens using redirection code, the server also returns a ID Token, which contains user information. It also specifies a user info endpoint for fetching user information using access token.

OpenID Connect also specifies defines a schema for API endpoints discovery. The schema should be available on a “well-known” location. Taking Google’s well-known location as an example, it specified:

• Authorization Endpoint
• Token Endpoint
• Revocation Endpoint
• JWK Server Endpoint
• Type of claims and scopes

{
 "issuer": "https://accounts.google.com",
 "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
 "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
 "token_endpoint": "https://oauth2.googleapis.com/token",
 "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
 "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
 "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
 "response_types_supported": ["..."],
 "response_modes_supported": ["..."],
 "subject_types_supported": ["..."],
 "id_token_signing_alg_values_supported": ["..."],
 "scopes_supported": ["..."],
 "token_endpoint_auth_methods_supported": [
  "client_secret_post",
  "client_secret_basic"
 ],
 "claims_supported": ["..."],
 "code_challenge_methods_supported": ["..."],
 "grant_types_supported": ["..."]
}

PKCE

One vulnerability in the original OAuth2 flow is the authorization code might be stolen, and the attacker use it faster than client to exchange tokens. Proof Key for Code Exchange (PKCE) is a mechanism to prevent this, by letting client app create a challenge and verify that during token exchange.

• When redirect to auth provider login page:
  • Client generate a code_verifier and create an hash out of it.
  • Client send the hash as challenge as part of URL search parameters.
• After client app use the authorization code for token exchange:
  • Use code_verifier as part of request, and server will only redeem the token if the code challenge passed.