# Java web application (Spring Security)

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

Source: https://oltinid.com/docs/quickstarts/java/ · Section: Quickstarts · All OneiD documentation: https://oltinid.com/llms.txt

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](https://oltinid.com/docs/ai/connector-specification/). See [Build with AI coding agents](https://oltinid.com/docs/ai/build-with-ai/).

## 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](https://oltinid.com/contact/?topic=demo).

## 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](https://oltinid.com/docs/get-started/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`

```yaml
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`

```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](https://oltinid.com/docs/reference/errors/).

## Learn more

- [Authorization code flow with PKCE](https://oltinid.com/docs/guides/authorization-code-pkce/)
- [Sign-out](https://oltinid.com/docs/guides/logout/)
- [Scopes, claims and roles](https://oltinid.com/docs/guides/scopes-claims-roles/)
- [Refresh tokens](https://oltinid.com/docs/guides/refresh-tokens/)