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.3).
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 |
Comments |
---|---|
Enable/disable whether new users can read any stored tokens. This assigns the Choices:
|
|
The alias uniquely identifies an identity provider and it is also used to build the redirect URI. |
|
OpenID Connect client_id to authenticate to the API with. Default: “admin-cli” |
|
Client Secret to use in conjunction with auth_client_id (if required). |
|
URL to the Keycloak instance. |
|
Password to authenticate for API access with. |
|
Keycloak realm name to authenticate to for API access. |
|
Username to authenticate for API access with. |
|
Specifies if this identity provider should be used by default for authentication even before displaying login screen. Choices:
|
|
Dict specifying the configuration options for the provider; the contents differ depending on the value of providerId. Examples are given below for |
|
The Authorization URL. |
|
Does the external IDP support backchannel logout? |
|
The client authentication method. |
|
The client or client identifier registered within the identity provider. |
|
The client or client secret registered within the identity provider. |
|
The scopes to be sent when asking for authorization. |
|
The Entity ID that will be used to uniquely identify this SAML Service Provider. |
|
Number defining order of the provider in GUI (for example, on Login page). |
|
If hidden, login with this provider is possible only if requested explicitly, for example using the Choices:
|
|
The issuer identifier for the issuer of the response. If not provided, no validation will be performed. |
|
URL where identity provider keys in JWK format are stored. See JWK specification for more details. |
|
End session endpoint to use to logout user from external IDP. |
|
Specifies the URI reference corresponding to a name identifier format. |
|
Way to identify and track external users from the assertion. |
|
The URL that must be used to send logout requests. |
|
The URL that must be used to send authentication requests (SAML AuthnRequest). |
|
Default sync mode for all mappers. The sync mode determines when user data will be synced using the mappers. |
|
The Token URL. |
|
If the switch is on, identity provider public keys will be downloaded from given JWKS URL. Choices:
|
|
The User Info URL. |
|
Enable/disable signature validation of external IDP signatures. Choices:
|
|
Friendly name for identity provider. |
|
Enable/disable this identity provider. Choices:
|
|
Alias of authentication flow, which is triggered after first login with this identity provider. |
|
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. Choices:
|
|
A list of dicts defining mappers associated with this Identity Provider. |
|
Dict specifying the configuration options for the mapper; the contents differ depending on the value of identityProviderMapper. |
|
Unique ID of this mapper. |
|
Alias of the identity provider for this mapper. |
|
Type of mapper. |
|
Name of the mapper. |
|
Alias of authentication flow, which is triggered after each login with this identity provider. |
|
Protocol used by this provider (supported values are |
|
The Keycloak realm under which this identity provider resides. Default: “master” |
|
State of the identity provider. On On Choices:
|
|
Enable/disable whether tokens must be stored after authenticating users. Choices:
|
|
Authentication token for Keycloak API. |
|
If enabled, email provided by this provider is not verified even if verification is enabled for the realm. Choices:
|
|
Verify TLS certificates (do not disable this in production). Choices:
|
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 |
Description |
---|---|
Representation of identity provider after module execution Returned: always 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} |
|
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} |
|
Message as to what action was taken Returned: always Sample: “Identity provider my-idp has been created” |
|
Representation of proposed changes to 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”} |
Authors
Laurent Paumier (@laurpaum)