Table of Contents

• Description
• Deployment
• Testing the Flow
• Authentication Flow
• Security Considerations
• Appendix

Description

This project provides a method for creating a custom two-factor authentication flow. To achieve this, authenticator, required action, and credential providers are implemented.

Deployment

To package the sources, build the image, and deploy the services:

./start.sh

This will also copy a preconfigured realm with a custom authentication flow utilizing all the providers created.

Testing the Flow

• Preconfigured Realm: An already configured realm is copied into the image. You can view the configurations in the Keycloak Admin Console and authenticate using:
  • Username: admin
  • Password: admin.
• Preconfigured User: To test the flow, go to http://localhost:8080/realms/example/account and authenticate using:
  • Username: demo@example.com
  • Password: demo
  • 2FA Setup: As part of the realm configuration, the custom 2FA flow is already configured and is used by the account-console client. Therefore, as part of your first login, you will have to set up the 2FA.

Authentication Flow

The below browser flow has been created. The flow has 3 alternatives. The last alternative is the one configured to use the authentication SPI for the 2FA after normal login. The account-console client browser flow was overriden to use it. As part of the implementation of the authentication SPI, it is adding a required action using the implemented provider for the user to complete. The required action is creating the credential that was implemented using the credential provider.

Security Considerations

• Ensure that all alternative flows align with your security needs. For example, a user may go through 2FA whenever he is redirected by client X that is using your custom browser flow. However, if that same user was being redirected by another client Y that is not using your custom browser flow, then the user will not go through the steps in your custom flow.
• Consider adding an implementation of PasswordPolicyProvider if your credential provider is using a new type of password-like credential. Have a look at the built-in implementations of PasswordPolicyProvider.
• For simplicity, the credentials are not hashed when stored in this example. Keycloak will not do that when you are using your custom credential provider.

Appendix

User First Login

Admin