OpenID Connect (OIDC) Cheat Sheet

Note: This cheat sheet also applies to OAuth 2.0.

Overview

OIDC is an authentication protocol. It is usually used to verify user identity via a 3rd party, e.g. use your Google / Facebook account to log into a ride hailing service. It is built upon OAuth 2.0, which is an authorization protocol.

Components

  • Client = the server that requests authentication
  • Provider = the server that does authentication
    • Endpoints = different URLs at the Provider to provide different services
      • Authorization Endpoint = provides authorization code, used in implicit flow (see below)
      • Token Endpoint = exchanges authorization codes for tokens
  • Token = a piece of data that contains user identity
    • JWT = a token consists of a JSON object and a signature, serialized with base64 encoding
  • Authorization Code = a temporary code used to exchange token

Authentication Flow

Implicit Flow

  • CLIENT directly send credentials to PROVIDER
  • PROVIDER sends back TOKEN to CLIENT

Implicit flow is used for scenarios where there are no back-end server. User gets authenticated directly from the front-end (usually the browser).

Authorization Code Flow

  • FRONT-END redirects user to PROVIDER login page
  • USER submits credentials
  • PROVIDER confirms consents of user
  • PROVIDER redirects user to preset URL with AUTHORIZATION CODE, thus BACK-END gains the code
  • BACK-END uses the code to get TOKEN from PROVIDER
See the source image

This is the common scenario where we see a 3rd party login page.

Authorization code is used to prevent front-end from gaining access to the token. Authorization code is opaque and may only used by back-end to get token. Token is stored at back-end.

PKCE (Proof Key for Code Exchange)

PKCE is a way to prevent replay attack in Authorization Code flow.

Authorization code may leak when:

  • Response from authorize endpoint is observed, or
  • Request to authorize endpoint is observed (after the fact e.g. in local logs, history or cache)

Attacker could use this code to exchange for token.

To prevent first case, send along a random string when requesting a code, send the random string again when exchanging the code for token. Authorization server is responsible for matching the string thus verify the identity of requester.

If the request to authorize endpoint is exposed, then the random string is also exposed. To prevent this from happening, when requesting a code, only the hash of the random string is sent, when exchanging code, the original string is sent, and the server will create a hash out of the string and verify the identity of requester.

The original random string is randomly chosen, and stored in memory, thus is unlikely to leak. The hash function has high entropy and is unlikely to clash. Currently PKCE standards specify SHA256 as the hash function.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s