January 25, 2025

Understanding CommonClientSessionModel in Keycloak

 The CommonClientSessionModel interface in Keycloak serves as a foundational component for managing client sessions. It provides methods and enums to handle session-specific attributes, actions, and execution states. Understanding and leveraging this interface is essential for building robust, secure, and dynamic authentication flows.

Key Features of CommonClientSessionModel

  1. Session Management: Provides methods to manage session-specific data like redirect URIs, actions, and protocols.
  2. Enums for Actions and Status: Defines enums such as Action and ExecutionStatus to standardize session behaviors and outcomes.
  3. Integration with Realms and Clients: Tightly coupled with RealmModel and ClientModel, enabling seamless integration into the Keycloak ecosystem.

Methods in CommonClientSessionModel

1. getRedirectUri and setRedirectUri

  • Purpose: Manage the URI to which the user is redirected after authentication.
  • Example:
sessionModel.setRedirectUri("https://example.com/callback");
String redirectUri = sessionModel.getRedirectUri();

2. getAction and setAction

  • Purpose: Define and retrieve the current action for the session.
  • Example:
sessionModel.setAction(CommonClientSessionModel.Action.AUTHENTICATE.name());
String action = sessionModel.getAction();

3. getProtocol and setProtocol

  • Purpose: Specify the protocol used in the session (e.g., OpenID Connect, SAML).
  • Example:
sessionModel.setProtocol("openid-connect");
String protocol = sessionModel.getProtocol();

4. getRealm and getClient

  • Purpose: Retrieve the associated realm and client models.
  • Example:
RealmModel realm = sessionModel.getRealm();
ClientModel client = sessionModel.getClient();

Enums in CommonClientSessionModel

1. Action

Defines actions that can be taken during a session. Examples include:

  • OAUTH_GRANT: Handles OAuth grants.
  • AUTHENTICATE: Initiates user authentication.
  • LOGGED_OUT: Represents a logged-out state.
  • USER_CODE_VERIFICATION: Used for verifying user codes in device flows.

Example: When to Use USER_CODE_VERIFICATION

  • Scenario: Implementing a device authorization grant flow where users enter a code to verify their identity.
  • Implementation:
sessionModel.setAction(CommonClientSessionModel.Action.USER_CODE_VERIFICATION.name());
// Handle user code verification logic here

2. ExecutionStatus

Defines the status of an authentication execution. Examples include:

  • FAILED: Execution failed.
  • SUCCESS: Execution succeeded.
  • CHALLENGED: A challenge was presented to the user.
  • EVALUATED_TRUE / EVALUATED_FALSE: Used for conditional checks.

Changing ExecutionStatus

To set or change the execution status, you can update the associated execution logic.

Example: Changing ExecutionStatus

AuthenticationExecutionModel execution = getExecution(realm, "execution-id");
execution.setExecutionStatus(ExecutionStatus.SUCCESS);
saveExecution(execution);

When to Use CommonClientSessionModel

1. Action-Specific Flows

Use setAction to dynamically assign actions based on the authentication flow. For example:

  • AUTHENTICATE: Used for standard login flows.
  • USER_CODE_VERIFICATION: Ideal for device login scenarios.

2. Tracking and Debugging Execution States

Leverage ExecutionStatus to monitor and debug authentication flows. For example:

  • Track failed executions and log error details.
  • Use CHALLENGED to understand where users faced challenges in the flow.

3. Protocol-Specific Implementations

Use getProtocol and setProtocol to differentiate between OIDC and SAML flows. This is especially useful in multi-protocol environments.

Best Practices

  1. State Management:

    • Ensure actions and execution statuses are updated correctly to prevent inconsistencies.
    • Use enums like ExecutionStatus to standardize status updates.

  2. Security:

    • Avoid storing sensitive data directly in session attributes.
    • Regularly validate session attributes to prevent unauthorized modifications.

  3. Error Handling:

    • Log and track execution failures using ExecutionStatus.
    • Provide meaningful error messages to guide users through challenges.

  4. Documentation:

    • Maintain detailed documentation for custom actions and execution flows.

  5. Testing:

    • Test all possible execution statuses to ensure robust handling of edge cases.

Additional Reading

By leveraging CommonClientSessionModel, you can build highly customizable and secure authentication flows tailored to your application's needs.

Posted by
Labels: