OAuth2 Flow

​

Basic Concepts of OAuth 2.0

• Authorization Server: Verifies the identity of the user and issues access tokens.
• Resource Server: The server that provides the protected resources (e.g., an API).
• Client: The application that wants to access the API.
• Resource Owner: The user who decides whether an application gets access to their resources.
• Access Token: A temporary token used for accessing the API.
• Refresh Token (optional): A long-term token used to renew an access token.

​

Grant Types

​

Authorization Code Flow (with or without PKCE)

• Use case: Web applications & mobile apps
• Security: Very high (tokens are managed only in the backend)

1. Redirect to Authorization Request: The application redirects the user to the authorization server’s login page. Here, the application specifies which permissions (scopes) it needs.
2. User Authentication and Consent: The user logs in to the authorization server and is asked whether they want to grant the application the requested access.
3. Receive Authorization Code: After successful authentication, the user is redirected back to the application. A one-time authorization code is passed.
4. Exchange Code for Access Token: The application sends the received code along with a secret key to the authorization server. If the request is valid, the server issues an access token.
5. Access Protected Resources: With the received access token, the application can now access protected APIs and retrieve data or perform actions on behalf of the user.

​

Proof Key for Code Exchange (PKCE)

• The client generates a random code verifier (a long, random string).
• From this, a code challenge is derived (a transformed version of the verifier, usually as a SHA-256 hash).
• When exchanging the authorization code for an access token, the client must send the original code verifier.
• The server verifies the challenge and only issues the access token if the values match.

​

Extensions of the Authorization Code Flow

1. Refresh Token for Long-term Access: To prevent the user from having to re-authenticate constantly, a refresh token can additionally be requested. This allows the application to obtain new access tokens without further user input. The scope offline is required for this.
2. ID Token for User Information (OpenID Connect): If the application also needs information about the logged-in user, an ID token can be requested. This is issued as a JWT (JSON Web Token) and contains, for example, the user ID, email address, or other identity attributes. The scope openid is required for this.
3. Scopes for Permission Control: The authorization process can be controlled through various scopes. These define which data or functions the user grants the application.

​

Example

1. User is redirected for authorization

GET https://oauth2.coreapi.io/oauth2/auth
    ?response_type=code
    &client_id=client123
    &redirect_uri=https://my-app.com/callback
    &scope=openid offline entitlements.read
    &state=randomString

2. User logs in The user is redirected to Fynn’s login form. After logging in, Fynn asks whether the application should be granted access.

GET https://my-app.com/callback?code=AUTH_CODE&state=randomString

3. Application exchanges the code for an access token The application now sends a POST request to the authorization server:

POST https://oauth2.coreapi.io/oauth2/token
Content-Type: application/x-www-form-urlencoded

client_id=client123
&client_secret=superSecret
&grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://my-app.com/callback

{
    "access_token": "...",
    "expires_in": 3600,
    "refresh_token": "...",
    "id_token": "...",
    "scope": "...",
    "token_type": "Bearer"
}

​

Refresh Token

POST https://oauth2.coreapi.io/oauth2/token
Content-Type: application/x-www-form-urlencoded

client_id=client123
&client_secret=superSecret
&grant_type=refresh_token
&refresh_token=abcd1234
&scope=offline openid entitlements.read

{
    "access_token": "...",
    "expires_in": 3600,
    "refresh_token": "...",
    "id_token": "...",
    "scope": "...",
    "token_type": "Bearer"
}

​

Scopes

​

OpenID Connect

​

ID Token

• sub (Subject) - Unique identifier of the user
• name - Full name of the user
• email - User’s email address
• iat (Issued At) - Time when the token was issued
• exp (Expiration) - Expiration time of the token
• iss (Issuer) - Identity provider (IdP) that issued the token
• aud (Audience) - The target application for which the token is intended

{
  iss: "https://oauth2.coreapi.io",
  sub: "some-identity-id",
  aud: "some-client-id",
  exp: 1311281970,
  iat: 1311280970,
  nonce: "KxSty13b2L",
  name: "Jane Doe",
  given_name: "Jane",
  family_name: "Doe",
  email: "jane@example.org",
  email_verified: true,
}

​

Validating ID Token (JWK)

​

OpenID Connect Logout

​

OpenID Connect Front-Channel Logout 1.0

• When a user logs out, Fynn redirects the user agent (browser) to the registered Logout URI.
• The OAuth2 client application can then also log the user out in your own system, e.g., by:
  • Deleting an authentication cookie
  • Invalidating the user session

​

OpenID Connect Back-Channel Logout 1.0

• iss (Issuer) - Identifier of the issuing OpenID provider: https://oauth2.coreapi.io or https://oauth2.preview.coreapi.io
• aud (Audience) - The client ID of the OAuth2 client for which this logout token is intended.
• iat (Issued At) - Time when the token was issued. Can be used to determine the age of the token.
• jti (JWT ID) - Unique identifier of the JWT to prevent replay attacks. The token should only be used once.
• events - Contains the entry http://schemas.openid.net/event/backchannel-logout. This declares that the JWT is a logout token. The corresponding value MUST be a JSON object and SHOULD be (empty JSON object).
• sid (Session ID) - A session ID that links a specific session to an ID token. This is passed as a parameter during the logout call.