guillaume
/
ansible-keycloak
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update documentation

main
Guido Grazioli 2022-01-27 16:34:06 +01:00
parent c5ee73cffc
commit dbad4ea086
No known key found for this signature in database
GPG Key ID: 22C8C31EF2BC093B
2 changed files with 106 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
README.md
View File

@ -46,56 +46,70 @@ A requirement file is provided to install:
## Usage ## Usage
### Install Playbook ### Install Playbook
`playbooks/keycloak.yml` installs the upstream(Keycloak) based on the defined variables. * [`playbooks/keycloak.yml`](playbooks/keycloak.yml) installs the upstream(Keycloak) based on the defined variables.
`playbooks/rhsso.yml` installs Red Hat Single Sign-On(RHSSO) based on defined variables. * [`playbooks/rhsso.yml`](playbooks/rhsso.yml) installs Red Hat Single Sign-On(RHSSO) based on defined variables.
### Choosing between upstream(Keycloak) project and Red Hat Single Sign-On(RHSSO) Both playbooks include the `keycloak` role, with different settings, as described in the following sections.
The roles supports installing upstream(Keycloak) or Red Hat Single Sign-On in the following ways For service configuration details, refer to the [keycloak role README](roles/keycloak/README.md).
#### Install upstream(Keycloak) from remote source
This is default approach, there is one required variable ### Choosing between upstream project (Keycloak) and Red Hat Single Sign-On (RHSSO)
``` The general flag `keycloak_rhsso_enable` controls what to install between upstream(Keycloak, when `False`) or Red Hat Single Sign-On (when `True`).
keycloak_admin_password: "<changeme>" The default value for the flag if `True` when Red Hat Network credentials are defined, `False` otherwise.
```
#### Install upstream(Keycloak) from local source when the following variable is defined
``` #### Install upstream (Keycloak) from keycloak releases
keycloak_admin_password: "<changeme>"
zip_file_local_path: <keycloak zip file on Ansible control node local path>
```
#### Install RHSSO from the Red Hat Customer Support Portal, when the following variables are defined This is the default approach when RHN credentials are not defined. Keycloak is downloaded from keycloak builds (hosted on github.com) locally, and distributed to target nodes.
```
keycloak_admin_password: "<changeme>" #### Install RHSSO from the Red Hat Customer Support Portal
Define the credentials as follows, and the default behaviour is to download a fresh archive of RHSSO on the controller node, then distribute to target nodes.
```yaml
rhn_username: '<customer_portal_username>' rhn_username: '<customer_portal_username>'
rhn_password: '<customer_portal_password>' rhn_password: '<customer_portal_password>'
rhsso_rhn_id: '<sso_product_id>' # (keycloak_rhsso_enable defaults to True)
``` ```
where `sso_product_id` is the ID for the specific Red Hat Single Sign-On version, ie. _101971_ will install version _7.5_)
#### Install RHSSO from remote sources like Nexus etc, when the following variables are defined #### Install from controller node (local source)
Making the keycloak zip archive (or the RHSSO zip archive), available to the playbook repository root directory, and setting `keycloak_offline_install` to `True`, allows to skip
the download tasks. The local path for the archive matches the downloaded archive path, so it is also used as a cache when multiple hosts are provisioned in a cluster.
```yaml
keycloak_offline_install: True
``` ```
keycloak_admin_password: "<changeme>"
And depending on `keycloak_rhsso_enable`:
* `True`: install RHSSO using file rh-sso-x.y.z-server-dist.zip
* `False`: install keycloak using file keycloak-x.y.zip
#### Install from alternate sources (like corporate Nexus, artifactory, proxy, etc)
For RHSSO:
```yaml
keycloak_rhsso_enable: True keycloak_rhsso_enable: True
rhsso_source_download_url: '<url to download RHSSO zip file>' keycloak_rhsso_download_url: "https://<internal-nexus.private.net>/<path>/<to>/rh-sso-x.y.z-server-dist.zip"
``` ```
#### Install RHSSO from local source when the following variable is defined For keycloak:
```yaml
keycloak_rhsso_enable: False
keycloak_download_url: "https://<internal-nexus.private.net>/<path>/<to>/keycloak-x.y.zip"
``` ```
keycloak_admin_password: "<changeme>"
keycloak_rhsso_enable: True
zip_file_local_path: <rhsso zip file on Ansible control node local path>
```
### Example installation command ### Example installation command
@ -113,17 +127,20 @@ ansible-playbook -i <ansible_hosts> -e @rhn-creds.yml playbooks/keycloak.yml -e
localhost ansible_connection=local localhost ansible_connection=local
``` ```
## Configuration ## Configuration
### Config Playbook ### Config Playbook
`playbooks/keycloak-realm.yml` creates provided realm, user federation(s), client(s), client role(s) and client user(s) if they don't exist. [`playbooks/keycloak-realm.yml`](playbooks/keycloak-realm.yml) creates provided realm, user federation(s), client(s), client role(s) and client user(s) if they don't exist.
### Example configuration command ### Example configuration command
Execute the following command from the source root directory Execute the following command from the source root directory
``` ```bash
ansible-playbook -i <ansible_hosts> playbooks/keycloak-realm.yml -e keycloak_admin_password=<changeme> -e keycloak_realm=test ansible-playbook -i <ansible_hosts> playbooks/keycloak-realm.yml -e keycloak_admin_password=<changeme> -e keycloak_realm=test
``` ```
@ -136,6 +153,9 @@ ansible-playbook -i <ansible_hosts> playbooks/keycloak-realm.yml -e keycloak_adm
localhost ansible_connection=local localhost ansible_connection=local
``` ```
For configuration details, refer to the [keycloak_realm role README](roles/keycloak_realm/README.md).
## License ## License
Apache License v2.0 or later Apache License v2.0 or later

102
roles/keycloak/README.md
View File

@ -14,6 +14,15 @@ This role requires the `python3-netaddr` library installed on the controller nod
* or via the collection: `pip install -r requirements.txt` * or via the collection: `pip install -r requirements.txt`
Dependencies
------------
The roles depends on:
* the `redhat_csp_download` role from [middleware_automation.redhat_csp_download](https://github.com/ansible-middleware/redhat-csp-download) collection if Red Hat Single Sign-on zip have to be downloaded from RHN.
* the `wildfly_driver` role from [middleware_automation.wildfly](https://github.com/ansible-middleware/wildfly) collection
Versions Versions
-------- --------
@ -25,9 +34,10 @@ Versions
Role Defaults Role Defaults
------------- -------------
* Service configuration
| Variable | Description | Default | | Variable | Description | Default |
|:---------|:------------|:---------| |:---------|:------------|:---------|
|`keycloak_rhsso_enable`| Enable Red Hat Single Sign-on installation | `False` |
|`keycloak_ha_enabled`| Enable auto configuration for database backend, clustering and remote caches on infinispan | `False` | |`keycloak_ha_enabled`| Enable auto configuration for database backend, clustering and remote caches on infinispan | `False` |
|`keycloak_db_enabled`| Enable auto configuration for database backend | `True` if `keycloak_ha_enabled` is True, else `False` | |`keycloak_db_enabled`| Enable auto configuration for database backend | `True` if `keycloak_ha_enabled` is True, else `False` |
|`keycloak_admin_user`| Administration console user account | `admin` | |`keycloak_admin_user`| Administration console user account | `admin` |
@ -41,7 +51,6 @@ Role Defaults
|`keycloak_management_https_port`| TLS management port | `9993` | |`keycloak_management_https_port`| TLS management port | `9993` |
|`keycloak_java_opts`| Additional JVM options | `-Xms1024m -Xmx2048m` | |`keycloak_java_opts`| Additional JVM options | `-Xms1024m -Xmx2048m` |
|`keycloak_prefer_ipv4`| Prefer IPv4 stack and addresses for port binding | `True` | |`keycloak_prefer_ipv4`| Prefer IPv4 stack and addresses for port binding | `True` |
|`keycloak_offline_install` | perform an offline install | `False`|
|`keycloak_config_standalone_xml`| filename for configuration | `keycloak.xml` | |`keycloak_config_standalone_xml`| filename for configuration | `keycloak.xml` |
|`keycloak_service_user`| posix account username | `keycloak` | |`keycloak_service_user`| posix account username | `keycloak` |
|`keycloak_service_group`| posix account group | `keycloak` | |`keycloak_service_group`| posix account group | `keycloak` |
@ -49,6 +58,19 @@ Role Defaults
|`jvm_package`| RHEL java package runtime | `java-1.8.0-openjdk-devel` | |`jvm_package`| RHEL java package runtime | `java-1.8.0-openjdk-devel` |
* Install options
| Variable | Description | Default |
|:---------|:------------|:---------|
|`keycloak_rhsso_enable`| Enable Red Hat Single Sign-on installation | `False` |
|`keycloak_offline_install` | perform an offline install | `False`|
|`keycloak_download_url`| Download URL for keycloak | `https://github.com/keycloak/keycloak/releases/download/<version>/<archive>`|
|`keycloak_rhsso_download_url`| Download URL for RHSSO | `https://access.redhat.com/jbossnetwork/restricted/softwareDownload.html?softwareId=<productID>`|
|`keycloak_version`| keycloak.org package version | `15.0.2` |
|`keycloak_rhsso_version`| RHSSO version | `7.5.0` |
|`keycloak_dest`| Installation root path | `/opt/keycloak` |
Role Variables Role Variables
-------------- --------------
@ -84,32 +106,14 @@ The following variables are _required_ only when `keycloak_db_enabled` is True:
|`keycloak_db_user` | username for connecting to postgres | `keycloak-user` | |`keycloak_db_user` | username for connecting to postgres | `keycloak-user` |
|`keycloak_db_pass` | password for connecting to postgres | `keycloak-pass` | |`keycloak_db_pass` | password for connecting to postgres | `keycloak-pass` |
The following variable can be used to install Keycloak or Red Hat Single Sign-On from local path:
| Variable | Description | Example | Example Playbooks
|:---------|:------------|:---------| -----------------
|`zip_file_local_path` | Full local path of upstream(Keycloak) or Red Hat Single Sign-On zip file on Ansible control plane | `tmp/rhsso/rh-sso-7.5-server-dist.zip` |
The following variable can be used to install Red Hat Single Sign-On from source via url, auth support is not added right now. _NOTE_: use ansible vaults or other security systems for storing credentials.
| Variable | Description | Example |
|:---------|:------------|:---------|
|`rhsso_source_download_url` | URL to download Red Hat Single Sign-On zip file from source | `http://localhost:8081/nexus/rhsso/rh-sso-7.5-server-dist.zip` |
Dependencies * The following is an example playbook that makes use of the role to install keycloak from remote:
------------
The roles depends on:
* the `redhat_csp_download` role from [middleware_automation.redhat_csp_download](https://github.com/ansible-middleware/redhat-csp-download) collection if Red Hat Single Sign-on zip have to be downloaded from RHN.
* the `wildfly_driver` role from [middleware_automation.wildfly](https://github.com/ansible-middleware/wildfly) collection
Example Playbook
----------------
The following is an example playbook that makes use of the role to install keycloak from remote
```yaml ```yaml
--- ---
@ -124,23 +128,7 @@ The following is an example playbook that makes use of the role to install keycl
keycloak_admin_password: "changeme" keycloak_admin_password: "changeme"
``` ```
The following is an example playbook that makes use of the role to install keycloak from local path on Ansible node * The following is an example playbook that makes use of the role to install Red Hat Single Sign-On from RHN:
```yaml
---
- hosts: ...
collections:
- middleware_automation.keycloak
tasks:
- name: Include keycloak role
include_role:
name: keycloak
vars:
keycloak_admin_password: "changeme"
zip_file_local_path: "/tmp/keycloak/keycloak-16.1.0.zip" # This should be local path on Ansible node of upstream(keycloak) zip file
```
The following is an example playbook that makes use of the role to install Red Hat Single Sign-On from RHN
```yaml ```yaml
--- ---
@ -157,9 +145,30 @@ The following is an example playbook that makes use of the role to install Red H
vars: vars:
keycloak_admin_password: "changeme" keycloak_admin_password: "changeme"
keycloak_rhsso_enable: True keycloak_rhsso_enable: True
rhn_username: '<customer portal username>'
rhn_password: '<customer portal password>'
``` ```
The following is an example playbook that makes use of the role to install Red Hat Single Sign-On from source url
* The following example playbook makes use of the role to install keycloak from the controller node:
```yaml
---
- hosts: ...
collections:
- middleware_automation.keycloak
tasks:
- name: Include keycloak role
include_role:
name: keycloak
vars:
keycloak_admin_password: "changeme"
keycloak_offline_install: True
# This should be the filename of keycloak archive on Ansible node: keycloak-16.1.0.zip
```
* This playbook installs Red Hat Single Sign-On from an alternate url:
```yaml ```yaml
--- ---
@ -173,10 +182,12 @@ The following is an example playbook that makes use of the role to install Red H
vars: vars:
keycloak_admin_password: "changeme" keycloak_admin_password: "changeme"
keycloak_rhsso_enable: True keycloak_rhsso_enable: True
rhsso_source_download_url: "<REPLACE with - Source download url>" # This should be the full of remote source rhsso zip file keycloak_rhsso_download_url: "<REPLACE with download url>"
# This should be the full of remote source rhsso zip file and can contain basic authentication credentials
``` ```
The following is an example playbook that makes use of the role to install Red Hat Single Sign-On from local path on Ansible node
* The following is an example playbook that makes use of the role to install Red Hat Single Sign-On from the controller node:
```yaml ```yaml
--- ---
@ -190,7 +201,8 @@ The following is an example playbook that makes use of the role to install Red H
vars: vars:
keycloak_admin_password: "changeme" keycloak_admin_password: "changeme"
keycloak_rhsso_enable: True keycloak_rhsso_enable: True
zip_file_local_path: "/tmp/rhsso/rh-sso-7.5-server-dist.zip" # This should be local path on Ansible node of rhsso zip file keycloak_offline_install: True
# This should be the filename of rhsso zip file on Ansible node: rh-sso-7.5-server-dist.zip
``` ```
License License