Session Management

OpenGate IAM manages user sessions via opengate-session-service (port 8087) backed by Redis 7. Sessions track active logins per device and support remote revocation.

On this page

• How Sessions Work
• Session Lifetime
• Listing Sessions
• Revoking Sessions
• Token Revocation
• Single Sign-On

How Sessions Work

User authenticates (authorization_code flow)
         │
         ▼
Auth Service issues access_token + refresh_token
         │
         ▼
Session Service creates session record in Redis
         │
         ├─ Key: session:{realmId}:{sessionId}
         ├─ Fields: userId, realm, ipAddress, userAgent,
         │          createdAt, expiresAt, clientIds
         └─ TTL: 8 hours (default)

User makes API request → Gateway validates JWT
         │
         ▼
Gateway checks token blacklist (Redis)
         │
         ▼
Request forwarded to service if valid

Session Lifetime

Listing Sessions

# Get all active sessions for a user
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
"http://localhost:8080/api/sessions?realm=master&userId=usr_abc123"

[
{
  "sessionId": "sess-uuid-1",
  "userId": "usr_abc123",
  "realmId": "master",
  "ipAddress": "192.168.1.10",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  "createdAt": "2025-06-01T10:00:00Z",
  "expiresAt": "2025-06-01T18:00:00Z",
  "clientIds": ["opengate-console"]
}
]

Revoking Sessions

# Revoke a specific session (logs out that device)
curl -X DELETE \
-H "Authorization: Bearer $ADMIN_TOKEN" \
"http://localhost:8080/api/sessions/sess-uuid-1"

# Revoke ALL sessions for a user (force logout all devices)
curl -X DELETE \
-H "Authorization: Bearer $ADMIN_TOKEN" \
"http://localhost:8080/api/sessions?realm=master&userId=usr_abc123"

When a session is revoked, its JTI is added to the Redis blacklist. The gateway rejects all subsequent requests with that token immediately — no need to wait for token expiry.

Token Revocation

# Revoke an access or refresh token directly
curl -X POST http://localhost:8080/realms/master/protocol/openid-connect/revoke \
-d "token=<refresh_token>" \
-d "client_id=opengate-console"

Single Sign-On

Users who authenticate in one app within the same realm are automatically authenticated in other apps without re-entering credentials.

To force re-authentication:

# Add prompt=login to force credential re-entry
GET /realms/master/protocol/openid-connect/auth?...&prompt=login