OAuth 2.0 & OpenID Connect

OAuth 2.0 Roles

OAuth 2.0 defines four distinct roles:

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
graph LR
    style A fill:#4CAF50,color:#fff
    style B fill:#2196F3,color:#fff
    style C fill:#FF9800,color:#fff
    style D fill:#9C27B0,color:#fff

    A[Resource Owner<br/>End User] -->|Grants consent| B[Client<br/>Application]
    B -->|Requests token| C[Authorization Server<br/>Issues Tokens]
    C -->|Issues access token| B
    B -->|Presents token| D[Resource Server<br/>Protected API]
    D -->|Returns resource| B

Grant Types

Authorization Code Grant (+ PKCE)

The most secure and recommended grant for web apps, SPAs, and mobile applications. PKCE (Proof Key for Code Exchange) prevents authorization code interception attacks.

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
sequenceDiagram
    autonumber
    participant U as User (Browser)
    participant C as Client App
    participant AS as Authorization Server
    participant RS as Resource Server

    rect rgb(232, 245, 233)
    Note over U,AS: Authorization Phase
    U->>C: Click "Login with Provider"
    C->>C: Generate code_verifier + code_challenge (PKCE)
    C->>AS: GET /authorize?response_type=code<br/>&client_id=X&redirect_uri=Y<br/>&state=Z&code_challenge=CH
    AS->>U: Display login + consent screen
    U->>AS: Enter credentials + approve
    AS->>C: Redirect to callback with ?code=ABC&state=Z
    end

    rect rgb(227, 242, 253)
    Note over C,RS: Token Exchange Phase
    C->>AS: POST /token {code=ABC, code_verifier=CV}
    AS->>AS: Verify code_challenge matches hash(code_verifier)
    AS->>C: {access_token, refresh_token, id_token}
    C->>RS: GET /api/resource (Authorization: Bearer token)
    RS->>C: Protected resource data
    end

Key points:

• The state parameter prevents CSRF attacks
• PKCE replaces the need for a client secret in public clients (SPAs, mobile)
• The authorization code is short-lived and single-use
• Tokens are never exposed in the browser URL

Client Credentials Grant

Used for service-to-service communication where no user context is needed (machine-to-machine).

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
sequenceDiagram
    autonumber
    participant S as Service A<br/>(Client)
    participant AS as Authorization Server
    participant RS as Service B<br/>(Resource Server)

    rect rgb(255, 243, 224)
    Note over S,RS: Machine-to-Machine Flow
    S->>AS: POST /token<br/>{grant_type=client_credentials,<br/>client_id=X, client_secret=Y,<br/>scope=read:data}
    AS->>AS: Validate client credentials
    AS->>S: {access_token, expires_in=3600}
    S->>RS: GET /api/internal-data<br/>Authorization: Bearer token
    RS->>RS: Validate token + check scopes
    RS->>S: Response data
    end

Use cases: Microservice communication, batch jobs, cron tasks, CI/CD pipelines.

Device Code Grant

Designed for devices with limited input capability (smart TVs, IoT, CLI tools).

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
sequenceDiagram
    autonumber
    participant D as Device<br/>(Smart TV)
    participant AS as Authorization Server
    participant U as User<br/>(Phone/Laptop)

    rect rgb(243, 229, 245)
    Note over D,U: Device Authorization Flow
    D->>AS: POST /device/code<br/>{client_id=X, scope=Y}
    AS->>D: {device_code, user_code="ABCD-1234",<br/>verification_uri="https://auth.example.com/device"}
    D->>D: Display: "Go to URL, enter code ABCD-1234"

    U->>AS: Navigate to verification_uri
    AS->>U: Prompt for user_code
    U->>AS: Enter "ABCD-1234" + login + consent

    loop Poll every 5 seconds
        D->>AS: POST /token<br/>{grant_type=device_code, device_code=DC}
        AS->>D: {error: "authorization_pending"}
    end

    Note over U,AS: User completes authorization
    D->>AS: POST /token {grant_type=device_code, device_code=DC}
    AS->>D: {access_token, refresh_token}
    end

Refresh Token Flow

Allows obtaining a new access token without re-authenticating the user.

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
sequenceDiagram
    autonumber
    participant C as Client
    participant AS as Authorization Server
    participant RS as Resource Server

    rect rgb(232, 234, 246)
    Note over C,RS: Token Refresh Cycle
    C->>RS: GET /api/resource (expired access_token)
    RS->>C: 401 Unauthorized (token expired)
    C->>AS: POST /token<br/>{grant_type=refresh_token,<br/>refresh_token=RT_OLD}
    AS->>AS: Validate refresh token<br/>Rotate: invalidate RT_OLD
    AS->>C: {access_token=NEW, refresh_token=RT_NEW}
    C->>RS: GET /api/resource (new access_token)
    RS->>C: 200 OK + resource data
    end

OAuth 2.0 vs OpenID Connect

OAuth 2.0 is an authorization framework. OpenID Connect (OIDC) is an identity layer built on top of OAuth 2.0 that adds authentication.

What OIDC adds:

• ID Token — A JWT containing authenticated user identity claims (sub, name, email, iat, exp)
• UserInfo Endpoint — Standardized API to fetch user profile data
• Discovery Document — Auto-configuration via .well-known/openid-configuration
• Session Management — Standardized logout and session monitoring

Tokens Deep Dive

Access Token

The credential used to access protected resources.

JWT Access Token Structure:

{
  "header": { "alg": "RS256", "typ": "JWT", "kid": "key-id-1" },
  "payload": {
    "iss": "https://auth.example.com",
    "sub": "user-123",
    "aud": "https://api.example.com",
    "exp": 1700000000,
    "iat": 1699996400,
    "scope": "read:profile write:posts",
    "client_id": "app-456"
  },
  "signature": "base64(RSASHA256(header.payload, privateKey))"
}

Refresh Token

ID Token (OIDC)

A JWT that contains claims about the authenticated user.

{
  "iss": "https://accounts.google.com",
  "sub": "110169484474386276334",
  "aud": "app-client-id",
  "exp": 1700003600,
  "iat": 1700000000,
  "nonce": "random-nonce-value",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "email_verified": true,
  "picture": "https://lh3.googleusercontent.com/..."
}

Verification steps: Check iss matches expected issuer, aud matches your client_id, exp is in the future, signature is valid using the provider's public key (from JWKS endpoint), and nonce matches what you sent.

Token Storage Best Practices

Browser Applications (SPA)

Mobile Applications

Server-Side Applications

• Store tokens encrypted at rest in a database
• Use envelope encryption (encrypt token with DEK, encrypt DEK with KEK)
• Implement token caching with TTL slightly less than token expiry

Scopes and Consent

Scopes define the boundaries of access granted to a client.

GET /authorize?scope=openid profile email read:repos write:repos

Consent screen best practices:

• Show human-readable descriptions of each scope
• Allow granular consent (user can deny specific scopes)
• Remember consent decisions to avoid repeated prompts
• Support scope downgrade (request fewer scopes than previously granted)

Security Considerations

CSRF Protection (State Parameter)

state = base64(random_bytes(32))

• Generated by client before authorization request
• Stored in session/cookie
• Validated when the authorization code callback arrives
• Prevents attackers from injecting their own authorization codes

Redirect URI Validation

• Exact match only — no wildcards, no partial matching
• Register all valid redirect URIs ahead of time
• Never allow open redirects (e.g., redirect_uri=https://evil.com)
• Use HTTPS for all redirect URIs (except localhost for development)

Token Leakage Prevention

PKCE Explained

PKCE (Proof Key for Code Exchange, pronounced "pixy") prevents authorization code interception:

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
flowchart LR
    style A fill:#4CAF50,color:#fff
    style B fill:#2196F3,color:#fff
    style C fill:#FF9800,color:#fff
    style D fill:#9C27B0,color:#fff

    A(["1. Client generates<br/>code_verifier = random 43-128 chars"]) --> B[["2. Client computes<br/>code_challenge = BASE64URL SHA256 of code_verifier"]]
    B --> C{{"3. Send code_challenge<br/>in /authorize request"}}
    C --> D[/"4. Send code_verifier<br/>in /token request"/]
    D --> E{"Auth Server verifies<br/>SHA256 code_verifier == code_challenge"}

    style E fill:#F44336,color:#fff

Even if an attacker intercepts the authorization code, they cannot exchange it without the code_verifier that never left the client.

Spring Boot Implementation

Resource Server Configuration

@Configuration
@EnableWebSecurity
public class ResourceServerConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/api/admin/**").hasAuthority("SCOPE_admin")
                .requestMatchers("/api/**").authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt
                    .jwtAuthenticationConverter(jwtAuthConverter())
                )
            );
        return http.build();
    }

    @Bean
    public JwtAuthenticationConverter jwtAuthConverter() {
        JwtGrantedAuthoritiesConverter grantedAuthorities = new JwtGrantedAuthoritiesConverter();
        grantedAuthorities.setAuthoritiesClaimName("roles");
        grantedAuthorities.setAuthorityPrefix("ROLE_");

        JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
        converter.setJwtGrantedAuthoritiesConverter(grantedAuthorities);
        return converter;
    }
}

application.yml:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.example.com
          jwk-set-uri: https://auth.example.com/.well-known/jwks.json

Authorization Server (Spring Authorization Server)

@Configuration
public class AuthServerConfig {

    @Bean
    public RegisteredClientRepository registeredClientRepository() {
        RegisteredClient webClient = RegisteredClient.withId(UUID.randomUUID().toString())
            .clientId("web-app")
            .clientSecret("{noop}secret")
            .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC)
            .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
            .authorizationGrantType(AuthorizationGrantType.REFRESH_TOKEN)
            .redirectUri("http://localhost:3000/callback")
            .scope(OidcScopes.OPENID)
            .scope(OidcScopes.PROFILE)
            .scope("read:data")
            .clientSettings(ClientSettings.builder()
                .requireProofKey(true)  // Enforce PKCE
                .build())
            .tokenSettings(TokenSettings.builder()
                .accessTokenTimeToLive(Duration.ofMinutes(15))
                .refreshTokenTimeToLive(Duration.ofDays(7))
                .reuseRefreshTokens(false)  // Enable rotation
                .build())
            .build();

        return new InMemoryRegisteredClientRepository(webClient);
    }

    @Bean
    public JWKSource<SecurityContext> jwkSource() {
        RSAKey rsaKey = generateRsaKey();
        JWKSet jwkSet = new JWKSet(rsaKey);
        return (selector, context) -> selector.select(jwkSet);
    }
}

OAuth 2.0 vs SAML vs API Keys

Interview Questions

Summary Cheat Sheet

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
flowchart LR
    style WEB fill:#4CAF50,color:#fff
    style SPA fill:#2196F3,color:#fff
    style MOB fill:#FF9800,color:#fff
    style SVC fill:#9C27B0,color:#fff
    style DEV fill:#F44336,color:#fff

    Q{"What type of client?"}
    Q -->|Server-side web app| WEB(["Auth Code Grant<br/>+ client secret"])
    Q -->|Single Page App| SPA[["Auth Code + PKCE<br/>+ BFF pattern"]]
    Q -->|Mobile/Native app| MOB{{"Auth Code + PKCE<br/>+ secure storage"}}
    Q -->|Service/daemon| SVC[/"Client Credentials"/]
    Q -->|Input-limited device| DEV(("Device Code Grant"))