OAuth2 and OIDC: Resource Server, Client and Auth Server

Delegated Authorisation, Not Authentication

OAuth2 is frequently described as "login with Google", which is misleading. OAuth2 is a delegated authorisation framework — a way for an application to obtain limited access to a resource on a user's behalf, without handling their password.

OIDC (OpenID Connect) is the layer on top that adds authentication: an ID token stating who the user is. "Login with Google" is OIDC.

The distinction matters because using OAuth2's access token as proof of identity is a known mistake. An access token says this bearer may call these APIs; it does not reliably say who the bearer is, and it was not issued to your application to make that claim.

The Four Roles

A Spring application is usually a resource server, sometimes a client, and occasionally the authorisation server. Spring has separate support for each.

Resource Server

The most common case — your API validates bearer tokens it did not issue:

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-oauth2-resource-server'
}

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.example.com/realms/shop
          audiences: shop-api

@Bean
SecurityFilterChain apiChain(HttpSecurity http) throws Exception {
    return http
        .securityMatcher("/api/**")
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
        .oauth2ResourceServer(oauth -> oauth.jwt(Customizer.withDefaults()))
        .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
        .csrf(CsrfConfigurer::disable)
        .build();
}

That issuer-uri does a surprising amount. At startup Spring fetches /.well-known/openid-configuration, discovers the JWKS endpoint, and configures a validator that checks signature, issuer, audience and expiry — with key rotation and caching handled. This is the five-check list from the authentication guide, implemented correctly, for two lines of YAML.

Mapping scopes and claims to authorities

By default, scopes become authorities prefixed SCOPE_:

.requestMatchers("/api/orders/**").hasAuthority("SCOPE_orders:read")

Most providers put roles in a custom claim instead, so you convert:

@Bean
JwtAuthenticationConverter jwtAuthenticationConverter() {
    var authorities = new JwtGrantedAuthoritiesConverter();
    authorities.setAuthorityPrefix("ROLE_");
    authorities.setAuthoritiesClaimName("roles");       // provider-specific
 
    var converter = new JwtAuthenticationConverter();
    converter.setJwtGrantedAuthoritiesConverter(authorities);
    return converter;
}

Now hasRole("ADMIN") works against the provider's roles claim — reconnecting to the role/authority conventions from the previous guide. Keycloak nests roles under realm_access.roles, which needs a custom converter; check your provider's actual token rather than assuming.

Opaque tokens

Some providers issue reference tokens with no readable content. Validation then means asking the provider:

spring:
  security:
    oauth2:
      resourceserver:
        opaquetoken:
          introspection-uri: https://auth.example.com/oauth2/introspect
          client-id: shop-api
          client-secret: ${INTROSPECTION_SECRET}

The trade is explicit: a network call per request (cache it), in exchange for immediate revocation — the opposite of the JWT trade-off. For a service where a revoked token must stop working at once, that cost may be worth paying.

Client

When your application needs to act on a user's behalf — or simply offer "log in with Google":

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-oauth2-client'
}

spring:
  security:
    oauth2:
      client:
        registration:
          google:
            client-id: ${GOOGLE_CLIENT_ID}
            client-secret: ${GOOGLE_CLIENT_SECRET}
            scope: openid,profile,email
          inventory:
            client-id: shop-service
            client-secret: ${INVENTORY_CLIENT_SECRET}
            authorization-grant-type: client_credentials
            scope: inventory:read,inventory:write
        provider:
          inventory:
            token-uri: https://auth.example.com/oauth2/token

http.oauth2Login(Customizer.withDefaults());     // adds the full login flow

Spring provides the redirect endpoints, callback handling, token exchange and session creation.

The authorisation code flow with PKCE

The flow worth understanding, because every browser and mobile login uses it:

PKCE (Proof Key for Code Exchange) is what makes this safe for clients that can't keep a secret. The client generates a random code_verifier, sends its hash as code_challenge on the way out, and presents the original verifier when redeeming the code. An attacker who intercepts the authorisation code cannot use it without the verifier.

PKCE began as a mobile-specific measure and is now recommended for all clients, confidential ones included. Spring Security enables it automatically for public clients; enable it explicitly otherwise.

Service-to-service: client credentials

No user involved — one service authenticating as itself:

@Bean
RestClient inventoryClient(RestClient.Builder builder,
                           OAuth2AuthorizedClientManager clients) {
    return builder
            .baseUrl("https://inventory.internal")
            .requestInterceptor(new OAuth2ClientHttpRequestInterceptor(clients))
            .build();
}

The interceptor obtains and attaches a token, and refreshes it before expiry. This replaces the pattern of passing a long-lived shared API key between services, with the benefit that the token is short-lived and scoped.

ID Tokens vs Access Tokens

The distinction that causes real vulnerabilities:

Authorisation Server

Spring Authorization Server lets you be the provider:

dependencies {
    implementation 'org.springframework.security:spring-security-oauth2-authorization-server'
}

@Bean
RegisteredClientRepository registeredClientRepository() {
    RegisteredClient spa = RegisteredClient.withId(UUID.randomUUID().toString())
            .clientId("shop-spa")
            .clientAuthenticationMethod(ClientAuthenticationMethod.NONE)   // public client
            .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
            .authorizationGrantType(AuthorizationGrantType.REFRESH_TOKEN)
            .redirectUri("https://shop.example.com/callback")
            .scope(OidcScopes.OPENID)
            .scope("orders:read")
            .clientSettings(ClientSettings.builder().requireProofKey(true).build())  // PKCE
            .build();
    return new InMemoryRegisteredClientRepository(spa);
}

It is a full OIDC-certified implementation — authorisation code, client credentials, refresh tokens, PKCE, JWKS, discovery, token introspection and revocation.

When self-hosting makes sense: a regulatory requirement that credentials never leave your infrastructure, an existing user store you must authenticate against, or cost at very large user counts.

When it doesn't: most of the time. An authorisation server is security-critical infrastructure you must patch, monitor, key-rotate, back up and operate correctly. Keycloak (self-hosted, open source) or a managed provider gives you the same protocol with an admin UI, user management, MFA, federation and someone else's on-call rota. Choosing to build this is choosing to own it.

Choosing an Approach

That last row is worth saying out loud. OAuth2 solves delegation across trust boundaries. An internal tool with fifteen users and no third-party integration gets complexity from it, not security — form login with sessions is less to operate and easier to reason about.

The Mental Model, Restated

1. OAuth2 is authorisation; OIDC adds authentication. An access token is not proof of identity.
2. Resource server is two lines of config, and issuer-uri gets the five validation checks right.
3. Map provider claims to authorities with a JwtAuthenticationConverter.
4. Opaque tokens trade a network call for immediate revocation.
5. Authorisation code + PKCE for all interactive clients. Implicit and password grants are deprecated.
6. Client credentials for service-to-service, replacing shared API keys.
7. ID token audience is the client; access token audience is the API. Never mix them.
8. Self-host an authorisation server only with a reason — it's security-critical infrastructure you then own.

What's Next

One guide remains in this phase, covering the two protections that are most often misconfigured by copy-paste: CORS, which is about which origins a browser may call you from, and CSRF, which is about whether a browser can be tricked into calling you. Plus how to test all of it.