What Are Keycloak Database Roles

Keycloak stores role data in its relational database, typically PostgreSQL or MySQL. Roles are entities linked to either a realm or a specific client. Each row in the keycloak_role table represents one role definition, with columns defining name, description, composite relationships, and references to parent realms or clients. Database roles are used to determine authorization grants during token creation and validation.

Realm vs. Client Roles

Realm roles live at the global level for a realm. Client roles are scoped to a single client application. In the database, they share schema structure, but their references differ: realm roles link to REALM_ID; client roles link to CLIENT_ID. This separation allows identity architects to maintain strict boundaries between application-specific permissions and global rules.

Composite Roles

Composite roles aggregate multiple roles. The database tracks composites in join tables such as composite_role mapping parent roles to child roles. When a composite role is assigned to a user, all its child roles are automatically granted. This logic is efficient at runtime but requires careful design to avoid privilege escalation.

Role Assignments in the Database

Role mappings between users and roles are stored in tables like user_role_mapping and group_role_mapping. Users can inherit roles via group assignments, and Keycloak’s database ensures these relationships are chained correctly. When a token is generated, Keycloak queries these mappings to embed accurate claims.

Best Practices for Managing Database Roles

• Use consistent naming conventions to reduce confusion.
• Enforce least privilege by limiting realm roles to essential system-wide permissions.
• Monitor composite structures to detect unintended access propagation.
• Periodically audit role tables directly via SQL to verify mapping accuracy.

Performance Considerations

Keycloak’s role queries can impact token issuance speed if role structures become too deep. Optimize indexes on key columns like ROLE_ID, USER_ID, and GROUP_ID. Avoid excessive composite chaining, and confirm database statistics are up to date.

Security Implications

Database roles are a central attack surface. If compromised, they allow unauthorized token claims. Protect the underlying database with strong authentication, network isolation, and encrypted connections. Implement rigorous change controls before altering role data.

Mastering Keycloak database roles means controlling identity at the source. Done right, it gives you precision, speed, and confidence in your security posture. Done wrong, it opens doors you’ll never want opened.

See how role management can be streamlined, audited, and secured—try it live in minutes at hoop.dev.