OAuth2 & OpenID Connect (OIDC)

OAuth2 and OpenID Connect (OIDC) are industry-standard protocols for authentication and authorization. While OAuth2 is primarily for authorization (granting access to resources), OIDC is an identity layer on top of OAuth2, providing authentication and user identity information.

What is OAuth2?

OAuth2 is a framework for delegated access. Instead of sharing credentials, a client app receives access tokens to access resources on behalf of a user.

Key Roles in OAuth2:

OAuth2 Grant Types

1. Authorization Code – For server-side apps (most secure)
2. Implicit – For client-side apps (deprecated, use Authorization Code with PKCE)
3. Client Credentials – For server-to-server communication
4. Resource Owner Password Credentials (ROPC) – User credentials sent to client (less secure)
5. Refresh Token – Obtain new access tokens without re-login

Flow (simplified):

User → Authorizes → Client → Requests Token → Access Resource

What is OpenID Connect (OIDC)?

OIDC extends OAuth2 by adding authentication. It provides an ID Token (JWT) that contains user identity info like name, email, and roles.

OIDC Tokens:

OIDC allows a client to verify the identity of the user and get profile info while using OAuth2 for authorization.

Flow (simplified):

User → Logs in → Authorization Server → ID Token + Access Token → Client

OAuth2 + OIDC Flow (Authorization Code Flow)

Step-by-step Flow:

1. Client redirects user to Authorization Server login page
2. User authenticates → Authorization Server redirects back with authorization code
3. Client sends authorization code to Authorization Server → gets:
   • Access Token (API access)
   • ID Token (user identity)
   • Refresh Token (optional)
4. Client stores tokens securely
5. Client calls Resource Server APIs with Access Token
6. Resource Server validates token → allows access

OAuth2 in Spring Security

Spring Security provides ready-made support for OAuth2 login and OIDC.

Integration Features:

• Auto-configured login endpoints
• Token validation & session management
• Works with multiple providers: Google, Facebook, Keycloak, Okta, GitHub

Example: Spring Security OAuth2 Login

@Configuration
@EnableWebSecurity
publicclassSecurityConfig {

@Bean
public SecurityFilterChainsecurityFilterChain(HttpSecurity http)throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated())
            .oauth2Login(oauth2 -> oauth2
                .loginPage("/oauth2/authorization/my-client"))// Custom login page
            .logout(logout -> logout
                .logoutSuccessUrl("/"));
return http.build();
    }
}

Key Components in Spring Security OAuth2

1. Client Registration – Defines OAuth2 provider details (client-id, secret, redirect URI)
2. OAuth2LoginAuthenticationFilter – Intercepts login requests and handles OAuth2 flow
3. OidcUserService / DefaultOAuth2UserService – Loads user information (ID token or user info endpoint)
4. Security Filter Chain – Secures endpoints and registers OAuth2 filters

Access Token & ID Token in Practice

Spring Security uses Access Tokens and ID Tokens to manage authentication and authorization after an OAuth2/OIDC login.

Access Token: Grants access to APIs, contains scope, expiry, and client info, sent in Authorization header.

ID Token: Identifies the authenticated user, contains user info (sub, email, name), used by the client for authentication.

Controller Example:

import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @GetMapping("/profile")
    public String userProfile(@AuthenticationPrincipal OidcUser oidcUser) {
        // Access ID Token info via OidcUser
        return "Hello, " + oidcUser.getFullName() + " (" + oidcUser.getEmail() + ")";
    }
}

@AuthenticationPrincipal gives access to OIDC user info after OAuth2 login.

Refresh Tokens

• Used to get new access tokens without user re-login
• Stored securely in server or HttpOnly cookie
• Rotation strategies (similar to JWT) can be applied for security

OAuth2 Login – Social Login Integration

Spring Security supports OAuth2 login, which allows users to authenticate using third-party identity providers (social logins) like:

• Google, Facebook, GitHub, LinkedIn
• Users don’t need to create a new account for your application.

Example (application.yml):

spring:
  security:
    oauth2:
      client:
        registration:
          google:
            client-id: your-client-id
            client-secret: your-client-secret
            scope: openid, profile, email

Resource Server – Protecting APIs

To protect APIs using access tokens:

@EnableWebSecurity
publicclassResourceServerConfig {

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

Access token scopes (SCOPE_admin) are used to enforce fine-grained authorization.

Keycloak Integration – Example

Keycloak can be used as Authorization Server:

1. Create realm, client, and roles

2. Configure Spring Boot with client credentials:

spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: spring-client
            client-secret: secret
            scope: openid,profile,email
            redirect-uri: "{baseUrl}/login/oauth2/code/keycloak"
        provider:
          keycloak:
            issuer-uri: <http://localhost:8080/realms/myrealm>

3. Users login via Keycloak and receive ID token + access token

4. Roles are mapped to Spring Security authorities

Scopes, Authorities, and Claims

Scopes: Define permissions for access tokens (read, write, admin)

Authorities: Mapped from scopes/roles for endpoint access control

Claims: Contain user info in ID Token (sub, email, name, roles)

Claims extraction example:

@GetMapping("/claims")
public Map<String, Object>getClaims(@AuthenticationPrincipal OidcUser oidcUser) {
return oidcUser.getClaims();
}

OAuth2 + OIDC vs JWT

Best Practices

• Always use HTTPS
• Prefer Authorization Code with PKCE for SPAs
• Validate token signature and expiry
• Store tokens securely (HttpOnly cookies preferred)
• Use OIDC for authentication, OAuth2 for authorization
• Implement role-based access control in resource servers

Key Takeaways

• OAuth2: Delegated access / authorization
• OIDC: Adds authentication & identity layer
• Access + ID + Refresh tokens manage auth & session
• Spring Security provides seamless OAuth2/OIDC integration
• Ideal for SSO, social login, microservices

Conclusion

OAuth2 + OIDC is a modern, robust, and secure approach to handle authentication and authorization in enterprise-grade applications. By integrating Spring Security, developers can implement:

• Single Sign-On (SSO) across multiple apps
• Social login integration
• Secure API access with scopes, roles, and claims
• Seamless token management using Access, ID, and Refresh tokens