Java web application (Spring Security)

Add OneiD to a Java application with Spring Security, step by step.

View as Markdown

This quickstart adds OneiD to a server web application with Spring Security. Every file is complete and runs as it is.

Tip Using an AI coding agent? Give it this page as Markdown (add .md to the address) together with the Connector specification. See Build with AI coding agents.

Before you start

  • A OneiD address, for example https://YOUR_ONEID. The code below uses the demonstration instance https://auth.oltinid.com; replace it with your own.
  • A client registered for this application (step 1). The code uses the client ID quickstart; replace it with yours.
  • A user who can sign in to your OneiD. For the demonstration instance, ask for a demo account.

1. Register the application

Ask your OneiD administrator to register a client with these settings, or register it yourself in the admin console. See Register an application.

Setting Value
Client type public (no secret)
Grant types authorization_code (add refresh_token if you request offline_access)
Redirect URI http://localhost:3000/login/oauth2/code/oneid
Post-logout redirect URI http://localhost:3000
Allowed scopes openid profile email

2. Install

Add the dependency org.springframework.boot:spring-boot-starter-oauth2-client.

3. Add the code

application.yml

server:
  port: 3000

spring:
  security:
    oauth2:
      client:
        registration:
          oneid:
            client-id: quickstart
            client-authentication-method: none   # a public client; Spring Security adds PKCE
            authorization-grant-type: authorization_code
            scope: openid, profile, email
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
        provider:
          oneid:
            # Spring reads the endpoints and signing keys from OneiD. The issuer name ends with a slash.
            issuer-uri: https://auth.oltinid.com/

HomeController.java

package com.example.demo;

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;

// With spring-boot-starter-oauth2-client on the classpath, every page needs a signed-in user:
// Spring Security sends the browser to OneiD and handles the callback.
@RestController
public class HomeController {

    @GetMapping("/")
    public String home(@AuthenticationPrincipal OidcUser user) {
        return "Hello, " + user.getFullName() + " (" + user.getEmail() + ")";
    }
}

4. Run it

Create a Spring Boot project with the Spring Web and OAuth2 Client starters, add these two files, and run it.

Spring Security uses the redirect address http://localhost:3000/login/oauth2/code/oneid.

Checkpoint Open http://localhost:3000 and Spring Security sends the browser to OneiD. After you sign in, the page shows Hello, followed by the user’s name and, in parentheses, the email address.

Common issues

  • OneiD shows an error page about the redirect address (invalid_request). The redirect URI the code sends is not registered on the client exactly as written. Register it, including scheme and port.
  • invalid_grant from the token endpoint. The code was used before or expired. Start the sign-in again; do not reload the callback page.
  • More errors and fixes: Errors and troubleshooting.

Learn more