# keycloak_realm — Keycloak Ansible Collection documentation

# keycloak_realm

Create realms and clients in keycloak or Red Hat Single Sign-On services.

## Role Defaults

Variable | Description | Default
--- | --- | ---
`keycloak_realm_admin_user` | Administration console user account | `admin`
`keycloak_realm_host` | hostname | `localhost`
`keycloak_realm_context` | Context path for rest calls (set to `/auth` for legacy WildFly-based Keycloak) | ``
`keycloak_realm_http_port` | HTTP port | `8080`
`keycloak_realm_https_port` | TLS HTTP port | `8443`
`keycloak_realm_auth_realm` | Name of the main authentication realm | `master`
`keycloak_realm_management_http_port` | Management port | `9990`
`keycloak_realm_auth_client` | Authentication client for configuration REST calls | `admin-cli`
`keycloak_realm_client_public` | Configure a public realm client | `True`
`keycloak_realm_client_web_origins` | Web origins for realm client | `/*`
`keycloak_realm_url` | URL for configuration rest calls | `http://{{ keycloak_realm_host }}:{{ keycloak_realm_http_port }}`
`keycloak_realm_management_url` | URL for management console rest calls | `http://{{ keycloak_realm_host }}:{{ keycloak_realm_management_http_port }}`

## Role Variables

The following are a set of required variables for the role:

Variable | Description
--- | ---
`keycloak_realm_realm` | Name of the realm to be created
`keycloak_realm_admin_password` | Password for the administration console user account

The following variables are available for creating clients:

Variable | Description | Default
--- | --- | ---
`keycloak_realm_clients` | List of client declarations for the realm | `[]`
`keycloak_realm_client_default_roles` | List of default role name for clients | `[]`
`keycloak_realm_client_users` | List of user/role mappings for a client | `[]`

The following variables are available for creating user federation:

Variable | Description | Default
--- | --- | ---
`keycloak_realm_user_federation` | List of keycloak_user_federation for the realm | `[]`

## Variable formats

- `keycloak_realm_user_federation`, a list of:

        - realm:  <name of the realm in which user federation should be configured, required>
          name: <name of the user federation provider, required>
          provider_id: <type of the user federation provider, required>
          provider_type: <Provider Type, default is set to org.keycloak.storage.UserStorageProvider>
          config: <dictionary of supported configuration values, required>
          mappers: <list of supported configuration values, required>

Refer to docs for information on supported variables.

- `keycloak_realm_clients`, a list of:

        - name: <name of the client>
          id: <id of the client>
          client_id: <id of the client>
          secret: <secret of the client (Optional)>
          roles: <keycloak_realm_client_default_roles>
          realm: <name of the realm that contains the client>
          public_client: <true for public, false for confidential>
          web_origins: <list of allowed we origins for the client>
          users: <keycloak_realm_client_users>

`name` and either `id` or `client_id` are required.

- `keycloak_realm_client_users`, a list of:

        - username: <username, required>
          password: <password, required>
          firstName: <firstName, optional>
          lastName: <lastName, optional>
          email: <email, optional>
          client_roles: <list of client user/role mappings>

- Client user/role mappings, a list of:

        - client: <name of the client>
          role: <name of the role>
          realm: <name of the realm>

For a comprehensive example, refer to the playbook.

## Related Modules

For features not covered by this role, the collection provides dedicated modules:

Module | What It Manages
--- | ---
`keycloak_client_scope` | Client scopes and protocol mappers — see example playbook
`keycloak_authentication_flow` | Authentication flows and execution steps — see example playbook
`keycloak_client` | Clients (also used internally by this role)
`keycloak_role` | Realm and client roles
`keycloak_realm_user_federation` | User federations such as LDAP (also used internally by this role)

## Example Playbook

The following is an example playbook that makes use of the role to create a realm in keycloak.

    ---
    - hosts: ...
          collections:
            - middleware_automation.keycloak
          tasks:
            - name: Include keycloak role
              include_role:
                name: keycloak_realm
              vars:
                keycloak_admin_password: "changeme"
                keycloak_realm: TestRealm
                keycloak_clients: [...]

The following example uses the `keycloak_client_scope` module to create a client scope with protocol mappers:

    - name: Create client scope
      middleware_automation.keycloak.keycloak_client_scope:
        auth_keycloak_url: http://localhost:8080
        auth_realm: master
        auth_username: admin
        auth_password: changeme
        realm: TestRealm
        name: my-scope
        protocol_mappers:
          - name: email
            protocolMapper: oidc-usermodel-attribute-mapper
            config:
              user.attribute: email
              claim.name: email
              id.token.claim: "true"
              access.token.claim: "true"
        state: present

The following example uses the `keycloak_authentication_flow` module to create a custom authentication flow:

    - name: Create authentication flow
      middleware_automation.keycloak.keycloak_authentication_flow:
        auth_keycloak_url: http://localhost:8080
        auth_realm: master
        auth_username: admin
        auth_password: changeme
        realm: TestRealm
        alias: my-browser-flow
        executions:
          - provider_id: auth-cookie
            requirement: ALTERNATIVE
          - provider_id: auth-password
            requirement: REQUIRED
        state: present

## License

Apache License 2.0

## Author Information

- Guido Grazioli

- Romain Pelisse