OpenID Connect Integration in Java: Complete Implementation Guide

OpenID Connect (OIDC) is an identity layer built on top of OAuth 2.0 that enables clients to verify user identities and obtain basic profile information. Here's a comprehensive guide to implementing OIDC in Java applications.

Table of Contents

Key OIDC Concepts

ID Token: JWT containing user identity information
UserInfo Endpoint: Returns additional user claims
Discovery: Standardized metadata endpoint
Dynamic Registration: Client registration with identity providers

Dependencies Setup

Maven Dependencies

<dependencies>
<!-- Spring Security OAuth2 -->
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-oauth2-client</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-oauth2-jose</artifactId>
</dependency>
<!-- Spring Boot Security -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- JWT Libraries -->
<dependency>
<groupId>com.nimbusds</groupId>
<artifactId>nimbus-jose-jwt</artifactId>
<version>9.31</version>
</dependency>
<!-- For manual OIDC implementation -->
<dependency>
<groupId>org.apache.httpcomponents.client5</groupId>
<artifactId>httpclient5</artifactId>
</dependency>
</dependencies>

Spring Boot OIDC Integration

Example 1: Basic Spring Security OIDC Configuration

@Configuration
@EnableWebSecurity
public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(authz -> authz
.requestMatchers("/", "/public/**").permitAll()
.anyRequest().authenticated()
)
.oauth2Login(oauth2 -> oauth2
.loginPage("/oauth2/authorization/google")
.defaultSuccessUrl("/dashboard", true)
.failureUrl("/login?error=true")
)
.logout(logout -> logout
.logoutSuccessUrl("/")
.invalidateHttpSession(true)
.deleteCookies("JSESSIONID")
);
return http.build();
}
}

Example 2: Application Properties Configuration

# application.yml
spring:
security:
oauth2:
client:
registration:
google:
client-id: ${GOOGLE_CLIENT_ID}
client-secret: ${GOOGLE_CLIENT_SECRET}
scope:
- openid
- profile
- email
redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
okta:
client-id: ${OKTA_CLIENT_ID}
client-secret: ${OKTA_CLIENT_SECRET}
scope: openid,profile,email
azure:
client-id: ${AZURE_CLIENT_ID}
client-secret: ${AZURE_CLIENT_SECRET}
scope: openid,profile,email
authorization-grant-type: authorization_code
client-authentication-method: client_secret_post
provider:
okta:
issuer-uri: https://${OKTA_DOMAIN}/oauth2/default
azure:
issuer-uri: https://login.microsoftonline.com/${AZURE_TENANT_ID}/v2.0

Manual OIDC Implementation

Example 3: OIDC Discovery and Dynamic Client Registration

@Service
public class OidcDiscoveryService {
private final WebClient webClient;
private final ObjectMapper objectMapper;
public OidcDiscoveryService(WebClient.Builder webClientBuilder) {
this.webClient = webClientBuilder.build();
this.objectMapper = new ObjectMapper();
}
public OidcProviderMetadata discoverProvider(String issuerUrl) {
try {
String discoveryUrl = issuerUrl + "/.well-known/openid-configuration";
return webClient.get()
.uri(discoveryUrl)
.retrieve()
.bodyToMono(OidcProviderMetadata.class)
.block();
} catch (Exception e) {
throw new RuntimeException("OIDC discovery failed for issuer: " + issuerUrl, e);
}
}
public OidcClientRegistration registerClient(OidcProviderMetadata metadata, 
OidcClientMetadata clientMetadata) {
try {
return webClient.post()
.uri(metadata.getRegistrationEndpoint())
.contentType(MediaType.APPLICATION_JSON)
.bodyValue(objectMapper.writeValueAsString(clientMetadata))
.retrieve()
.bodyToMono(OidcClientRegistration.class)
.block();
} catch (Exception e) {
throw new RuntimeException("Client registration failed", e);
}
}
}
@Data
class OidcProviderMetadata {
private String issuer;
private String authorizationEndpoint;
private String tokenEndpoint;
private String userinfoEndpoint;
private String jwksUri;
private String registrationEndpoint;
private List<String> scopesSupported;
private List<String> responseTypesSupported;
private List<String> subjectTypesSupported;
private List<String> idTokenSigningAlgValuesSupported;
}
@Data
class OidcClientMetadata {
private List<String> redirectUris;
private String clientName;
private List<String> grantTypes = Arrays.asList("authorization_code", "refresh_token");
private List<String> responseTypes = Arrays.asList("code");
private String applicationType = "web";
private List<String> contacts;
}
@Data
class OidcClientRegistration {
private String clientId;
private String clientSecret;
private String clientIdIssuedAt;
private String clientSecretExpiresAt;
private String registrationClientUri;
private String registrationAccessToken;
}

Example 4: OIDC Authentication Flow

@Service
public class OidcAuthenticationService {
private final WebClient webClient;
private final JwtDecoder jwtDecoder;
private final OidcProviderMetadata providerMetadata;
public OidcAuthenticationService(WebClient.Builder webClientBuilder, 
OidcProviderMetadata providerMetadata) {
this.webClient = webClientBuilder.build();
this.providerMetadata = providerMetadata;
this.jwtDecoder = JwtDecoders.fromIssuerLocation(providerMetadata.getIssuer());
}
public String buildAuthorizationUrl(String clientId, String redirectUri, String state, String nonce) {
return UriComponentsBuilder.fromHttpUrl(providerMetadata.getAuthorizationEndpoint())
.queryParam("response_type", "code")
.queryParam("client_id", clientId)
.queryParam("redirect_uri", redirectUri)
.queryParam("scope", "openid profile email")
.queryParam("state", state)
.queryParam("nonce", nonce)
.build()
.toUriString();
}
public OidcTokens exchangeCodeForTokens(String authorizationCode, String clientId, 
String clientSecret, String redirectUri) {
try {
MultiValueMap<String, String> formData = new LinkedMultiValueMap<>();
formData.add("grant_type", "authorization_code");
formData.add("code", authorizationCode);
formData.add("redirect_uri", redirectUri);
formData.add("client_id", clientId);
formData.add("client_secret", clientSecret);
TokenResponse tokenResponse = webClient.post()
.uri(providerMetadata.getTokenEndpoint())
.contentType(MediaType.APPLICATION_FORM_URLENCODED)
.body(BodyInserters.fromFormData(formData))
.retrieve()
.bodyToMono(TokenResponse.class)
.block();
return validateIdToken(tokenResponse.getIdToken());
} catch (Exception e) {
throw new RuntimeException("Token exchange failed", e);
}
}
private OidcTokens validateIdToken(String idToken) {
try {
Jwt jwt = jwtDecoder.decode(idToken);
// Validate required claims
validateRequiredClaims(jwt.getClaims());
return new OidcTokens(
idToken,
jwt.getClaims(),
jwt.getHeaders()
);
} catch (Exception e) {
throw new RuntimeException("ID token validation failed", e);
}
}
private void validateRequiredClaims(Map<String, Object> claims) {
if (!claims.containsKey("iss") || !claims.get("iss").equals(providerMetadata.getIssuer())) {
throw new RuntimeException("Invalid issuer");
}
if (!claims.containsKey("sub")) {
throw new RuntimeException("Missing subject");
}
if (!claims.containsKey("aud")) {
throw new RuntimeException("Missing audience");
}
if (!claims.containsKey("exp")) {
throw new RuntimeException("Missing expiration");
}
// Validate expiration
long exp = Long.parseLong(claims.get("exp").toString());
if (System.currentTimeMillis() / 1000 > exp) {
throw new RuntimeException("Token expired");
}
}
public OidcUserInfo getUserInfo(String accessToken) {
return webClient.get()
.uri(providerMetadata.getUserinfoEndpoint())
.header("Authorization", "Bearer " + accessToken)
.retrieve()
.bodyToMono(OidcUserInfo.class)
.block();
}
}
@Data
class TokenResponse {
private String accessToken;
private String tokenType;
private Long expiresIn;
private String idToken;
private String refreshToken;
private String scope;
}
@Data
class OidcTokens {
private final String idToken;
private final Map<String, Object> idTokenClaims;
private final Map<String, Object> idTokenHeaders;
}
@Data
class OidcUserInfo {
private String sub;
private String name;
private String givenName;
private String familyName;
private String middleName;
private String nickname;
private String preferredUsername;
private String profile;
private String picture;
private String website;
private String email;
private Boolean emailVerified;
private String gender;
private String birthdate;
private String zoneinfo;
private String locale;
private String phoneNumber;
private Boolean phoneNumberVerified;
private Map<String, Object> address;
private Long updatedAt;
}

Advanced OIDC Features

Example 5: Custom OIDC User Service

@Service
public class CustomOidcUserService implements OAuth2UserService<OidcUserRequest, OidcUser> {
private final OidcUserService delegate = new OidcUserService();
private final UserRepository userRepository;
public CustomOidcUserService(UserRepository userRepository) {
this.userRepository = userRepository;
}
@Override
public OidcUser loadUser(OidcUserRequest userRequest) throws OAuth2AuthenticationException {
OidcUser oidcUser = delegate.loadUser(userRequest);
// Extract claims from ID token
Map<String, Object> claims = oidcUser.getClaims();
String email = (String) claims.get("email");
String subject = (String) claims.get("sub");
String issuer = userRequest.getClientRegistration().getProviderDetails().getIssuerUri();
// Find or create user in local database
User user = userRepository.findBySubAndIssuer(subject, issuer)
.orElseGet(() -> createNewUser(oidcUser, subject, issuer));
// Update user information
updateUserFromClaims(user, claims);
// Create custom OIDC user with additional attributes
return new CustomOidcUser(oidcUser, user);
}
private User createNewUser(OidcUser oidcUser, String subject, String issuer) {
User user = new User();
user.setSub(subject);
user.setIssuer(issuer);
user.setCreatedAt(LocalDateTime.now());
return userRepository.save(user);
}
private void updateUserFromClaims(User user, Map<String, Object> claims) {
user.setEmail((String) claims.get("email"));
user.setName((String) claims.get("name"));
user.setGivenName((String) claims.get("given_name"));
user.setFamilyName((String) claims.get("family_name"));
user.setPicture((String) claims.get("picture"));
user.setEmailVerified(Boolean.TRUE.equals(claims.get("email_verified")));
user.setUpdatedAt(LocalDateTime.now());
userRepository.save(user);
}
}
@Data
class CustomOidcUser extends DefaultOidcUser {
private final User localUser;
public CustomOidcUser(OidcUser oidcUser, User localUser) {
super(oidcUser.getAuthorities(), oidcUser.getIdToken(), oidcUser.getUserInfo());
this.localUser = localUser;
}
@Override
public String getName() {
return localUser.getEmail(); // Use email as principal name
}
public Long getUserId() {
return localUser.getId();
}
}
@Entity
@Table(name = "users")
@Data
class User {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(unique = true, nullable = false)
private String sub; // OIDC subject identifier
@Column(nullable = false)
private String issuer;
private String email;
private String name;
private String givenName;
private String familyName;
private String picture;
private Boolean emailVerified;
private LocalDateTime createdAt;
private LocalDateTime updatedAt;
}

Example 6: JWT Validation and Key Management

@Service
public class JwtValidationService {
private final Map<String, JwtDecoder> jwtDecoders = new ConcurrentHashMap<>();
private final WebClient webClient;
public JwtValidationService(WebClient.Builder webClientBuilder) {
this.webClient = webClientBuilder.build();
}
public Jwt validateToken(String token, String issuer) {
JwtDecoder decoder = jwtDecoders.computeIfAbsent(issuer, this::createJwtDecoder);
return decoder.decode(token);
}
private JwtDecoder createJwtDecoder(String issuer) {
try {
// Fetch JWKS (JSON Web Key Set) from issuer
String jwksUri = getJwksUriFromIssuer(issuer);
JwtDecoder jwtDecoder = NimbusJwtDecoder.withJwkSetUri(jwksUri).build();
// Configure validators
((NimbusJwtDecoder) jwtDecoder).setJwtValidator(jwtValidator(issuer));
return jwtDecoder;
} catch (Exception e) {
throw new RuntimeException("Failed to create JWT decoder for issuer: " + issuer, e);
}
}
private String getJwksUriFromIssuer(String issuer) {
// For well-known providers, use discovery endpoint
String discoveryUrl = issuer + "/.well-known/openid-configuration";
Map<String, Object> discovery = webClient.get()
.uri(discoveryUrl)
.retrieve()
.bodyToMono(new ParameterizedTypeReference<Map<String, Object>>() {})
.block();
return (String) discovery.get("jwks_uri");
}
private OAuth2TokenValidator<Jwt> jwtValidator(String issuer) {
List<OAuth2TokenValidator<Jwt>> validators = new ArrayList<>();
validators.add(new JwtTimestampValidator());
validators.add(new JwtIssuerValidator(issuer));
validators.add(new JwtClaimValidator<String>("aud", 
aud -> aud != null && aud.contains("your-client-id")));
validators.add(new JwtClaimValidator<String>("nonce", 
nonce -> nonce != null)); // Validate nonce if present
return new DelegatingOAuth2TokenValidator<>(validators);
}
public boolean validateTokenSignature(String token, String jwksUri) {
try {
// Parse token without validation
SignedJWT signedJWT = SignedJWT.parse(token);
// Get key ID from header
String keyId = signedJWT.getHeader().getKeyID();
// Fetch JWKS and find the matching key
JWKSet jwkSet = JWKSet.load(new URL(jwksUri).openStream());
JWK jwk = jwkSet.getKeyByKeyId(keyId);
if (jwk instanceof RSAKey) {
RSASSAVerifier verifier = new RSASSAVerifier(((RSAKey) jwk).toRSAPublicKey());
return signedJWT.verify(verifier);
}
return false;
} catch (Exception e) {
throw new RuntimeException("Token signature validation failed", e);
}
}
}

Example 7: OIDC-Protected REST API

@RestController
@RequestMapping("/api")
public class SecureApiController {
@GetMapping("/user/profile")
public ResponseEntity<UserProfile> getUserProfile(@AuthenticationPrincipal OidcUser principal) {
UserProfile profile = new UserProfile();
profile.setEmail(principal.getEmail());
profile.setName(principal.getFullName());
profile.setPicture(principal.getPicture());
profile.setEmailVerified(principal.getEmailVerified());
return ResponseEntity.ok(profile);
}
@PostMapping("/user/preferences")
public ResponseEntity<?> updateUserPreferences(
@RequestBody UserPreferences preferences,
@AuthenticationPrincipal CustomOidcUser principal) {
// Use local user ID from custom OIDC user
Long userId = principal.getUserId();
// Update preferences for this user
return ResponseEntity.ok().build();
}
}
@Configuration
@EnableWebSecurity
@EnableMethodSecurity(prePostEnabled = true)
public class ResourceServerConfig {
@Bean
public SecurityFilterChain apiFilterChain(HttpSecurity http) throws Exception {
http
.securityMatcher("/api/**")
.authorizeHttpRequests(authz -> authz
.anyRequest().authenticated()
)
.oauth2ResourceServer(oauth2 -> oauth2
.jwt(jwt -> jwt
.jwtAuthenticationConverter(grantedAuthoritiesExtractor())
)
)
.sessionManagement(session -> session
.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
);
return http.build();
}
private Converter<Jwt, AbstractAuthenticationToken> grantedAuthoritiesExtractor() {
JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
converter.setJwtGrantedAuthoritiesConverter(jwt -> {
// Extract roles from JWT claims
Map<String, Object> realmAccess = jwt.getClaimAsMap("realm_access");
if (realmAccess != null) {
List<String> roles = (List<String>) realmAccess.get("roles");
if (roles != null) {
return roles.stream()
.map(role -> new SimpleGrantedAuthority("ROLE_" + role))
.collect(Collectors.toList());
}
}
return Collections.emptyList();
});
return converter;
}
}

Testing OIDC Integration

Example 8: Testing OIDC Authentication

@SpringBootTest
@AutoConfigureTestDatabase
class OidcAuthenticationTest {
@Autowired
private TestRestTemplate restTemplate;
@MockBean
private OAuth2AuthorizedClientService authorizedClientService;
@Test
void testUnauthenticatedAccess() {
ResponseEntity<String> response = restTemplate.getForEntity("/api/user/profile", String.class);
assertThat(response.getStatusCode()).isEqualTo(HttpStatus.UNAUTHORIZED);
}
@Test
@WithMockOidcUser(email = "[email protected]", roles = {"USER"})
void testAuthenticatedAccess() {
ResponseEntity<UserProfile> response = restTemplate.getForEntity("/api/user/profile", UserProfile.class);
assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
assertThat(response.getBody().getEmail()).isEqualTo("[email protected]");
}
}
// Custom security test annotation
@Retention(RetentionPolicy.RUNTIME)
@WithSecurityContext(factory = WithMockOidcUserSecurityContextFactory.class)
public @interface WithMockOidcUser {
String email() default "[email protected]";
String[] roles() default {"USER"};
String sub() default "1234567890";
}
public class WithMockOidcUserSecurityContextFactory implements WithSecurityContextFactory<WithMockOidcUser> {
@Override
public SecurityContext createSecurityContext(WithMockOidcUser mockUser) {
SecurityContext context = SecurityContextHolder.createEmptyContext();
Map<String, Object> claims = new HashMap<>();
claims.put("sub", mockUser.sub());
claims.put("email", mockUser.email());
claims.put("email_verified", true);
Jwt jwt = Jwt.withTokenValue("mock-token")
.header("alg", "RS256")
.claims(c -> c.putAll(claims))
.build();
List<GrantedAuthority> authorities = Arrays.stream(mockUser.roles())
.map(role -> new SimpleGrantedAuthority("ROLE_" + role))
.collect(Collectors.toList());
JwtAuthenticationToken authentication = new JwtAuthenticationToken(jwt, authorities);
context.setAuthentication(authentication);
return context;
}
}

Best Practices and Security Considerations

Security Configuration

@Configuration
public class OidcSecurityBestPractices {
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http
// CSRF protection for state-changing operations
.csrf(csrf -> csrf
.ignoringRequestMatchers("/api/**")
)
// Session management
.sessionManagement(session -> session
.sessionCreationPolicy(SessionCreationPolicy.IF_REQUIRED)
.maximumSessions(1)
)
// Headers security
.headers(headers -> headers
.contentSecurityPolicy(csp -> csp
.policyDirectives("default-src 'self'; script-src 'self' 'unsafe-inline'")
)
.frameOptions(FrameOptionsConfig::sameOrigin)
)
// OAuth2 client
.oauth2Client(oauth2 -> oauth2
.authorizationCodeGrant(codeGrant -> codeGrant
.authorizationRequestRepository(cookieAuthorizationRequestRepository())
)
);
return http.build();
}
private CookieAuthorizationRequestRepository cookieAuthorizationRequestRepository() {
return new HttpCookieOAuth2AuthorizationRequestRepository();
}
@Bean
public ClientRegistrationRepository clientRegistrationRepository() {
return new InMemoryClientRegistrationRepository(this.googleClientRegistration());
}
private ClientRegistration googleClientRegistration() {
return ClientRegistration.withRegistrationId("google")
.clientId(System.getenv("GOOGLE_CLIENT_ID"))
.clientSecret(System.getenv("GOOGLE_CLIENT_SECRET"))
.clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC)
.authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
.redirectUri("{baseUrl}/login/oauth2/code/{registrationId}")
.scope("openid", "profile", "email")
.authorizationUri("https://accounts.google.com/o/oauth2/v2/auth")
.tokenUri("https://www.googleapis.com/oauth2/v4/token")
.userInfoUri("https://www.googleapis.com/oauth2/v3/userinfo")
.userNameAttributeName(IdTokenClaimNames.SUB)
.jwkSetUri("https://www.googleapis.com/oauth2/v3/certs")
.clientName("Google")
.build();
}
}

Conclusion

OpenID Connect provides a robust framework for implementing secure authentication in Java applications. Key takeaways:

Use Spring Security OAuth2 for quick integration with major providers
Implement proper JWT validation with signature verification and claim validation
Handle user sessions securely with appropriate session management
Follow security best practices for CSRF protection and headers security
Test thoroughly with both unit tests and integration tests

OIDC integration enables secure, standards-based authentication that works across different identity providers while providing a good user experience.