Tested up to 18.0.0
GuardianKey is a solution to protect systems against authentication attacks. It uses Machine Learning to analyze the user's behavior, threat intelligence, and psychometrics (or behavioral biometrics) and provides an attack risk in real-time.
The protected system (in the concrete case, KeyCloak/RH-SSO, via this extension) sends the events via REST for the GuardianKey on each login attempt and can notify users or even block the high-risk events. Also, there is a panel that presents dashboards about login attempts. There are cloud and product versions. Also, there is a free service for small environments.
Beyond the security, the GuardianKey solution provides a good user experience, because the user is not required to provide extra information or to execute tasks during the login. It is a painless high-security.
For more information, check https://guardiankey.io
Below, we describe how you can use the KeyCloak/RH-SSO's GuardianKey extension to access the GuardianKey engine in in cloud.
A video for this tutorial is available at https://youtu.be/R5QFcH4bXuA
In summary, you should:
- Register an user at https://panel.guardiankey.io/auth/register
- Deploy the GuardianKey extension in your KeyCloak/RH-SSO installation
- Configure the extension
- Check the events in the GuardianKey panel and protect your systems
More details in the sequel.
The KeyCloak/RH-SSO's GuardianKey extension does not register automatically in the cloud services, you must do this and get the deployment information (cryptographic keys, etc).
Just access the registering form at https://panel.guardiankey.io/auth/register and follow the instructions.
More details can be found at: https://guardiankey.io/panel-documentation/#accessing-for-the-first-time
To deploy the extension, you must:
- Download and move the
guardiankey.jarfile to theprovidersdirectory of your Keycloak/RH-SSO installation and running 'build', for example:
$ wget https://github.com/guardiankey/guardiankey-plugin-keycloak/releases/download/v0.9.3-beta/guardiankey.jar
$ cp guardiankey.jar /opt/keycloak-18.0.0/providers/
$ cd /opt/keycloak-18.0.0/
$ ./bin/kc.sh build
- Copy the e-mail template to your Keycloak/RH-SSO theme, for example:
$ cd /opt/keycloak-18.0.0
$ cp ./lib/lib/main/org.keycloak.keycloak-themes-18.0.0.jar /tmp
$ mkdir /tmp/a
$ cd /tmp/a
$ unzip /tmp/org.keycloak.keycloak-themes-18.0.0.jar
$ cp base /opt/keycloak-18.0.0/themes/custom
$ cd /opt/keycloak-18.0.0/themes/custom/email
$ wget https://raw.githubusercontent.com/guardiankey/guardiankey-plugin-keycloak/master/extra/guardiankey-security_alert.ftl
- Restart Keycloak/RH-SSO service
(go to item 4)
To deploy the extension, you must:
- Download and move the
guardiankey.jarfile to thedeploymentsdirectory of your KeyCloak/RH-SSO installation, for example:
$ wget https://github.com/guardiankey/guardiankey-plugin-keycloak/releases/download/v0.9.1-beta/guardiankey.jar
$ cp guardiankey.jar /opt/jboss/keycloak/standalone/deployments/
- Copy the e-mail template into the
emaildirectory of the theme used by your installation, for example:
$ wget https://raw.githubusercontent.com/guardiankey/guardiankey-plugin-keycloak/master/extra/guardiankey-security_alert.ftl
$ cp guardiankey-security_alert.ftl /opt/jboss/keycloak/themes/keycloak/email/
It is not needed to restart services, JBoss will automatically deploy the files.
In some seconds, the file guardiankey.jar.deployed should appear in the deployments directory.
If you have a problem in this phase, it will appear a file named guardiankey.jar.failed.
In this case, you can check its contents to have a clue about the problem.
- Copy the e-mail template into the
emaildirectory of the theme used by your installation, for example:
$ wget https://raw.githubusercontent.com/guardiankey/guardiankey-plugin-keycloak/master/extra/guardiankey-security_alert.ftl
$ cp guardiankey-security_alert.ftl /opt/jboss/keycloak/themes/keycloak/email/
It is not needed to restart services, JBoss will automatically deploy the files.
In some seconds, the file guardiankey.jar.deployed should appear in the deployments directory.
If you have a problem in this phase, it will appear a file named guardiankey.jar.failed.
In this case, you can check its contents to have a clue about the problem.
To enable GuardianKey to notify your users about suspicious authentication attempts, you have to configure the e-mail sending in your KeyCloak/RH-SSO instance. Probably, you already did this in order to use KeyCloak/RH-SSO. If no, in KeyCloak/RH-SSO admin interface, go to "Realm settings", e-mail tab, and provide an SMTP server for e-mail sending. For example, like in the screenshot presented below.
Currently, GuardianKey extension supports just Browser flows.
The built-in Browser flow provided by KeyCloak/RH-SSO cannot be modified.
So, you should copy this Browser flow to include the GuardianKey Authenticator provider in a new flow.
In KeyCloak/RH-SSO, go to Authentication. In the tab Flows, select the Browser flow,
click in the button copy, provide a new name, and confirm.
Screen presented in the image below.
Now, select the newly created browser flow, click in the button Add execution, select the provider GuardianKey Authenticator and save.
The GuardianKey Authenticator must be set-up to REQUIRED and should be last in the list, such as in the image below.
You have to open the GuardianKey's panel and get the deployment information
for your system.
It can be found when viewing an Authgroup, Deploy information tab, such as in the image below.
To configure the GuardianKey extension, you should go to the created flow and click in the Config link that is inside the Actions
menu of the GuardianKey Authenticator line in the flow. There will open a form like the one in the image below.
The Organization ID, AuthGroup ID, Key and IV are deployment information that can be found at GuardianKey's panel. The other fields are described below.
- Alias: any name for your reference.
- Service name and Agent ID: are sent in events to GuardianKey to identify the service and sender. Suggest to keep "KeyCloak" and "KeyCloakServer".
- Reverse DNS: put ON to send reverse DNS information for the events. Recommend ON.
- Send e-mails: if ON, it may notify your users if the risk of the event is above the notify threshold defined in the policy configured in the GuardianKey's panel for your authgroup. We recommend to tell your users that they may receive e-mails, before enabling this feature.
- Panel URL and API URL: must be "https://panel.guardiankey.io" and "https://api.guardiankey.io" if you are using the GuardianKey in cloud.
- Send only: if ON, the extension will send events to GuardianKey and will NOT wait for the GuardianKey's response. So, the extension will not be able to BLOCK or NOTIFY users via e-mail.
You must set the GuardianKey flow as the Browser flow for your realm.
In KeyCloak/RH-SSO, go to Authentication and tab Bindings. Set the created flow for GuardianKey as
the Browser flow and save. See image below.
GuardianKey also monitors the failed login attempts. To implement it in KeyCloak/RH-SSO, it is needed to add an event listener.
In KeyCloak/RH-SSO, go to Events, tab Config, and include the guardiankey-event-listener in the "Event Listeners" field (img below).
Finally, you can check if it's running. Just authenticate in a system that uses the KeyCloak/RH-SSO realm and check if the event appears in the GuardianKey's panel.
If you have troubles, you can find help in the links below. You can also send an e-mail to contact@guardiankey.io.