Automate your SSO with Ansible and Keycloak

The article Deploy Keycloak single sign-on with Ansible discussed how to automate the deployment of Keycloak. In this follow-up article, we’ll use that as a baseline and explore how to automate the configuration of the Keycloak single sign-on (SSO) server, including setting up users, specifying LDAP connection details, and so on.

Here again, to facilitate our automation, we will leverage an Ansible collection named middleware_automation.keycloak, specifically designed for this endeavor.

Install Keycloak with Ansible

In the previous article, we saw in detail how to automate the installation of Keycloak. For this new installment, we’ll start from there using the following playbook:

---
- name: Playbook for Keycloak Hosts
  hosts: keycloak
  vars:
    keycloak_admin_password: "remembertochangeme"
  collections:
    - middleware_automation.keycloak
  roles:
    - keycloak

This short playbook will take care of the installation of the single sign-on server itself, which already includes quite a few tasks to perform on the target system, including:

• Creating appropriate operating system user and group accounts (the name is keycloak for both)
• Downloading the installation archive from the Keycloak website
• Unarchiving the content while ensuring that all the files are associated with the appropriate user and groups along with the correct privileges
• Ensuring that the required version of the Java Virtual Machine (JVM) is installed
• Integrating the software into the host service management system (in our case, the Linux systemd daemon).

However, prior to running the playbook, we are going to enhance it even further to perform day two configurations of the Keycloak server, including the configuration of the SSO realm, clients, and users.

Configure single sign-on

The Ansible collection for Keycloak allows defining the realm, client, and users without adding a single, extra task. All that is needed is to define a few extra variables. Of course, those variables are quite structured and need to be formatted correctly for Ansible to be able to configure Keycloak appropriately. The following is a complete, working example of such a configuration:

---
- name: Playbook for Keycloak Hosts
  hosts: all
  vars:
    keycloak_admin_password: "remembertochangeme"
    keycloak_realm: TestRealm
  collections:
    - middleware_automation.keycloak
  roles:
    - keycloak
  tasks:
 - name: Keycloak Realm Role
    ansible.builtin.include_role:
        name: keycloak_realm
    vars:
        keycloak_client_default_roles:
        - TestRoleAdmin
        - TestRoleUser
        keycloak_client_users:
        - username: TestUser
            password: password
            client_roles:
            - client: TestClient
                role: TestRoleUser
                realm: "{{ keycloak_realm }}"
        - username: TestAdmin
            password: password
            client_roles:
            - client: TestClient
                role: TestRoleUser
                realm: "{{ keycloak_realm }}"
            - client: TestClient
                role: TestRoleAdmin
                realm: "{{ keycloak_realm }}"
        keycloak_realm: TestRealm
        keycloak_clients:
        - name: TestClient
            roles: "{{ keycloak_client_default_roles }}"
            realm: "{{ keycloak_realm }}"
            public_client: "{{ keycloak_client_public }}"
            web_origins: "{{ keycloak_client_web_origins }}"
            users: "{{ keycloak_client_users }}"
            client_id: TestClient

Note that this example, purposely, does not rely on any external sources (such as an LDAP server) so that it can be used easily, to test the collection without requiring the setup of any extra resources.

Because the SSO configuration is quite dense, we are going to break down each portion to not only provide additional insight, but to illustrate its significance in the SSO configuration.

Define the realm

The very first step is to define a realm, which, for the purpose of this article, contains the desired user and role details, but other capabilities provided by Keycloak that will be explored throughout the article. To create the realm, we just need to add one variable to our playbook:

…
            - client: TestClient
             role: TestRoleAdmin
             realm: "{{ keycloak_realm }}"
     keycloak_realm: TestRealm
     keycloak_clients:
…

Configure roles and users

The next portion of the variables provided populates the realm with the appropriate details related to users and roles. For the demonstration of this article, we added two users (and two roles) to the realm we are defining:

• TestAdmin: An admin user who can connect to the SSO server and configure the realm. This user belongs to both roles we defined above.
• TestClient: A user belonging to the realm and thus belongs only in the TestRoleUser.

…
        keycloak_client_default_roles:
         - TestRoleAdmin
         - TestRoleUser
     keycloak_client_users:
         - username: TestUser
         password: password
         client_roles:
             - client: TestClient
             role: TestRoleUser
             realm: "{{ keycloak_realm }}"
         - username: TestAdmin
         password: password
         client_roles:
             - client: TestClient
             role: TestRoleUser
             realm: "{{ keycloak_realm }}"
             - client: TestClient
             role: TestRoleAdmin
             realm: "{{ keycloak_realm }}"
…

Define Keycloak clients

The last portion of the variables defines the client associated with the roles so that their users can use the SSO service:

…
        keycloak_clients:
        - name: TestClient
            roles: "{{ keycloak_client_default_roles }}"
            realm: "{{ keycloak_realm }}"
            public_client: "{{ keycloak_client_public }}"
            web_origins: "{{ keycloak_client_web_origins }}"
            users: "{{ keycloak_client_users }}"

…

Run the playbook

That’s it! With these details provided, we can now run the playbook to deploy Keycloak and fully configure our SSO instance (based on the user's information inside the TestRealm). Execute the following command to execute the automation:

# systemctl status keycloak
● keycloak.service - keycloak Server
   Loaded: loaded (/etc/systemd/system/keycloak.service; enabled; vendor preset: disabled)
   Active: active (running) since Wed 2022-12-28 14:24:28 UTC; 26min ago
  Process: 1607 ExecStop=/opt/keycloak/keycloak-service.sh stop (code=exited, status=0/SUCCESS)
  Process: 1627 ExecStart=/opt/keycloak/keycloak-service.sh start (code=exited, status=0/SUCCESS)
 Main PID: 1742 (java)
   CGroup: /system.slice/keycloak.service
        ├─1630 /bin/sh /opt/keycloak/keycloak-18.0.2/bin/standalone.sh -Djboss.bind.address=0.0.0.0 -Djboss.http.port=8080 -Djboss.https.port=8443 -Djboss.management.http.port=9990 -Djbo>
        └─1742 /usr/lib/jvm/java-11-openjdk-11.0.17.0.8-2.el8_6.x86_64/bin/java -D[Standalone] -server -Xms1024m -Xmx2048m --add-exports=java.desktop/sun.awt=ALL-UNNAMED --add-exports=ja>

Dec 28 14:24:35 515ef9b313a5 keycloak-service.sh[1742]: 14:24:35,360 INFO  [org.jboss.resteasy.resteasy_jaxrs.i18n] (ServerService Thread Pool -- 59) RESTEASY002220: Adding singleton resour>
Dec 28 14:24:35 515ef9b313a5 keycloak-service.sh[1742]: 14:24:35,360 INFO  [org.jboss.resteasy.resteasy_jaxrs.i18n] (ServerService Thread Pool -- 59) RESTEASY002220: Adding singleton resour>
Dec 28 14:24:35 515ef9b313a5 keycloak-service.sh[1742]: 14:24:35,360 INFO  [org.jboss.resteasy.resteasy_jaxrs.i18n] (ServerService Thread Pool -- 59) RESTEASY002220: Adding singleton resour>
Dec 28 14:24:35 515ef9b313a5 keycloak-service.sh[1742]: 14:24:35,360 INFO  [org.jboss.resteasy.resteasy_jaxrs.i18n] (ServerService Thread Pool -- 59) RESTEASY002210: Adding provider singlet>
Dec 28 14:24:35 515ef9b313a5 keycloak-service.sh[1742]: 14:24:35,428 INFO  [org.wildfly.extension.undertow] (ServerService Thread Pool -- 59) WFLYUT0021: Registered web context: '/auth' for>
Dec 28 14:24:35 515ef9b313a5 keycloak-service.sh[1742]: 14:24:35,487 INFO  [org.jboss.as.server] (ServerService Thread Pool -- 42) WFLYSRV0010: Deployed "keycloak-server.war" (runtime-name >
Dec 28 14:24:35 515ef9b313a5 keycloak-service.sh[1742]: 14:24:35,522 INFO  [org.jboss.as.server] (Controller Boot Thread) WFLYSRV0212: Resuming server
Dec 28 14:24:35 515ef9b313a5 keycloak-service.sh[1742]: 14:24:35,524 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0025: Keycloak 18.0.2 (WildFly Core 18.1.1.Final) started in 8112ms>
Dec 28 14:24:35 515ef9b313a5 keycloak-service.sh[1742]: 14:24:35,526 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0060: Http management interface listening on http://127.0.0.1:9990/>
Dec 28 14:24:35 515ef9b313a5 keycloak-service.sh[1742]: 14:24:35,527 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0051: Admin console listening on http://127.0.0.1:9990

To go even further, we can add a check to our playbook that will use the Keycloak admin credentials to get a token from the SSO server. This emulates what will happen when a user tries to access an application using the SSO service. Thus, if it works fine, it confirms the service is functional:

- name: Verify token api call
  ansible.builtin.uri:
    url: "{{ keycloak_port }}/auth/realms/master/protocol/openid-connect/token"
    method: POST
    body: "client_id=admin-cli&username=admin&password={{ keycloak_admin_password }}&grant_type=password"
    validate_certs: no
    register: keycloak_auth_response
    until: keycloak_auth_response.status == 200
    retries: 2
    delay: 2

Conclusion

On top of deploying the Keycloak server, we have fully automated the configuration of our SSO. We can deploy a fully functional instance, in any environment, without any manual intervention. Most importantly, it is accomplished in a secure and repeatable fashion. With just this playbook, you can set up the entire infrastructure for SSO in a matter of minutes using the tooling provided by the Ansible Middleware project.

Cover Image by pvproductions on Freepik