OAuth 2.1 / OIDC

OpenGate IAM implements OAuth 2.1 and OpenID Connect (OIDC) via Spring Authorization Server 1.3 — the recommended standard for securing modern web apps, APIs, and CLI tools.

On this page

• Supported Grant Types
• Authorization Code + PKCE
• Client Credentials
• OIDC Endpoints
• JWT Access Token Structure
• Token Validation

Supported Grant Types

Authorization Code + PKCE

  Client App                  OpenGate Gateway           Auth Service
      │                              │                        │
      │ 1. Generate code_verifier    │                        │
      │    code_challenge =          │                        │
      │    BASE64URL(SHA256(cv))     │                        │
      │                              │                        │
      │ 2. GET /auth                 │                        │
      │    ?response_type=code       │                        │
      │    &client_id=my-app         │                        │
      │    &code_challenge=...       │───────────────────────►│
      │    &scope=openid profile     │                        │
      │                              │                        │ Show login
      │◄───────────────────────────────────────────────────── │
      │                              │                        │
      │ 3. User submits credentials  │                        │
      │─────────────────────────────────────────────────────► │
      │                              │                        │ Verify + issue code
      │ 4. Redirect ?code=<code>     │                        │
      │◄──────────────────────────────────────────────────────│
      │                              │                        │
      │ 5. POST /token               │                        │
      │    grant_type=authorization_code                      │
      │    code=<code>               │───────────────────────►│
      │    code_verifier=<cv>        │                        │ Verify PKCE + issue JWT
      │ 6. { access_token,           │◄───────────────────────│
      │      refresh_token,          │                        │
      │      id_token }              │                        │
      │◄─────────────────────────────│                        │

# Step 1 — Generate PKCE verifier + challenge
CODE_VERIFIER=$(openssl rand -base64 64 | tr '+/' '-_' | tr -d '=\n')
CODE_CHALLENGE=$(echo -n "$CODE_VERIFIER" | openssl dgst -sha256 -binary | base64 | tr '+/' '-_' | tr -d '=')

# Step 2 — Redirect user to authorization endpoint
open "http://localhost:8080/realms/master/protocol/openid-connect/auth?\
response_type=code&client_id=my-app&redirect_uri=http://localhost:3000/callback&\
scope=openid+profile+email&code_challenge=$CODE_CHALLENGE&code_challenge_method=S256"

# Step 5 — Exchange code for tokens
curl -X POST http://localhost:8080/realms/master/protocol/openid-connect/token \
-d "grant_type=authorization_code" \
-d "code=<auth_code>" \
-d "redirect_uri=http://localhost:3000/callback" \
-d "client_id=my-app" \
-d "code_verifier=$CODE_VERIFIER"

Client Credentials

For server-to-server communication — no user involved.

curl -X POST http://localhost:8080/realms/master/protocol/openid-connect/token \
-u "backend-service:client-secret" \
-d "grant_type=client_credentials" \
-d "scope=openid"

OIDC Endpoints

JWT Access Token Structure

Tokens are signed with RSA-2048 (RS256). Verify using the JWKS endpoint.

{
"iss": "http://localhost:8080/realms/master",
"sub": "usr_abc123",
"aud": ["my-app"],
"exp": 1705312800,
"iat": 1705309200,
"jti": "550e8400-e29b-41d4-a716-446655440000",
"realm": "master",
"email": "alice@example.com",
"email_verified": true,
"roles": ["ROLE_ADMIN", "ROLE_USER"],
"scope": "openid profile email"
}

Token Validation

Spring Boot Resource Server:

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class ResourceServerConfig {

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
  return http
    .authorizeHttpRequests(auth -> auth
      .requestMatchers("/public/**").permitAll()
      .anyRequest().authenticated()
    )
    .oauth2ResourceServer(oauth2 -> oauth2
      .jwt(jwt -> jwt.jwkSetUri(
        "http://localhost:8080/realms/master/protocol/openid-connect/certs"
      ))
    )
    .build();
}
}