Reading OAuth2 ID Token in Spring MVC

In this short tutorial, you will learn how to read an ID Token in your Spring Boot Web Application @Controller class.

The ID Token is a security token that is issued by the Identity Provider Server and it contains information about the currently authenticated user. For example, from the ID token, you can get the user information like userId, first name, last name, or email address.

We do not use an ID token instead of an access token to get access to protected resource servers. We use it to carry information about the authenticated user and access it when needed.

Accessing OidcUser with the @AuthenticationPrincipal Annotation

To access information that the ID Token contains, we can use the @AuthenticationPrincipal annotation.  The @AuthenticationPrincipal annotation, helps us inject an instance of OidcUser object into a method in our @Controller class.

@Controller
public class AlbumsController {

    @GetMapping("/albums")
    public String getAlbums(Model model, @AuthenticationPrincipal OidcUser principal) {
        
        System.out.println("Principal = " + principal);
 
        return "albums";
    }
    
}

Please notice the use of @AuthenticationPrincipal in front of an OidcUser principal object in the method argument. This is how we can make information about the currently authenticated user available to our method. From the same OidcUser principal object, we can get all the claims that Open ID Connect ID Token contains.

Reading ID Token

If we look into the OidcUser interface, then we will see that it defines three useful methods. One of them is to get the ID Token.

public interface OidcUser extends OAuth2User, IdTokenClaimAccessor {

    /**
     * Returns the claims about the user.
     * The claims are aggregated from {@link #getIdToken()} and {@link #getUserInfo()} (if available).
     *
     * @return a {@code Map} of claims about the user
     */
    Map<String, Object> getClaims();

    /**
     * Returns the {@link OidcUserInfo UserInfo} containing claims about the user.
     *
     * @return the {@link OidcUserInfo} containing claims about the user.
     */
    OidcUserInfo getUserInfo();

    /**
     * Returns the {@link OidcIdToken ID Token} containing claims about the user.
     *
     * @return the {@link OidcIdToken} containing claims about the user.
     */
    OidcIdToken getIdToken();
}

So we can update our getAlbums() method to read the value of OidcToken object and the token value this way.

@Controller
public class AlbumsController {

    @GetMapping("/albums")
    public String getAlbums(Model model, @AuthenticationPrincipal OidcUser principal) {
        
        // Get ID Token Object 
        OidcIdToken idToken = principal.getIdToken();
  
        // Get ID Token Value
        String tokenValue = idToken.getTokenValue();
        System.out.println("ID tokenValue = " + tokenValue);
 
        return "albums";
    }
    
}

I hope this short tutorial was of some value to you. Have a look at other OAuth2 related tutorials on this blog. Hopefully, you will find more tutorials that will be of good value to you.

Happy learning! 🙋🏻‍♂️