January 25, 2025

Understanding Authenticator.createAuthSession in Keycloak

 

Welcome! Today, we're going to explore something called Authenticator.createAuthSession in Keycloak, and I'll explain it in a simple way so that even a 10-year-old can follow along. Imagine we’re setting up a clubhouse, and each member needs a special pass to enter. Keycloak helps us manage these passes and makes sure only the right people get inside.

Now, let’s dive in!

What is Keycloak?

Keycloak is like a big security guard for websites and apps. It keeps track of:

  • Who you are (your username)
  • How you prove it’s you (your password, OTP, or other methods)
  • What you’re allowed to do (permissions)

Whenever you log into an app or website, Keycloak helps you get inside if you’re allowed.

What is an Authentication Session?

When you try to log in, Keycloak creates a temporary "login ticket" for you. This ticket is called an authentication session. Think of it like a temporary pass that lets you move through different checkpoints (like entering your password or verifying an OTP) until you’re fully logged in.

Once the process is done:

  • If you pass all the checkpoints, you get a membership pass (a permanent session).
  • If you fail, your temporary pass is thrown away.

What Does Authenticator.createAuthSession Do?

Authenticator.createAuthSession is a function that creates this temporary pass (authentication session). Let’s understand the lifecycle step by step:

Lifecycle of Authenticator.createAuthSession

1. Check for an Existing Session

  • When a user tries to log in, Keycloak first checks if they already have an authentication session.
  • This prevents creating duplicate sessions for the same user, especially if they accidentally refresh the page or start the process again.
  • If an existing session is found, it will be reused.

2. Create a New Authentication Session

  • If no existing session is found, Keycloak creates a new authentication session.
  • This session acts as a placeholder for the login process and ensures that each step (e.g., entering username, password, or OTP) is tracked properly.
  • This is where the createAuthSession method kicks in to generate this session.

3. Bind the Session to the Realm and Client

  • The new session is linked to:
    • The realm: This is like a section of the clubhouse. It determines which group the user belongs to.
    • The client: This is the app or website the user is trying to access (e.g., the "Clubhouse App").
  • This binding ensures that the session is valid only for that specific app and group.

4. Add an Action to the Session

  • Actions define what the user is trying to do. For example:
    • LOGIN: The user is logging into the app.
    • RESET_PASSWORD: The user wants to reset their password.
  • This action helps Keycloak decide what steps to show next (e.g., OTP verification).

5. Store Session Details in the Context

  • The authentication session is saved in the Keycloak context.
  • This context is like a clipboard that Keycloak uses to store temporary information during the login process.
  • It ensures that every step of the login process has access to the necessary data (e.g., the user’s username or OTP).

6. Handle Expiration

  • If the user doesn’t complete the login process within a certain time (e.g., 5 minutes), the authentication session expires.
  • This ensures that temporary data doesn’t linger around forever and keeps the system secure.

7. Return the Authentication Session

  • Finally, the session is returned to the calling function, so the login process can continue.
  • The session is used for subsequent steps, like verifying the user’s password or sending an OTP.

Example Code (Simplified)

Here’s a fun way to understand createAuthSession with a code example. Think of it as creating a ticket in our clubhouse system:

public class AuthSessionManager {
    public AuthenticationSessionModel createAuthSession(KeycloakSession session, AuthenticationSessionManager authSessionManager) {
        AuthenticationSessionModel authSession = authSessionManager.getCurrentAuthenticationSession(session, session.getContext().getClient());

        if (authSession == null) {
            authSession = authSessionManager.createAuthenticationSession(session, session.getContext().getRealm(), session.getContext().getClient());
            authSession.setAction("LOGIN");

            System.out.println("New authentication session created!");
        } else {
            System.out.println("Reusing existing session.");
        }

        return authSession; // Return the ticket
    }
}

Walkthrough of the Code

  • Step 1: Check if a login ticket (authentication session) already exists.
  • Step 2: If no ticket exists, create a new one.
  • Step 3: Add information to the ticket, like which app you’re logging into.
  • Finally, return the ticket so the login process can continue.

Best Practices for createAuthSession

  1. Handle Expiry Gracefully:

    • Always define an appropriate timeout for authentication sessions to ensure security.

  2. Support Multiple Flows:

    • Use dynamic actions (LOGIN, MFA, PASSWORDLESS, etc.) to handle different login methods.

  3. Log and Monitor:

    • Log session creation and reuse events for debugging and auditing purposes.

  4. Secure Context Data:

    • Ensure sensitive information in the context is encrypted or sanitized properly.

Supporting Multiple Flows

Keycloak can handle various authentication flows, such as:

Passwordless (OTP-Based)

authSession.setAction("OTP_VERIFY");
// Send OTP to the user
otpService.sendOtp(user.getPhoneNumber());

Multi-Factor Authentication (MFA)

authSession.setAction("MFA_VERIFY");
// Trigger MFA using configured methods (e.g., TOTP, push notification)
mfaService.triggerMFA(user.getId());

Username and Password

authSession.setAction("LOGIN");
// Proceed with password verification
authManager.verifyPassword(user, providedPassword);

Using AuthNote in Authentication

What is AuthNote?

AuthNote is a key-value store associated with an authentication session or user session. Think of it as a sticky note attached to a session or user, storing temporary information needed during the login process.

When to Use AuthNote?

  1. Session-Specific Data: Use AuthNote when you need to store data specific to the ongoing authentication session. For example:

    • Storing OTPs during a passwordless or multi-factor authentication (MFA) flow.
    • Keeping track of intermediate steps (e.g., if the user has verified their phone but not their email).

  2. User-Specific Data: Use AuthNote for temporary data about a user that doesn’t need to persist across multiple sessions. For example:

    • Storing a one-time token for resetting passwords.
    • Keeping a flag for specific actions like user consent during login.

  3. Dynamic Flows: Use AuthNote when implementing custom authentication flows with multiple steps.

Code Examples for AuthNote

Passwordless Authentication (OTP-Based)

// Step 1: Generate and store OTP in the session
String otp = otpService.generateOtp();
authSession.setAuthNote("OTP", otp);

// Step 2: Send OTP to the user
otpService.sendOtp(user.getPhoneNumber());

// Step 3: Verify the OTP
String providedOtp = formParameters.get("otp");
String storedOtp = authSession.getAuthNote("OTP");

if (!storedOtp.equals(providedOtp)) {
    throw new AuthenticationException("Invalid OTP");
}

Multi-Factor Authentication (MFA)

// Step 1: Add a note for MFA
String mfaToken = mfaService.generateToken();
authSession.setAuthNote("MFA_TOKEN", mfaToken);

// Step 2: Verify MFA token
String providedMfaToken = formParameters.get("mfaToken");
String storedMfaToken = authSession.getAuthNote("MFA_TOKEN");

if (!storedMfaToken.equals(providedMfaToken)) {
    throw new AuthenticationException("Invalid MFA Token");
}

Things to Remember

  • Expiration Policy: Always configure session expiration to prevent stale sessions.
  • Error Handling: Use clear error messages when authentication fails.
  • Custom Flows: Customize actions to fit your application’s needs.
  • Session Reuse: Avoid creating multiple sessions unnecessarily by checking for existing ones.
  • Security: Protect the session context to prevent leaks.
  • Use AuthNote Wisely: Don’t overload the session with unnecessary data. Only store what’s required for the current flow.

Conclusion

Authenticator.createAuthSession is like a system that gives you a temporary pass to start logging into an app. It’s an

Posted by