Two Factor Auth using Duo with Keycloak

These are the steps to setup two factor authentication with Duo using Keycloak.

Install Keycloak Duo SPI

  1. Clone the Keycloak Duo SPI repo

    git clone https://github.com/OSC/keycloak-duo-spi.git
    cd keycloak-duo-spi
    git submodule update --init
    
  2. Edit pom.xml and ensure keycloak.version matches the version of Keycloak you are running.

  3. Build (with Docker) - produces target/keycloak-duo-spi-jar-with-dependencies.jar

    docker run --rm -it -v $(pwd):/keycloak-duo-spi -w /keycloak-duo-spi \
      ohiosupercomputer/keycloak_duo_spi_buildbox:latest mvn clean test package
    
  4. Build (without Docker) - produces target/keycloak-duo-spi-jar-with-dependencies.jar

    yum -y install maven
    cd build/duo_java/DuoWeb
    mvn clean test install
    cd ../../..
    mvn clean test package
    
  5. Copy the JAR file and necessary template files to Keycloak and instruct Keycloak to install the SPI

    sudo install -o keycloak -g keycloak -m 0644 target/keycloak-duo-spi-jar-with-dependencies.jar \
      /opt/keycloak-9.0.0/standalone/deployments/keycloak-duo-spi-jar-with-dependencies.jar
    sudo install -o keycloak -g keycloak -m 0644 src/main/resources/duo-mfa.ftl \
      /opt/keycloak-9.0.0/themes/base/login/duo-mfa.ftl
    sudo install -o keycloak -g keycloak -m 0644 /dev/null \
      /opt/keycloak-9.0.0/standalone/deployments/keycloak-duo-spi-jar-with-dependencies.jar.dodeploy
    

Configure Duo SPI

  1. Log into your Keycloak instance
  2. Choose the realm to configure in upper left corner, eg ondemand
  3. Choose Realm Settings in the left menu then Security Defenses tab
  4. Add frame-src https://*.duosecurity.com/ 'self'; to the beginning of the value for Content-Security-Policy
  5. Choose Authentication in the left menu
  6. While on Flows tab ensure the dropdown for the flow name is Browser and click Copy
  7. Name the new flow browser-with-duo
  8. For all items below Username Password Form delete them by choosing Actions then Delete
  9. Choose Actions for Browser-with-duo Forms and choose Add Execution
  10. Select the Duo MFA provider and click Save
  11. Click Actions for Duo MFA and select Config. Fill in all values as appropriate and select Save.
  12. Select Required for Duo MFA
  13. Choose the Bindings tab and set Browser Flow to browser-with-duo and choose Save

Users logging into Keycloak will be required to verify their identity using Duo.