Steampunk Ansible Documentation - community.general.keycloak_identity_provider (8.5.0) - module - Allows administration of Keycloak identity providers via Keycloak API

Install collection

Install with ansible-galaxy collection install community.general:==8.5.0

Add to requirements.yml

  collections:
    - name: community.general
      version: 8.5.0

Description

This module allows you to add, remove or modify Keycloak identity providers via the Keycloak REST API. It requires access to the REST API via OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles.

The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/15.0/rest-api/index.html).

Usage examples

Scanned by Steampunk Spotter

- name: Create OIDC identity provider, authentication with credentials
  community.general.keycloak_identity_provider:
    state: present
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: admin
    auth_password: admin
    realm: myrealm
    alias: oidc-idp
    display_name: OpenID Connect IdP
    enabled: true
    provider_id: oidc
    config:
      issuer: https://idp.example.com
      authorizationUrl: https://idp.example.com/auth
      tokenUrl: https://idp.example.com/token
      userInfoUrl: https://idp.example.com/userinfo
      clientAuthMethod: client_secret_post
      clientId: my-client
      clientSecret: secret
      syncMode: FORCE
    mappers:
      - name: first_name
        identityProviderMapper: oidc-user-attribute-idp-mapper
        config:
          claim: first_name
          user.attribute: first_name
          syncMode: INHERIT
      - name: last_name
        identityProviderMapper: oidc-user-attribute-idp-mapper
        config:
          claim: last_name
          user.attribute: last_name
          syncMode: INHERIT

Scanned by Steampunk Spotter

- name: Create SAML identity provider, authentication with credentials
  community.general.keycloak_identity_provider:
    state: present
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: admin
    auth_password: admin
    realm: myrealm
    alias: saml-idp
    display_name: SAML IdP
    enabled: true
    provider_id: saml
    config:
      entityId: https://auth.example.com/auth/realms/myrealm
      singleSignOnServiceUrl: https://idp.example.com/login
      wantAuthnRequestsSigned: true
      wantAssertionsSigned: true
    mappers:
      - name: roles
        identityProviderMapper: saml-user-attribute-idp-mapper
        config:
          user.attribute: roles
          attribute.friendly.name: User Roles
          attribute.name: roles
          syncMode: INHERIT

Inputs

alias:
description:
- The alias uniquely identifies an identity provider and it is also used to build
the redirect URI.
required: true
type: str

realm:
default: master
description:
- The Keycloak realm under which this identity provider resides.
type: str

state:
choices:
- present
- absent
default: present
description:
- State of the identity provider.
- On V(present), the identity provider will be created if it does not yet exist, or
updated with the parameters you provide.
- On V(absent), the identity provider will be removed if it exists.
type: str

token:
description:
- Authentication token for Keycloak API.
type: str
version_added: 3.0.0
version_added_collection: community.general

config:
description:
- Dict specifying the configuration options for the provider; the contents differ
depending on the value of O(provider_id). Examples are given below for V(oidc) and
V(saml). It is easiest to obtain valid config values by dumping an already-existing
identity provider configuration through check-mode in the RV(existing) field.
suboptions:
authorizationUrl:
description:
- The Authorization URL.
type: str
backchannelSupported:
description:
- Does the external IDP support backchannel logout?
type: str
clientAuthMethod:
description:
- The client authentication method.
type: str
clientId:
description:
- The client or client identifier registered within the identity provider.
type: str
clientSecret:
description:
- The client or client secret registered within the identity provider.
type: str
defaultScope:
description:
- The scopes to be sent when asking for authorization.
type: str
entityId:
description:
- The Entity ID that will be used to uniquely identify this SAML Service Provider.
type: str
gui_order:
aliases:
- guiOrder
description:
- Number defining order of the provider in GUI (for example, on Login page).
type: int
hide_on_login_page:
aliases:
- hideOnLoginPage
description:
- If hidden, login with this provider is possible only if requested explicitly,
for example using the C(kc_idp_hint) parameter.
type: bool
issuer:
description:
- The issuer identifier for the issuer of the response. If not provided, no validation
will be performed.
type: str
jwksUrl:
description:
- URL where identity provider keys in JWK format are stored. See JWK specification
for more details.
type: str
logoutUrl:
description:
- End session endpoint to use to logout user from external IDP.
type: str
nameIDPolicyFormat:
description:
- Specifies the URI reference corresponding to a name identifier format.
type: str
principalType:
description:
- Way to identify and track external users from the assertion.
type: str
singleLogoutServiceUrl:
description:
- The URL that must be used to send logout requests.
type: str
singleSignOnServiceUrl:
description:
- The URL that must be used to send authentication requests (SAML AuthnRequest).
type: str
sync_mode:
aliases:
- syncMode
description:
- Default sync mode for all mappers. The sync mode determines when user data will
be synced using the mappers.
type: str
tokenUrl:
description:
- The Token URL.
type: str
useJwksUrl:
description:
- If the switch is on, identity provider public keys will be downloaded from given
JWKS URL.
type: bool
userInfoUrl:
description:
- The User Info URL.
type: str
validateSignature:
description:
- Enable/disable signature validation of external IDP signatures.
type: bool
type: dict

enabled:
description:
- Enable/disable this identity provider.
type: bool

mappers:
description:
- A list of dicts defining mappers associated with this Identity Provider.
elements: dict
suboptions:
config:
description:
- Dict specifying the configuration options for the mapper; the contents differ
depending on the value of O(mappers[].identityProviderMapper).
type: dict
id:
description:
- Unique ID of this mapper.
type: str
identityProviderAlias:
description:
- Alias of the identity provider for this mapper.
type: str
identityProviderMapper:
description:
- Type of mapper.
type: str
name:
description:
- Name of the mapper.
type: str
type: list

link_only:
aliases:
- linkOnly
description:
- If true, users cannot log in through this provider. They can only link to this provider.
This is useful if you don't want to allow login from the provider, but want to integrate
with a provider.
type: bool

auth_realm:
description:
- Keycloak realm name to authenticate to for API access.
type: str

http_agent:
default: Ansible
description:
- Configures the HTTP User-Agent header.
type: str
version_added: 5.4.0
version_added_collection: community.general

provider_id:
aliases:
- providerId
description:
- Protocol used by this provider (supported values are V(oidc) or V(saml)).
type: str

store_token:
aliases:
- storeToken
description:
- Enable/disable whether tokens must be stored after authenticating users.
type: bool

trust_email:
aliases:
- trustEmail
description:
- If enabled, email provided by this provider is not verified even if verification
is enabled for the realm.
type: bool

display_name:
aliases:
- displayName
description:
- Friendly name for identity provider.
type: str

auth_password:
aliases:
- password
description:
- Password to authenticate for API access with.
type: str

auth_username:
aliases:
- username
description:
- Username to authenticate for API access with.
type: str

auth_client_id:
default: admin-cli
description:
- OpenID Connect C(client_id) to authenticate to the API with.
type: str

validate_certs:
default: true
description:
- Verify TLS certificates (do not disable this in production).
type: bool

auth_keycloak_url:
aliases:
- url
description:
- URL to the Keycloak instance.
required: true
type: str

auth_client_secret:
description:
- Client Secret to use in conjunction with O(auth_client_id) (if required).
type: str

connection_timeout:
default: 10
description:
- Controls the HTTP connections timeout period (in seconds) to Keycloak API.
type: int
version_added: 4.5.0
version_added_collection: community.general

authenticate_by_default:
aliases:
- authenticateByDefault
description:
- Specifies if this identity provider should be used by default for authentication
even before displaying login screen.
type: bool

post_broker_login_flow_alias:
aliases:
- postBrokerLoginFlowAlias
description:
- Alias of authentication flow, which is triggered after each login with this identity
provider.
type: str

add_read_token_role_on_create:
aliases:
- addReadTokenRoleOnCreate
description:
- Enable/disable whether new users can read any stored tokens. This assigns the C(broker.read-token)
role.
type: bool

first_broker_login_flow_alias:
aliases:
- firstBrokerLoginFlowAlias
description:
- Alias of authentication flow, which is triggered after first login with this identity
provider.
type: str

Outputs

end_state:
  description: Representation of identity provider after module execution.
  returned: on success
  sample:
    addReadTokenRoleOnCreate: false
    alias: my-idp
    authenticateByDefault: false
    config:
      authorizationUrl: https://idp.example.com/auth
      clientAuthMethod: client_secret_post
      clientId: my-client
      clientSecret: '**********'
      issuer: https://idp.example.com
      tokenUrl: https://idp.example.com/token
      userInfoUrl: https://idp.example.com/userinfo
    displayName: OpenID Connect IdP
    enabled: true
    firstBrokerLoginFlowAlias: first broker login
    internalId: 4d28d7e3-1b80-45bb-8a30-5822bf55aa1c
    linkOnly: false
    providerId: oidc
    storeToken: false
    trustEmail: false
  type: dict
existing:
  description: Representation of existing identity provider.
  returned: always
  sample:
    addReadTokenRoleOnCreate: false
    alias: my-idp
    authenticateByDefault: false
    config:
      authorizationUrl: https://old.example.com/auth
      clientAuthMethod: client_secret_post
      clientId: my-client
      clientSecret: '**********'
      issuer: https://old.example.com
      syncMode: FORCE
      tokenUrl: https://old.example.com/token
      userInfoUrl: https://old.example.com/userinfo
    displayName: OpenID Connect IdP
    enabled: true
    firstBrokerLoginFlowAlias: first broker login
    internalId: 4d28d7e3-1b80-45bb-8a30-5822bf55aa1c
    linkOnly: false
    providerId: oidc
    storeToken: false
    trustEmail: false
  type: dict
msg:
  description: Message as to what action was taken.
  returned: always
  sample: Identity provider my-idp has been created
  type: str
proposed:
  description: Representation of proposed identity provider.
  returned: always
  sample:
    config:
      authorizationUrl: https://idp.example.com/auth
      clientAuthMethod: client_secret_post
      clientId: my-client
      clientSecret: secret
      issuer: https://idp.example.com
      tokenUrl: https://idp.example.com/token
      userInfoUrl: https://idp.example.com/userinfo
    displayName: OpenID Connect IdP
    providerId: oidc
  type: dict