W3cubDocs

/Ansible

community.general.keycloak_identity_provider – Allows administration of Keycloak identity providers via Keycloak API

Note

This plugin is part of the community.general collection (version 3.8.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.keycloak_identity_provider.

New in version 3.6.0: of community.general

Synopsis

  • 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 https://www.keycloak.org/docs-api/15.0/rest-api/index.html.

Parameters

Parameter Choices/Defaults Comments
add_read_token_role_on_create
boolean
    Choices:
  • no
  • yes
Enable/disable whether new users can read any stored tokens. This assigns the broker.read-token role.

aliases: addReadTokenRoleOnCreate
alias
string / required
The alias uniquely identifies an identity provider and it is also used to build the redirect URI.
auth_client_id
string
Default:
"admin-cli"
OpenID Connect client_id to authenticate to the API with.
auth_client_secret
string
Client Secret to use in conjunction with auth_client_id (if required).
auth_keycloak_url
string / required
URL to the Keycloak instance.

aliases: url
auth_password
string
Password to authenticate for API access with.

aliases: password
auth_realm
string
Keycloak realm name to authenticate to for API access.
auth_username
string
Username to authenticate for API access with.

aliases: username
authenticate_by_default
boolean
    Choices:
  • no
  • yes
Specifies if this identity provider should be used by default for authentication even before displaying login screen.

aliases: authenticateByDefault
config
dictionary
Dict specifying the configuration options for the provider; the contents differ depending on the value of providerId. Examples are given below for oidc and saml. It is easiest to obtain valid config values by dumping an already-existing identity provider configuration through check-mode in the existing field.
authorizationUrl
string
The Authorization URL.
backchannelSupported
string
Does the external IDP support backchannel logout?
clientAuthMethod
string
The client authentication method.
clientId
string
The client or client identifier registered within the identity provider.
clientSecret
string
The client or client secret registered within the identity provider.
defaultScope
string
The scopes to be sent when asking for authorization.
entityId
string
The Entity ID that will be used to uniquely identify this SAML Service Provider.
gui_order
integer
Number defining order of the provider in GUI (for example, on Login page).

aliases: guiOrder
hide_on_login_page
boolean
    Choices:
  • no
  • yes
If hidden, login with this provider is possible only if requested explicitly, for example using the kc_idp_hint parameter.

aliases: hideOnLoginPage
issuer
string
The issuer identifier for the issuer of the response. If not provided, no validation will be performed.
jwksUrl
string
URL where identity provider keys in JWK format are stored. See JWK specification for more details.
logoutUrl
string
End session endpoint to use to logout user from external IDP.
nameIDPolicyFormat
string
Specifies the URI reference corresponding to a name identifier format.
principalType
string
Way to identify and track external users from the assertion.
singleLogoutServiceUrl
string
The URL that must be used to send logout requests.
singleSignOnServiceUrl
string
The URL that must be used to send authentication requests (SAML AuthnRequest).
sync_mode
string
Default sync mode for all mappers. The sync mode determines when user data will be synced using the mappers.

aliases: syncMode
tokenUrl
string
The Token URL.
useJwksUrl
boolean
    Choices:
  • no
  • yes
If the switch is on, identity provider public keys will be downloaded from given JWKS URL.
userInfoUrl
string
The User Info URL.
validateSignature
boolean
    Choices:
  • no
  • yes
Enable/disable signature validation of external IDP signatures.
display_name
string
Friendly name for identity provider.

aliases: displayName
enabled
boolean
    Choices:
  • no
  • yes
Enable/disable this identity provider.
first_broker_login_flow_alias
string
Alias of authentication flow, which is triggered after first login with this identity provider.

aliases: firstBrokerLoginFlowAlias
link_only
boolean
    Choices:
  • no
  • yes
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.

aliases: linkOnly
mappers
list / elements=dictionary
A list of dicts defining mappers associated with this Identity Provider.
config
dictionary
Dict specifying the configuration options for the mapper; the contents differ depending on the value of identityProviderMapper.
id
string
Unique ID of this mapper.
identityProviderAlias
string
Alias of the identity provider for this mapper.
identityProviderMapper
string
Type of mapper.
name
string
Name of the mapper.
post_broker_login_flow_alias
string
Alias of authentication flow, which is triggered after each login with this identity provider.

aliases: postBrokerLoginFlowAlias
provider_id
string
Protocol used by this provider (supported values are oidc or saml).

aliases: providerId
realm
string
Default:
"master"
The Keycloak realm under which this identity provider resides.
state
string
    Choices:
  • present ←
  • absent
State of the identity provider.
On present, the identity provider will be created if it does not yet exist, or updated with the parameters you provide.
On absent, the identity provider will be removed if it exists.
store_token
boolean
    Choices:
  • no
  • yes
Enable/disable whether tokens must be stored after authenticating users.

aliases: storeToken
token
string
added in 3.0.0 of community.general
Authentication token for Keycloak API.
trust_email
boolean
    Choices:
  • no
  • yes
If enabled, email provided by this provider is not verified even if verification is enabled for the realm.

aliases: trustEmail
validate_certs
boolean
    Choices:
  • no
  • yes ←
Verify TLS certificates (do not disable this in production).

Examples

- 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

- 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

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
end_state
dictionary
always
Representation of identity provider after module execution

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}
existing
dictionary
always
Representation of existing identity provider

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}
msg
string
always
Message as to what action was taken

Sample:
Identity provider my-idp has been created
proposed
dictionary
always
Representation of proposed changes to identity provider

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'}


Authors

  • Laurent Paumier (@laurpaum)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/keycloak_identity_provider_module.html