Update documentation
Guido Grazioli
parent
c5ee73cffc
commit
dbad4ea086
78
README.md
78
README.md
|
|
@ -46,56 +46,70 @@ A requirement file is provided to install:
|
|||
|
||||
## Usage
|
||||
|
||||
|
||||
### Install Playbook
|
||||
|
||||
`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/keycloak.yml`](playbooks/keycloak.yml) installs the upstream(Keycloak) based on the 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)
|
||||
|
||||
```
|
||||
keycloak_admin_password: "<changeme>"
|
||||
```
|
||||
The general flag `keycloak_rhsso_enable` controls what to install between upstream(Keycloak, when `False`) or Red Hat Single Sign-On (when `True`).
|
||||
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
|
||||
|
||||
```
|
||||
keycloak_admin_password: "<changeme>"
|
||||
zip_file_local_path: <keycloak zip file on Ansible control node local path>
|
||||
```
|
||||
#### Install upstream (Keycloak) from keycloak releases
|
||||
|
||||
#### 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_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
|
||||
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
|
||||
|
||||
|
|
@ -113,17 +127,20 @@ ansible-playbook -i <ansible_hosts> -e @rhn-creds.yml playbooks/keycloak.yml -e
|
|||
localhost ansible_connection=local
|
||||
```
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
|
||||
### 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
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
|
|
@ -136,6 +153,9 @@ ansible-playbook -i <ansible_hosts> playbooks/keycloak-realm.yml -e keycloak_adm
|
|||
localhost ansible_connection=local
|
||||
```
|
||||
|
||||
For configuration details, refer to the [keycloak_realm role README](roles/keycloak_realm/README.md).
|
||||
|
||||
|
||||
## License
|
||||
|
||||
Apache License v2.0 or later
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
||||
|
||||
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
|
||||
--------
|
||||
|
||||
|
|
@ -25,9 +34,10 @@ Versions
|
|||
Role Defaults
|
||||
-------------
|
||||
|
||||
* Service configuration
|
||||
|
||||
| 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_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` |
|
||||
|
|
@ -41,7 +51,6 @@ Role Defaults
|
|||
|`keycloak_management_https_port`| TLS management port | `9993` |
|
||||
|`keycloak_java_opts`| Additional JVM options | `-Xms1024m -Xmx2048m` |
|
||||
|`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_service_user`| posix account username | `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` |
|
||||
|
||||
|
||||
* 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
|
||||
--------------
|
||||
|
||||
|
|
@ -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_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 |
|
||||
|:---------|:------------|:---------|
|
||||
|`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` |
|
||||
Example Playbooks
|
||||
-----------------
|
||||
|
||||
The following variable can be used to install Red Hat Single Sign-On from source via url, auth support is not added right now.
|
||||
|
||||
| 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` |
|
||||
_NOTE_: use ansible vaults or other security systems for storing credentials.
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
Example Playbook
|
||||
----------------
|
||||
|
||||
The following is an example playbook that makes use of the role to install keycloak from remote
|
||||
* The following is an example playbook that makes use of the role to install keycloak from remote:
|
||||
|
||||
```yaml
|
||||
---
|
||||
|
|
@ -124,23 +128,7 @@ The following is an example playbook that makes use of the role to install keycl
|
|||
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
|
||||
|
||||
```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
|
||||
* The following is an example playbook that makes use of the role to install Red Hat Single Sign-On from RHN:
|
||||
|
||||
```yaml
|
||||
---
|
||||
|
|
@ -157,9 +145,30 @@ The following is an example playbook that makes use of the role to install Red H
|
|||
vars:
|
||||
keycloak_admin_password: "changeme"
|
||||
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
|
||||
---
|
||||
|
|
@ -173,10 +182,12 @@ The following is an example playbook that makes use of the role to install Red H
|
|||
vars:
|
||||
keycloak_admin_password: "changeme"
|
||||
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
|
||||
---
|
||||
|
|
@ -190,7 +201,8 @@ The following is an example playbook that makes use of the role to install Red H
|
|||
vars:
|
||||
keycloak_admin_password: "changeme"
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue