Authentication

The HERCULES SGI system uses Keycloak 13.0.0 as its authentication and authorization server. This guide covers Keycloak setup, realm configuration, and user management.

Keycloak Overview

Keycloak provides:

Single Sign-On (SSO) across all SGI services
OAuth2/OpenID Connect authentication
Role-Based Access Control (RBAC)
User Federation (LDAP, Active Directory)
Identity Brokering (SAML, Social Login)

SGI uses Keycloak 13.0.0 specifically. Using other versions may cause compatibility issues.

Keycloak Installation

Docker Deployment (Recommended)

The SGI authentication server extends the official Keycloak image:

# Build the custom Keycloak image
cd sgi-auth
mvn clean package -DskipTests
docker build -t sgi-auth:1.1.0 .

# Run Keycloak
docker run -d \
  --name sgi-auth \
  -p 8080:8080 \
  -e KEYCLOAK_USER=admin \
  -e KEYCLOAK_PASSWORD=admin \
  -e DB_VENDOR=postgres \
  -e DB_ADDR=postgres \
  -e DB_DATABASE=keycloak \
  -e DB_USER=keycloak \
  -e DB_PASSWORD=keycloak \
  sgi-auth:1.1.0

Standalone Installation

For non-containerized deployment:

Download Keycloak

Download Keycloak 13.0.0:

wget https://github.com/keycloak/keycloak/releases/download/13.0.0/keycloak-13.0.0.tar.gz
tar -xzf keycloak-13.0.0.tar.gz
cd keycloak-13.0.0

Configure Database

Configure Keycloak to use PostgreSQL (recommended for production):

# Edit standalone/configuration/standalone.xml
# Add PostgreSQL datasource configuration

Or use the H2 embedded database for development.

Install Custom Extensions

Install SGI’s custom SAML broker mappers:

cp sgi-auth/broker-saml-mappers/target/broker-saml-mappers-*.jar \
   keycloak-13.0.0/standalone/deployments/

Start Keycloak

cd keycloak-13.0.0/bin
./standalone.sh -Djboss.bind.address=0.0.0.0

Access the admin console at: http://localhost:8080/auth

SGI Realm Configuration

Importing the SGI Realm

SGI provides a pre-configured realm with all necessary clients, roles, and settings.

Locate the Realm File

The realm configuration is in sgi-auth/realm/sgi-realm.json.

Security Alert: The default realm file contains example credentials and secrets. Do not use in production without customization!

Import the Realm

Option 1: Admin Console (Recommended)

Login to Keycloak admin console: http://localhost:8080/auth
Hover over the realm dropdown (top-left)
Click “Add realm”
Select “Import” and choose sgi-realm.json
Click “Create”

Option 2: Command Line

# Using Docker
docker exec -it sgi-auth \
  /opt/jboss/keycloak/bin/standalone.sh \
  -Djboss.socket.binding.port-offset=100 \
  -Dkeycloak.migration.action=import \
  -Dkeycloak.migration.provider=singleFile \
  -Dkeycloak.migration.file=/realm/sgi-realm.json \
  -Dkeycloak.migration.strategy=OVERWRITE_EXISTING

Verify Realm Import

Check that the realm was imported successfully:

Select the sgi realm from the dropdown
Navigate to “Realm Settings”
Verify the realm name is sgi
Check “Clients” - you should see multiple clients (front, csp-service, eti-service, etc.)

Realm Settings

The SGI realm includes these important settings:

Realm

string

default:"sgi"

Realm identifier used in OAuth2 configuration.

Access Token Lifespan

integer

default:"300"

Access token validity in seconds (5 minutes).

SSO Session Idle

integer

default:"1800"

SSO session idle timeout in seconds (30 minutes).

SSO Session Max

integer

default:"36000"

Maximum SSO session lifespan in seconds (10 hours).

Offline Session Idle

integer

default:"2592000"

Offline session idle timeout in seconds (30 days).

Client Configuration

The SGI realm includes multiple OAuth2 clients:

Frontend Client (`front`)

Frontend Client Configuration

Client ID: front
Client Protocol: openid-connect
Access Type: public
Valid Redirect URIs:

http://localhost:4200/* (development)
https://sgi.example.com/* (production)

Web Origins:

http://localhost:4200 (development)
https://sgi.example.com (production)

Configuration steps:

Navigate to Clients → front
Update Valid Redirect URIs for your domain
Update Web Origins to match your frontend URL
Save changes

{
  "clientId": "front",
  "enabled": true,
  "protocol": "openid-connect",
  "publicClient": true,
  "redirectUris": [
    "https://sgi.example.com/*"
  ],
  "webOrigins": [
    "https://sgi.example.com"
  ]
}

Backend Service Clients

Each backend service has its own client for service-to-service authentication:

CSP Service Client

Client ID: csp-service
Access Type: confidential
Service Accounts Enabled: true
Authorization Enabled: true

Change the client secret before production deployment!The default secret in the realm file is: cf693c2b-bdaf-4f98-87db-e7996b917b0a

To generate a new client secret:

Navigate to Clients → csp-service
Go to Credentials tab
Click Regenerate Secret
Copy the new secret
Update the secret in your service’s application.yml:

spring:
  security:
    oauth2:
      client:
        registration:
          csp-service:
            client-secret: YOUR_NEW_SECRET_HERE

Other Service Clients

Similar configuration for other services:

eti-service - Ethics Committee service
pii-service - Intellectual Property service
cnf-service - Configuration service
com-service - Communications service
tp-service - Third Parties service
usr-service - User management service
rel-service - Relations service
rep-service - Reports service
prc-service - Processing service
eer-service - External Evaluation Reports service

Each client requires:

Unique client secret (regenerate for production)
Service account roles configured
Scope mappings to access other services

Role Configuration

SGI uses role-based access control with module-specific roles.

Role Naming Convention

Roles follow the pattern: [MODULE]-[PERMISSION] Examples from the CSP (Calls, Solicitudes, Proyectos) module:

CSP-ROLE-R - Read permission
CSP-ROLE-E - Edit permission
CSP-ROLE-C - Create permission
CSP-ROLE-B - Delete (Borrar) permission

Module Roles

The SGI realm includes roles for these modules:

CSP Module Roles (Calls, Applications, Projects)

CSP-ROLE-R - View calls, applications, and projects
CSP-ROLE-E - Edit existing records
CSP-ROLE-C - Create new records
CSP-ROLE-B - Delete records
CSP-ROLS-R - View funding requests
CSP-ROLS-E - Edit funding requests
CSP-ROLS-C - Create funding requests
CSP-ROLS-B - Delete funding requests

ETI Module Roles (Ethics Committee)

ETI-ACT-V - View committee acts
ETI-ACT-E - Edit committee acts
ETI-EVR-V - View evaluations
ETI-EVR-EVALR - Evaluate as evaluator
ETI-MEM-V - View memories
ETI-MEM-E - Edit memories

PII Module Roles (Intellectual Property)

PII-INV-V - View inventions
PII-INV-E - Edit inventions
PII-INV-C - Create inventions
PII-INV-B - Delete inventions

Administrative Roles

ADMINISTRADOR-CSP - CSP module administrator
ADMINISTRADOR-ETI - ETI module administrator
ADMINISTRADOR-PII - PII module administrator
SYSADM-CSP - CSP system administrator
UNIDAD-GESTION - Management unit access

Assigning Roles to Users

Navigate to User

In Keycloak admin console:

Select the sgi realm
Click Users in the left menu
Find and select the user

Assign Realm Roles

Go to Role Mappings tab
Under Available Roles, select roles to assign
Click Add selected
Assigned roles appear in Assigned Roles section

Verify Role Assignment

Test the user can access appropriate SGI modules:

# Get access token
curl -X POST "http://localhost:8080/auth/realms/sgi/protocol/openid-connect/token" \
  -d "client_id=front" \
  -d "username=testuser" \
  -d "password=password" \
  -d "grant_type=password"

# Decode the JWT to verify roles

User Management

Creating Users

Add New User

Navigate to Users → Add user
Fill in user details:
- Username (required)
- Email
- First Name
- Last Name
Set Email Verified to ON
Click Save

Set Password

Go to Credentials tab
Set password
Set Temporary to OFF for permanent password
Click Set Password

Configure User Attributes

SGI requires the user_ref_id attribute:

Go to Attributes tab
Add attribute:
- Key: user_ref_id
- Value: External user reference ID (e.g., employee ID)
Click Save

The user_ref_id is used to link Keycloak users with external systems (HR, LDAP, etc.).

Assign Roles

Follow the role assignment steps in the previous section.

User Federation

Connect Keycloak to LDAP or Active Directory:

LDAP Configuration

Navigate to User Federation → Add provider → ldap
Configure LDAP settings:

Edit Mode

string

default:"READ_ONLY"

How users are edited. Use READ_ONLY for authoritative LDAP.

Vendor

string

LDAP server type (Active Directory, Red Hat Directory Server, etc.).

Connection URL

string

required

LDAP connection string (e.g., ldap://ldap.example.com:389).

Users DN

string

required

Base DN for users (e.g., ou=users,dc=example,dc=com).

Bind DN

string

required

Service account DN for binding to LDAP.

Bind Credential

string

required

Password for the bind DN.

Configure attribute mappings to match SGI requirements
Test connection and authentication
Synchronize users

Security Considerations

Critical Security Tasks Before Production:

Change all client secrets - Regenerate secrets for all service clients
Update admin credentials - Change default admin username/password
Enable HTTPS - Configure TLS certificates for Keycloak
Configure CORS - Restrict valid redirect URIs and web origins
Enable brute force protection - In Realm Settings → Security Defenses
Review token lifespans - Adjust based on security requirements
Audit roles and permissions - Remove unnecessary roles from realm
Backup realm configuration - Export realm regularly

Rotating Client Secrets

Refer to the official guide in the source repository: sgi-auth/docs/keycloak-secrets-rotation.md

Generate New Secret

For each service client:

Navigate to Clients → [client-name] → Credentials
Click Regenerate Secret
Copy the new secret

Update Service Configuration

Update each service’s application.yml or environment variables:

# Using environment variable
export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_CSP_SERVICE_CLIENT_SECRET="new_secret"

# Or in application.yml
spring:
  security:
    oauth2:
      client:
        registration:
          csp-service:
            client-secret: new_secret

Restart Services

Restart each service to apply the new secret:

# Docker
docker restart sgi-csp-service

# Systemd
systemctl restart sgi-csp-service

Verify Connectivity

Test that services can still authenticate:

# Check service health endpoints
curl http://localhost:4281/actuator/health

CVE-2020-27838 Mitigation

SGI 1.0.0 updates Keycloak to version 13.0.0 to address CVE-2020-27838, a security vulnerability in earlier Keycloak versions.Ensure you’re using Keycloak 13.0.0 or later.

Sensitive Information in Realm Export

The default sgi-realm.json contains sensitive information including:

Example user credentials
Client secrets
Sample role assignments

Action Required: Before production deployment:

Import the realm
Change all credentials and secrets
Remove example users
Export a clean realm configuration for your environment

Token Configuration

Configure JWT tokens for optimal security and performance:

Access Token Settings

Navigate to Realm Settings → Tokens
Configure token lifespans:

Access Token Lifespan

duration

default:"5 minutes"

How long access tokens are valid. Shorter is more secure but requires more token refreshes.

Timeout for OAuth2 authorization code flow.

Refresh Token Max Reuse

integer

default:"0"

How many times a refresh token can be reused (0 = single use).

Token Claims

SGI uses these custom claims:

user_ref_id - External user reference ID
authorities - User roles and permissions
sub - Subject (Keycloak user ID)

Claims are automatically included in JWT tokens.

Troubleshooting

Realm Import Fails

Problem: Realm import fails with validation errors. Solution:

# Check realm file validity
jq . sgi-auth/realm/sgi-realm.json

# Import with partial import strategy
-Dkeycloak.migration.strategy=IGNORE_EXISTING

Invalid Redirect URI

Problem: Login fails with “Invalid redirect URI” error. Solution: Update the front client’s Valid Redirect URIs to match your frontend URL.

Client Secret Mismatch

Problem: Services can’t authenticate with “invalid_client” error. Solution: Verify client secret matches between Keycloak and service configuration.

User Attribute Missing

Problem: JWT token missing user_ref_id claim. Solution:

Add user_ref_id attribute to user
Configure client mapper:
- Clients → front → Mappers → Create
- Mapper Type: User Attribute
- User Attribute: user_ref_id
- Token Claim Name: user_ref_id

Next Steps

Administrator Guide - Managing users and permissions
API Authentication - Using JWT tokens in API requests
Authorization - Role-based access control and permissions

Get Started

Core Modules

User Guides

Deployment

Keycloak Overview

Keycloak Installation

Docker Deployment (Recommended)

Standalone Installation

SGI Realm Configuration

Importing the SGI Realm

Realm Settings

Client Configuration

Frontend Client (`front`)

Backend Service Clients

Role Configuration

Role Naming Convention

Module Roles

Assigning Roles to Users

User Management

Creating Users

User Federation

Security Considerations

Rotating Client Secrets

CVE-2020-27838 Mitigation

Sensitive Information in Realm Export

Token Configuration

Access Token Settings

Token Claims

Troubleshooting

Realm Import Fails

Invalid Redirect URI

Client Secret Mismatch

User Attribute Missing

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Modules

User Guides

Deployment

​Keycloak Overview

​Keycloak Installation

​Docker Deployment (Recommended)

​Standalone Installation

​SGI Realm Configuration

​Importing the SGI Realm

​Realm Settings

​Client Configuration

​Frontend Client (front)

​Backend Service Clients

​Role Configuration

​Role Naming Convention

​Module Roles

​Assigning Roles to Users

​User Management

​Creating Users

​User Federation

​Security Considerations

​Rotating Client Secrets

​CVE-2020-27838 Mitigation

​Sensitive Information in Realm Export

​Token Configuration

​Access Token Settings

​Token Claims

​Troubleshooting

​Realm Import Fails

​Invalid Redirect URI

​Client Secret Mismatch

​User Attribute Missing

​Next Steps

Build docs developers (and LLMs) love

Keycloak Overview

Keycloak Installation

Docker Deployment (Recommended)

Standalone Installation

SGI Realm Configuration

Importing the SGI Realm

Realm Settings

Client Configuration

Frontend Client (`front`)

Backend Service Clients

Role Configuration

Role Naming Convention

Module Roles

Assigning Roles to Users

User Management

Creating Users

User Federation

Security Considerations

Rotating Client Secrets

CVE-2020-27838 Mitigation

Sensitive Information in Realm Export

Token Configuration

Access Token Settings

Token Claims

Troubleshooting

Realm Import Fails

Invalid Redirect URI

Client Secret Mismatch

User Attribute Missing

Next Steps