This document explains how authentication works between the DDEC Web Application and Keycloak.
The DDEC Web Application uses OpenID Connect (OIDC) protocol to authenticate users through Keycloak. This provides:
The DDEC application is registered in Keycloak as a Client:
| Property | Value | Description |
|---|---|---|
| Client ID | ddecweb-client |
Unique identifier for DDEC application |
| Protocol | OpenID Connect | Authentication protocol used |
| Access Type | Public | Browser-based application |
| Standard Flow | Enabled | Uses Authorization Code flow |
Users are stored in Keycloak's user directory with:
| Role | Description | Access Level |
|---|---|---|
admin |
System administrator | Full access to all features |
ddecuser |
Standard user | Access to calibration functions |
Guest |
Read-only user | View data only |
IOSCHD |
Batch scheduler | Batch job management |
The diagram below shows how DDEC authenticates users through Keycloak:
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ │ │ │ │ │
│ User │ │ DDEC Web │ │ Keycloak │
│ Browser │ │ Application │ │ Server │
│ │ │ │ │ │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
│ 1. Access DDEC │ │
│───────────────────>│ │
│ │ │
│ 2. Redirect to Keycloak Login │
│<───────────────────│ │
│ │ │
│ 3. Login Page Request │
│─────────────────────────────────────────>
│ │ │
│ 4. Display Login Form │
│<─────────────────────────────────────────
│ │ │
│ 5. Submit Username/Password │
│─────────────────────────────────────────>
│ │ │
│ │ 6. Validate │
│ │ Credentials │
│ │ │
│ 7. Redirect with Authorization Code │
│<─────────────────────────────────────────
│ │ │
│ 8. Follow Redirect (with code) │
│───────────────────>│ │
│ │ │
│ │ 9. Exchange Code │
│ │ for Tokens │
│ │───────────────────>│
│ │ │
│ │ 10. Return Tokens │
│ │ (ID, Access, │
│ │ Refresh) │
│ │<───────────────────│
│ │ │
│ 11. Create Session, Show DDEC │
│<───────────────────│ │
│ │ │
User Accesses DDEC: User navigates to the DDEC Web Application URL
Redirect to Keycloak: DDEC detects no valid session and redirects to Keycloak login, including:
ddecweb-client)Login Page: Browser requests Keycloak login page
Display Form: Keycloak shows the login form
Submit Credentials: User enters username and password
Validation: Keycloak validates credentials against user store
Authorization Code: If valid, Keycloak redirects back to DDEC with an authorization code
Follow Redirect: Browser follows redirect to DDEC callback URL
Token Exchange: DDEC backend exchanges the authorization code for tokens
Tokens Returned: Keycloak returns:
Session Created: DDEC creates a user session and displays the application
The ID Token contains information about the authenticated user:
{
"exp": 1706500000,
"iat": 1706496400,
"sub": "user-uuid-here",
"preferred_username": "jsmith",
"email": "jsmith@example.com",
"given_name": "John",
"family_name": "Smith",
"realm_access": {
"roles": ["ddecuser", "admin"]
},
"resource_access": {
"ddecweb-client": {
"roles": ["calibration-manager"]
}
}
}
Used by DDEC to authorize requests. Contains:
| Token | Default Lifetime | Purpose |
|---|---|---|
| Access Token | 5 minutes | Short-lived for security |
| Refresh Token | 30 minutes | Used to get new access tokens |
| ID Token | 5 minutes | User identity information |
| Session | 30 minutes (idle) | Keycloak session timeout |
Roles Defined in Keycloak: Administrator creates roles in the DDECWEB realm
Roles Assigned to Users: Each user is assigned one or more roles
Roles Included in Token: When user logs in, their roles are included in the token
DDEC Checks Roles: Application checks roles before allowing access to features
The application uses Spring Security annotations to protect endpoints:
// Only admins can access
@PreAuthorize("hasRole('admin')")
public ResponseEntity<?> getAdminData() { ... }
// Any authenticated user
@PreAuthorize("hasRole('ANY')")
public ResponseEntity<?> downloadCalibration() { ... }
// Specific role required
@PreAuthorize("hasRole('ddecuser')")
public ResponseEntity<?> updateCalibration() { ... }
| Feature | admin | ddecuser | Guest | IOSCHD |
|---|---|---|---|---|
| View calibrations | ✓ | ✓ | ✓ | ✓ |
| Download calibrations | ✓ | ✓ | ✗ | ✗ |
| Release calibrations | ✓ | ✓ | ✗ | ✗ |
| User management | ✓ | ✗ | ✗ | ✗ |
| System configuration | ✓ | ✗ | ✗ | ✗ |
| Schedule batch jobs | ✓ | ✗ | ✗ | ✓ |
| View SPDB cache | ✓ | ✗ | ✗ | ✗ |
When a user successfully authenticates:
| Setting | Default | Configured |
|---|---|---|
| DDEC Session Timeout | 30 min | 3000 seconds (50 min) |
| Keycloak SSO Session | 30 min | Configurable in realm |
| Keycloak SSO Max | 10 hours | Maximum session length |
When a user logs out:
In application.yml:
keycloak:
realm: DDECWEB
resource: ddecweb-client
auth-server-url: https://keycloak-server:8443/auth
ssl-required: external
public-client: true
principal-attribute: preferred_username
use-resource-role-mappings: true
| Property | Description |
|---|---|
realm |
Keycloak realm name |
resource |
Client ID registered in Keycloak |
auth-server-url |
Keycloak server URL |
ssl-required |
Require SSL (external, all, none) |
public-client |
No client secret needed |
principal-attribute |
Which claim to use as username |
use-resource-role-mappings |
Use client-specific roles |
In Keycloak Admin Console under Clients → ddecweb-client:
| Setting | Value | Description |
|---|---|---|
| Client Protocol | openid-connect | Authentication protocol |
| Access Type | public | Browser-based app (no secret) |
| Standard Flow Enabled | ON | Authorization Code flow |
| Direct Access Grants | OFF | Disable password grant |
| Valid Redirect URIs | https://ddec-server:8080/* | Allowed callback URLs |
| Web Origins | https://ddec-server:8080 | CORS allowed origins |
| Issue | Possible Cause | Solution |
|---|---|---|
| Redirect loop | Invalid redirect URI | Check Valid Redirect URIs in Keycloak |
| 401 Unauthorized | Token expired | Refresh token or re-login |
| 403 Forbidden | Missing role | Assign required role to user |
| Invalid token | Clock skew | Sync time between servers |
| CORS error | Wrong Web Origins | Add DDEC URL to Web Origins |
Enable debug logging in DDEC:
logging:
level:
org.keycloak: DEBUG
org.springframework.security: DEBUG
Use https://jwt.io to decode and inspect tokens (for debugging only - never paste production tokens into online tools).