Correcting capitalization
This commit is contained in:
Andy Munro
Marek Posolda
parent
2e8827cf1a
commit
26087f0ece
18 changed files with 326 additions and 104 deletions
23
securing_apps/topics/overview/basic-steps.adoc
Normal file
23
securing_apps/topics/overview/basic-steps.adoc
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
=== Basic steps to secure applications and services
|
||||
|
||||
These are the basic steps for setting up an application or a service in Keycloak.
|
||||
|
||||
Configure a client adapter using one of these options:
|
||||
|
||||
* A {project_name} adapter
|
||||
|
||||
* A third party library adapter
|
||||
|
||||
Register a client using one of these options:
|
||||
|
||||
* The Admin Console
|
||||
|
||||
* The client registration service
|
||||
|
||||
* The CLI
|
||||
|
||||
[role="_additional-resources"]
|
||||
.Additional resources
|
||||
|
||||
This guide provide the detailed instructions for these steps. Additional information on using the Admin Console exists in the Server Administration Guide. That guide refers to creating a client rather than registering a client.
|
||||
|
||||
21
securing_apps/topics/overview/basic-steps.adoc~
Normal file
21
securing_apps/topics/overview/basic-steps.adoc~
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
These are the basic steps for setting up an application or a service in Keycloak.
|
||||
|
||||
Configure a client adapter using one of these options:
|
||||
|
||||
* A {project_name} adapter
|
||||
|
||||
* A third party library adapter
|
||||
|
||||
Register a client using one of these options:
|
||||
|
||||
* The Admin Console
|
||||
|
||||
* The client registration service
|
||||
|
||||
* The CLI
|
||||
|
||||
[role="_additional-resources"]
|
||||
== Additional resources
|
||||
|
||||
This guide provide the detailed instructions for these steps. Additional information on using the Admin Console exists in the Server Administration Guide. That guide refers to creating a client rather than registering a client.
|
||||
|
||||
13
securing_apps/topics/overview/terminology.adoc
Normal file
13
securing_apps/topics/overview/terminology.adoc
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
=== Terminology
|
||||
|
||||
These terms are used in this guide:
|
||||
|
||||
* `Clients` are entities that can request Keycloak to authenticate a user. Most often, clients are applications and services that want to use Keycloak to secure themselves and provide a single sign-on solution. Clients can also be entities that just want to request identity information or an access token so that they can securely invoke other services on the network that are secured by Keycloak.
|
||||
|
||||
* `Applications` include a wide range of applications that work for specific platforms for each protocol
|
||||
|
||||
* A `service account` is built-in account that exists for each client. The client uses this account to obtain an access token.
|
||||
|
||||
* `Client adapters` are libraries that make it very easy to secure applications and services with Keycloak. We call them adapters rather than libraries as they provide a tight integration to the underlying platform and framework. This makes our adapters easy to use and they require less boilerplate code than what is typically required by a library.
|
||||
|
||||
* `Creating a client` and `registering a client` are the same action. The Admin Console includes a Create Client option which performs the same action that is performed by using the Client Registration Services.
|
||||
BIN
server_admin/images/master_realm.png
Normal file
BIN
server_admin/images/master_realm.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
|
|
@ -54,11 +54,11 @@ include::topics/identity-broker/session-data.adoc[]
|
|||
include::topics/identity-broker/first-login-flow.adoc[]
|
||||
include::topics/identity-broker/tokens.adoc[]
|
||||
include::topics/identity-broker/logout.adoc[]
|
||||
include::topics/sso-protocols.adoc[]
|
||||
include::topics/admin-console-permissions.adoc[]
|
||||
include::topics/admin-console-permissions/master-realm.adoc[]
|
||||
include::topics/admin-console-permissions/per-realm.adoc[]
|
||||
include::topics/admin-console-permissions/fine-grain.adoc[]
|
||||
include::topics/sso-protocols.adoc[]
|
||||
include::topics/assembly-managing-clients.adoc[]
|
||||
include::topics/vault.adoc[]
|
||||
include::topics/events.adoc[]
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ If the <<_access-type, access type>> of the client is set to *confidential*, the
|
|||
.Credentials Tab
|
||||
image:{project_images}/client-credentials.png[Credentials Tab]
|
||||
|
||||
The *Client Authenticator* drop-down list specifies the type of credential to use for your client.
|
||||
The *Client Authenticator* drop-down list specifies the type of credential to use for your client.
|
||||
|
||||
*Client ID and Secret*
|
||||
|
||||
|
|
@ -19,12 +19,8 @@ image:{project_images}/client-credentials-jwt.png[]
|
|||
|
||||
*Signed JWT* is "Signed Json Web Token".
|
||||
|
||||
When choosing this credential type you will have to also generate a private key and certificate for the client in the tab `Keys`. The private key will be used to sign the JWT, while the certificate is used by the server to verify the signature.
|
||||
|
||||
.Keys Tab
|
||||
image:{project_images}/client-oidc-keys.png[]
|
||||
|
||||
Click on the `Generate new keys and certificate` button to start this process.
|
||||
When choosing this credential type you will have to also generate a private key and certificate for the client in the *Keys* tab. The private key will be used to sign the JWT, while the certificate is used by the server to verify the signature.
|
||||
Click *Generate new keys and certificate* to start this process.
|
||||
|
||||
.Generate Keys
|
||||
image:{project_images}/generate-client-keys.png[]
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Conditions in Conditional flows
|
||||
|
||||
As was mentioned in <<_execution-requirements, Execution requirements>>, _Condition_ executions can be only contained in _Conditional_ subflow.
|
||||
|
|
|
|||
|
|
@ -39,18 +39,20 @@ This action is configured through the *Actions* > *Config* link. It redirects to
|
|||
+
|
||||
Since this sub-flow is marked as _alternative_, it will not be executed if the *Cookie* authentication type passed. This sub-flow contains an additional authentication type that needs to be executed. {project_name} loads the executions for this sub-flow and processes them.
|
||||
|
||||
The first execution is the *Username Password Form*, an authentication type that renders the username and password page. It is marked as _required_, so the user must enter a valid username and password.
|
||||
.. The first execution is the *Username Password Form*, an authentication type that renders the username and password page. It is marked as _required_, so the user must enter a valid username and password.
|
||||
|
||||
The second execution is the *Browser - Conditional OTP* sub-flow. This sub-flow is _conditional_ and executes depending on the result of the *Condition - User Configured* execution. If the result is true, {project_name} loads the executions for this sub-flow and processes them.
|
||||
.. The second execution is the *Browser - Conditional OTP* sub-flow. This sub-flow is _conditional_ and executes depending on the result of the *Condition - User Configured* execution. If the result is true, {project_name} loads the executions for this sub-flow and processes them.
|
||||
|
||||
The next execution is the *Condition - User Configured* authentication. This authentication checks if {project_name} has configured other executions in the flow for the user. The *Browser - Conditional OTP* sub-flow executes only when the user has a configured OTP credential.
|
||||
.. The next execution is the *Condition - User Configured* authentication. This authentication checks if {project_name} has configured other executions in the flow for the user. The *Browser - Conditional OTP* sub-flow executes only when the user has a configured OTP credential.
|
||||
|
||||
The final execution is the *OTP Form*. {project_name} marks this execution as _required_ but it runs only when the user has an OTP credential set up because of the setup in the _conditional_ sub-flow. If not, the user does not see an OTP form.
|
||||
.. The final execution is the *OTP Form*. {project_name} marks this execution as _required_ but it runs only when the user has an OTP credential set up because of the setup in the _conditional_ sub-flow. If not, the user does not see an OTP form.
|
||||
|
||||
[[_execution-requirements]]
|
||||
==== Execution requirements
|
||||
|
||||
===== Requirement
|
||||
A set of radio buttons that control the execution of an action executes.
|
||||
|
||||
[[_execution-requirements]]
|
||||
====== Required
|
||||
|
||||
All _Required_ elements in the flow must be successfully sequentially executed. The flow terminates if a required element fails.
|
||||
|
|
@ -160,7 +162,7 @@ To illustrate the creation of flows, this section describes creating an advanced
|
|||
.The common part with the browser flow
|
||||
image:images/Passwordless-browser-login-common.png[]
|
||||
+
|
||||
. Click *Actions for the *Forms* execution.
|
||||
. Click *Actions* for the *Forms* execution.
|
||||
. Select *Add execution*.
|
||||
. Select *Username Form* from the drop-down list.
|
||||
. Click *Save*.
|
||||
|
|
|
|||
|
|
@ -136,7 +136,7 @@ The password to open the truststore.
|
|||
|
||||
See link:https://docs.wildfly.org/19/Admin_Guide.html#https-listener[HTTPS Listener] for the instructions to enable HTTPS in WildFly.
|
||||
|
||||
* Add the <https-listener> element.
|
||||
Add the <https-listener> element as shown below:
|
||||
|
||||
[source,xml,subs="attributes+"]
|
||||
----
|
||||
|
|
@ -196,41 +196,44 @@ image:images/x509-configuration.png[X509 Configuration]
|
|||
*User Identity Source*::
|
||||
Defines the method for extracting the user identity from a client certificate.
|
||||
|
||||
*Canonical DN representation enabled*::
|
||||
*Canonical DN representation enabled (optional)*::
|
||||
Defines whether to use canonical format to determine a distinguished name. The official link:https://docs.oracle.com/javase/8/docs/api/javax/security/auth/x500/X500Principal.html#getName-java.lang.String-[Java API documentation] describes the format. This option affects the two User Identity Sources _Match SubjectDN using regular expression_ and _Match IssuerDN using regular expression_ only. Enable this option when you set up a new {project_name} instance. Disable this option to retain backward compatibility with existing {project_name} instances.
|
||||
|
||||
*Enable Serial Number hexadecimal representation*::
|
||||
*Enable Serial Number hexadecimal representation (optional)*::
|
||||
Represent the link:https://tools.ietf.org/html/rfc5280#section-4.1.2.2[serial number] as hexadecimal. The serial number with the sign bit set to 1 must be left padded with 00 octet. For example, a serial number with decimal value _161_, or _a1_ in hexadecimal representation is encoded as _00a1_, according to RFC5280. See link:https://tools.ietf.org/html/rfc5280#appendix-B[RFC5280, appendix-B] for more details.
|
||||
|
||||
*A regular expression*::
|
||||
*A regular expression (optional)*::
|
||||
A regular expression to use as a filter for extracting the certificate identity. The expression must contain a single group.
|
||||
|
||||
*User Mapping Method*::
|
||||
Defines the method to match the certificate identity with an existing user. _Username or email_ searches for existing users by username or email. _Custom Attribute Mapper_ searches for existing users with a custom attribute that matches the certificate identity. The name of the custom attribute is configurable.
|
||||
|
||||
*A name of user attribute*::
|
||||
*A name of user attribute (optional)*::
|
||||
A custom attribute whose value matches against the certificate identity. Use multiple custom attributes when attribute mapping is related to multiple values, For example, 'Certificate Serial Number and IssuerDN'.
|
||||
|
||||
*CRL Checking Enabled*::
|
||||
WARNING: It is highly recommended that attribute used here is read-only for the users. By default, only the `usercertificate` attribute is read-only by {project_name}.
|
||||
If you use a different attribute name, you may need to add it to the list of read-only attributes. See the details in the link:#_read_only_user_attributes[Threat model mitigation chapter].
|
||||
|
||||
*CRL Checking Enabled (optional)*::
|
||||
Check the revocation status of the certificate by using the Certificate Revocation List. The location of the list is defined in the *CRL file path* attribute.
|
||||
|
||||
*Enable CRL Distribution Point to check certificate revocation status*::
|
||||
*Enable CRL Distribution Point to check certificate revocation status (optional)*::
|
||||
Use CDP to check the certificate revocation status. Most PKI authorities include CDP in their certificates.
|
||||
|
||||
*CRL file path*::
|
||||
*CRL file path (optional)*::
|
||||
The path to a file containing a CRL list. The value must be a path to a valid file if the *CRL Checking Enabled* option is enabled.
|
||||
|
||||
*OCSP Checking Enabled*::
|
||||
*OCSP Checking Enabled (optional)*::
|
||||
Checks the certificate revocation status by using Online Certificate Status Protocol.
|
||||
|
||||
*OCSP Responder URI*::
|
||||
*OCSP Responder URI (optional)*::
|
||||
Override the value of the OCSP responder URI in the certificate.
|
||||
|
||||
*Validate Key Usage*::
|
||||
*Validate Key Usage (optional)*::
|
||||
Verifies the certificate's KeyUsage extension bits are set. For example, "digitalSignature,KeyEncipherment" verifies if bits 0 and 2 in the KeyUsage extension are set.
|
||||
Leave this parameter empty to disable the Key Usage validation. See link:https://tools.ietf.org/html/rfc5280#section-4.2.1.3[RFC5280, Section-4.2.1.3] for more information. {project_name} raises an error when a key usage mismatch occurs.
|
||||
|
||||
*Validate Extended Key Usage*::
|
||||
*Validate Extended Key Usage (optional)*::
|
||||
Verifies one or more purposes defined in the Extended Key Usage extension. See link:https://tools.ietf.org/html/rfc5280#section-4.2.1.12[RFC5280, Section-4.2.1.12] for more information. Leave this parameter empty to disable the Extended Key Usage validation. {project_name} raises an error when flagged as critical by the issuing CA and a key usage extension mismatch occurs.
|
||||
|
||||
*Bypass identity confirmation*::
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
[role="_abstract"]
|
||||
{project_name} includes the ability to export and import its entire database.
|
||||
|
||||
You can migrate the whole {project_name} database from one environment to another or migrate to another database. The export/import triggers at server boot time, and its parameters pass through Java properties.
|
||||
You can migrate the whole {project_name} database from one environment to another or migrate to another database (for example from MySQL to Oracle). The export/import triggers at server boot time, and its parameters pass through Java properties.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
|
|
|
|||
|
|
@ -26,17 +26,12 @@ Review Profile::
|
|||
* When *OFF*, the profile page does not display unless the user clicks in a later phase on the `Review profile info` link in the page displayed by the `Confirm Link Existing Account` authenticator.
|
||||
|
||||
Create User If Unique::
|
||||
This authenticator checks if there is already an existing {project_name} account with the same email or username like the account from the identity provider.
|
||||
If it's not, then the authenticator just creates a new local {project_name} account and links it with the identity provider and the whole flow is finished.
|
||||
Otherwise it goes to the next `Handle Existing Account` subflow.
|
||||
If you always want to ensure that there is no duplicated account, you can mark this authenticator as `REQUIRED`. In this case, the user
|
||||
will see the error page if there is an existing {project_name} account and the user will need to link the identity provider account through Account management.
|
||||
=======
|
||||
* This authenticator verifies that there is already a {project_name} account with the same email or username as the identity provider's account.
|
||||
* If an account does not exist, the authenticator creates a local {project_name} account, links this account with the identity provider, and terminates the flow.
|
||||
* If an account exists, the authenticator implements the next `Handle Existing Account` sub-flow.
|
||||
* To ensure there is no duplicated account, you can mark this authenticator as `REQUIRED`. The user sees the error page if a {project_name} account exists, and users must link their identity provider account through Account management.
|
||||
|
||||
NOTE: If you want to skip the ability to create new users, but you want that users authenticated from identity provider must already exists in {project_name} with same username or email like the user from identity provider, you can create new flow and replace `Create User If Exists` authenticator with `Detect Existing Broker User` . More details in the <<Detect Existing User First Login Flow,examples below>>.
|
||||
|
||||
Confirm Link Existing Account::
|
||||
* On the information page, users see a {project_name} account with the same email. Users can review their profile again and use a different email or username. The flow restarts and goes back to the `Review Profile` authenticator.
|
||||
|
|
@ -107,8 +102,12 @@ Automatically Set Existing User::
|
|||
Automatically sets an existing user to the authentication context without any verification. Set the authenticator requirement to `Mandatory`.
|
||||
|
||||
You have to set the `First Login Flow` of the identity provider configuration to that flow.
|
||||
You could set the also set `Sync Mode` to `force` if you want to update the user profile (Last Name, First Name...) with the identity provider attributes.
|
||||
You could set the also set `Sync Mode` to `force` if you want to update the user profile (Last Name, First Name, and so on) with the identity provider attributes.
|
||||
|
||||
NOTE: This flow can be used if you want to delegate the identity to other identity providers (such as github, facebook ...) but you want to manage which users that can log in.
|
||||
=======
|
||||
NOTE: This flow can be used if you want to delegate the identity to other identity providers (such as github, facebook, and so on) but you want to manage which users that can log in.
|
||||
=======
|
||||
|
||||
With this configuration, {project_name} is unable to determine which internal account corresponds to the external identity. The *Verify Existing Account By Re-authentication* authenticator asks the provider for the username and password.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -32,8 +32,6 @@ image:{project_images}/saml-add-identity-provider.png[Add Identity Provider]
|
|||
|
||||
|Principal Type
|
||||
|Specifies which part of the SAML assertion will be used to identify and track external user identities. Can be either Subject NameID or SAML attribute (either by name or by friendly name). Subject NameID value can not be set together with 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' NameID Policy Format value.
|
||||
=======
|
||||
|Specifies the part of the SAML assertion {project_name} uses to identify and track external user identities. The Principal Type can be Subject NameID or SAML attribute (by name or by friendly name).
|
||||
|
||||
|Principal Attribute
|
||||
|If a Principal type is non-blank, this field specifies the name ("Attribute [Name]") or the friendly name ("Attribute [Friendly Name]") of the identifying attribute.
|
||||
|
|
|
|||
|
|
@ -93,7 +93,7 @@ from the dropdown. You can change the priority to make sure the new keypair beco
|
|||
|
||||
.Procedure
|
||||
. Select the realm in the Admin Console.
|
||||
. Click Realm settings.
|
||||
. Click *Realm settings*.
|
||||
. Click the *Keys* tab.
|
||||
. Click the *Active* tab.
|
||||
. Click the provider of the key you want to make passive.
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ In the Admin Console, two types of realms exist:
|
|||
* `Other realms` - These realms are created by the administrator in the master realm. In these realms, administrators manage the users in your organization and the applications they need. The applications are owned by the users.
|
||||
|
||||
.Realms and applications
|
||||
image:../../../getting_started/images/master_realm.png[Realms and applications]
|
||||
image:images/master_realm.png[Realms and applications]
|
||||
|
||||
Realms are isolated from one another and can only manage and authenticate the users that they control. Following this security model helps prevent accidental changes and follows the tradition
|
||||
of permitting user accounts access to only those privileges and powers necessary
|
||||
|
|
|
|||
|
|
@ -78,4 +78,223 @@ This is used by clients running on internet-connected devices that have limited
|
|||
|
||||
. The application requests {project_name} a device code and a user code. {project_name} creates a device code and a user code. {project_name} returns a response including the device code and the user code to the application.
|
||||
. The application provides the user with the user code and the verification URI. The user accesses a verification URI to be authenticated by using another browser.
|
||||
. The application repeatedly polls {project_name} to find out if the user completed the user authorization. If user authentication is complete, the application exchanges the device code for an _identity_, _access_ and _refresh_ token.
|
||||
. The application repeatedly polls {project_name} to find out if the user completed the user authorization. If user authentication is complete, the application exchanges the device code for an _identity_, _access_ and _refresh_ token.
|
||||
|
||||
[[_client_initiated_backchannel_authentication_grant]]
|
||||
===== Client Initiated Backchannel Authentication Grant
|
||||
|
||||
:tech_feature_name: Client Initiated Backchannel Authentication Grant
|
||||
:tech_feature_setting: -Dkeycloak.profile.feature.ciba=enabled
|
||||
include::../templates/techpreview.adoc[]
|
||||
|
||||
This is used by clients who want to initiate the authentication flow by communicating with the OpenID Provider directly without redirect through the user's browser like OAuth 2.0's authorization code grant. Here's a brief summary of the protocol:
|
||||
|
||||
. The client requests {project_name} an auth_req_id that identifies the authentication request made by the client. {project_name} creates the auth_req_id.
|
||||
. After receiving this auth_req_id, this client repeatedly needs to poll {project_name} to obtain an Access Token, Refresh Token and ID Token from {project_name} in return for the auth_req_id until the user is authenticated.
|
||||
|
||||
An administrator can configure Client Initiated Backchannel Authentication (CIBA) related operations as `CIBA Policy` per realm.
|
||||
|
||||
Also please refer to other places of {project_name} documentation like link:{adapterguide_link}#_backchannel_authentication_endpoint[Backchannel Authentication Endpoint section] of {adapterguide_name} and link:{adapterguide_link}#_client_initiated_backchannel_authentication_grant[Client Initiated Backchannel Authentication Grant section] of {adapterguide_name}.
|
||||
|
||||
====== CIBA Policy
|
||||
|
||||
An administrator carries out the following operations on the `Admin Console` :
|
||||
|
||||
- Open the `Authentication -> CIBA Policy` tab.
|
||||
- Configure items and click `Save`.
|
||||
|
||||
The configurable items and their description follow.
|
||||
|
||||
|===
|
||||
|Configuration|Description
|
||||
|
||||
|Backchannel Token Delivery Mode
|
||||
|Specifying how the CD (Consumption Device) gets the authentication result and related tokens. There are three modes, "poll", "ping" and "push". {project_name} only supports "poll". The default setting is "poll". This configuration is required.
|
||||
For more details, see https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#rfc.section.5[CIBA Specification].
|
||||
|
||||
|Expires In
|
||||
|The expiration time of the "auth_req_id" in seconds since the authentication request was received. The default setting is 120. This configuration is required.
|
||||
For more details, see https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#successful_authentication_request_acknowdlegment[CIBA Specification].
|
||||
|
||||
|Interval
|
||||
|The interval in seconds the CD (Consumption Device) needs to wait for between polling requests to the token endpoint. The default setting is 5. This configuration is optional.
|
||||
For more details, see https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#successful_authentication_request_acknowdlegment[CIBA Specification].
|
||||
|
||||
|Authentication Requested User Hint
|
||||
|The way of identifying the end-user for whom authentication is being requested. The default setting is "login_hint". There are three modes, "login_hint", "login_hint_token" and "id_token_hint". {project_name} only supports "login_hint". This configuration is required.
|
||||
For more details, see https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#rfc.section.7.1[CIBA Specification].
|
||||
|
||||
|===
|
||||
|
||||
====== Provider Setting
|
||||
|
||||
The CIBA grant uses the following two providers.
|
||||
|
||||
. Authentication Channel Provider : provides the communication between {project_name} and the entity that actually authenticates the user via AD (Authentication Device).
|
||||
. User Resolver Provider : get `UserModel` of {project_name} from the information provided by the client to identify the user.
|
||||
|
||||
{project_name} has both default providers. However, the administrator needs to set up Authentication Channel Provider like this:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<spi name="ciba-auth-channel">
|
||||
<default-provider>ciba-http-auth-channel</default-provider>
|
||||
<provider name="ciba-http-auth-channel" enabled="true">
|
||||
<properties>
|
||||
<property name="httpAuthenticationChannelUri" value="https://backend.internal.example.com/auth"/>
|
||||
</properties>
|
||||
</provider>
|
||||
</spi>
|
||||
----
|
||||
|
||||
The configurable items and their description follow.
|
||||
|
||||
|===
|
||||
|Configuration|Description
|
||||
|
||||
|httpAuthenticationChannelUri
|
||||
|Specifying URI of the entity that actually authenticates the user via AD (Authentication Device).
|
||||
|
||||
|===
|
||||
|
||||
====== Authentication Channel Provider
|
||||
|
||||
CIBA standard document does not specify how to authenticate the user by AD. Therefore, it might be implemented at the discretion of products. {project_name} delegates this authentication to an external authentication entity. To communicate with the authentication entity, {project_name} provides Authentication Channel Provider.
|
||||
|
||||
Its implementation of {project_name} assumes that the authentication entity is under the control of the administrator of {project_name} so that {project_name} trusts the authentication entity. It is not recommended to use the authentication entity that the administrator of {project_name} cannot control.
|
||||
|
||||
Authentication Channel Provider is provided as SPI provider so that users of {project_name} can implement their own provider in order to meet their environment. {project_name} provides its default provider called HTTP Authentication Channel Provider that uses HTTP to communicate with the authentication entity.
|
||||
|
||||
If a user of {project_name} user want to use the HTTP Authentication Channel Provider, they need to know its contract between {project_name} and the authentication entity consisting of the following two parts.
|
||||
|
||||
Authentication Delegation Request/Response::
|
||||
{project_name} sends an authentication request to the authentication entity.
|
||||
|
||||
Authentication Result Notification/ACK::
|
||||
The authentication entity notifies the result of the authentication to {project_name}.
|
||||
|
||||
Authentication Delegation Request/Response consists of the following messaging.
|
||||
|
||||
Authentication Delegation Request:: The request is sent from {project_name} to the authentication entity to ask it for user authentication by AD.
|
||||
|
||||
----
|
||||
POST [delegation_reception]
|
||||
----
|
||||
|
||||
* Headers
|
||||
|
||||
|===
|
||||
|Name|Value|Description
|
||||
|
||||
|Content-Type|application/json|The message body is json formatted.
|
||||
|Authorization|Bearer [token]|The [token] is used when the authentication entity notifies the result of the authentication to {project_name}.
|
||||
|
||||
|===
|
||||
|
||||
* Parameters
|
||||
|
||||
|===
|
||||
|Type|Name|Description
|
||||
|
||||
|Path
|
||||
|delegation_reception|The endpoint provided by the authentication entity to receive the delegation request
|
||||
|
||||
|===
|
||||
|
||||
* Body
|
||||
|
||||
|===
|
||||
|Name|Description
|
||||
|
||||
|login_hint|It tells the authentication entity who is authenticated by AD. +
|
||||
By default, it is the user's "username". +
|
||||
This field is required and was defined by CIBA standard document.
|
||||
|
||||
|scope|It tells which scopes the authentication entity gets consent from the authenticated user. +
|
||||
This field is required and was defined by CIBA standard document.
|
||||
|
||||
|is_consent_required|It shows whether the authentication entity needs to get consent from the authenticated user about the scope. +
|
||||
This field is required.
|
||||
|
||||
|binding_message|Its value is intended to be shown in both CD and AD's UI to make the user recognize that the authentication by AD is triggered by CD. +
|
||||
This field is optional and was defined by CIBA standard document.
|
||||
|
||||
|acr_values|It tells the requesting Authentication Context Class Reference from CD. +
|
||||
This field is optional and was defined by CIBA standard document.
|
||||
|
||||
|===
|
||||
|
||||
Authentication Delegation Response:: The response is returned from the authentication entity to {project_name} to notify that the authentication entity received the authentication request from {project_name}.
|
||||
|
||||
* Responses
|
||||
|
||||
|===
|
||||
|HTTP Status Code|Description
|
||||
|
||||
|201|It notifies {project_name} of receiving the authentication delegation request.
|
||||
|
||||
|===
|
||||
|
||||
Authentication Result Notification/ACK consists of the following messaging.
|
||||
|
||||
Authentication Result Notification:: The authentication entity sends the result of the authentication request to {project_name}.
|
||||
|
||||
----
|
||||
POST /auth/realms/[realm]/protocol/openid-connect/ext/ciba/auth/callback
|
||||
----
|
||||
|
||||
* Headers
|
||||
|
||||
|===
|
||||
|Name|Value|Description
|
||||
|
||||
|Content-Type|application/json|The message body is json formatted.
|
||||
|Authorization|Bearer [token]|The [token] must be the one the authentication entity has received from {project_name} in Authentication Delegation Request.
|
||||
|
||||
|===
|
||||
|
||||
* Parameters
|
||||
|
||||
|===
|
||||
|Type|Name|Description
|
||||
|
||||
|Path
|
||||
|realm|The realm name
|
||||
|
||||
|===
|
||||
|
||||
* Body
|
||||
|
||||
|===
|
||||
|Name|Description
|
||||
|
||||
|status|It tells the result of user authentication by AD. +
|
||||
It must be one of the following status. +
|
||||
SUCCEED : The authentication by AD has been successfully completed. +
|
||||
UNAUTHORIZED : The authentication by AD has not been completed. +
|
||||
CANCELLED : The authentication by AD has been cancelled by the user.
|
||||
|
||||
|===
|
||||
|
||||
Authentication Result ACK:: The response is returned from {project_name} to the authentication entity to notify {project_name} received the result of user authentication by AD from the authentication entity.
|
||||
|
||||
* Responses
|
||||
|
||||
|===
|
||||
|HTTP Status Code|Description
|
||||
|
||||
|200|It notifies the authentication entity of receiving the notification of the authentication result.
|
||||
|
||||
|===
|
||||
|
||||
====== User Resolver Provider
|
||||
|
||||
Even if the same user, its representation may differ in each CD, {project_name} and the authentication entity.
|
||||
|
||||
For CD, {project_name} and the authentication entity to recognize the same user, this User Resolver Provider converts their own user representations among them.
|
||||
|
||||
User Resolver Provider is provided as SPI provider so that users of {project_name} can implement their own provider in order to meet their environment. {project_name} provides its default provider called Default User Resolver Provider that has the following characteristics.
|
||||
|
||||
* Only support `login_hint` parameter and is used as default.
|
||||
* `username` of UserModel in {project_name} is used to represent the user on CD, {project_name} and the authentication entity.
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ When a user attempts to log in, {project_name} examines that user's storage to f
|
|||
|
||||
External user databases rarely have the data necessary to support all the features of {project_name}, so the User Storage Provider can opt to store items locally in {project_name} user data storage. Providers can import users locally and sync periodically with external data storage. This approach depends on the capabilities of the provider and the configuration of the provider. For example, your external user data storage may not support OTP. The OTP can be handled and stored by {project_name}, depending on the provider.
|
||||
|
||||
=== Adding a Provider
|
||||
=== Adding a provider
|
||||
To add a storage provider, perform the following procedure:
|
||||
|
||||
.Procedure
|
||||
|
|
@ -20,7 +20,7 @@ image:{project_images}/user-federation.png[User Federation]
|
|||
+
|
||||
. Select the provider type from the *Add Provider* list. {project_name} brings you to that provider's configuration page.
|
||||
|
||||
=== Dealing with Provider Failures
|
||||
=== Dealing with provider failures
|
||||
|
||||
If a User Storage Provider fails, you may not be able to log in and view users in the Admin Console. {project_name} does not detect failures when using a Storage Provider to look up a user, so it cancels the invocation. If you have a Storage Provider with a high priority that fails during user lookup, the login or user query fails with an exception and will not fail over to the next configured provider.
|
||||
|
||||
|
|
|
|||
|
|
@ -150,8 +150,6 @@ directory entry using `ldapsearch` and base64 decode the `userPassword` attribut
|
|||
[[_ldap_troubleshooting]]
|
||||
==== Troubleshooting
|
||||
|
||||
- It is useful to increase the logging level to TRACE for the category `org.keycloak.storage.ldap`. You increase this level in the logging
|
||||
|
||||
It is useful to increase the logging level to TRACE for the category `org.keycloak.storage.ldap`. You increase this level in the logging
|
||||
subsystem in the `standalone(-ha).xml` file. With this setting, many logging messages are sent
|
||||
to the `server.log` file in the `TRACE` level, including the logging for all queries to the LDAP server and the parameters, which were
|
||||
|
|
@ -159,25 +157,24 @@ used to send the queries. When you are creating any LDAP question on user forum
|
|||
enabled TRACE logging. If it is too big, the good alternative is to include just the snippet from server log with the messages, which were
|
||||
added to the log during the operation, which causes the issues to you.
|
||||
|
||||
When you create LDAP provider, message appear in the server log in the INFO level starting with:
|
||||
|
||||
- When you create LDAP provider, message appear in the server log in the INFO level starting with:
|
||||
|
||||
When you create LDAP provider, message appear in the server log in the INFO level starting with:
|
||||
|
||||
```
|
||||
[source,bash,subs=+attributes]
|
||||
----
|
||||
Creating new LDAP Store for the LDAP storage provider: ...
|
||||
```
|
||||
----
|
||||
|
||||
It shows the configuration of your LDAP provider. Before you are asking the questions or reporting bugs, it will be nice to include this
|
||||
message to show your LDAP configuration. Eventually feel free to replace some config changes, which you do not want to include, with some
|
||||
placeholder values. One example is `bindDn=some-placeholder` . For `connectionUrl`, feel free to replace it as well, but it is generally
|
||||
useful to include at least the protocol, which was used (`ldap` vs `ldaps`)`. Similarly it can be useful to include the details for
|
||||
configuration of your LDAP mappers, which are displayed with the message like this at the DEBUG level:
|
||||
```
|
||||
[source,bash,subs=+attributes]
|
||||
----
|
||||
Mapper for provider: XXX, Mapper name: YYY, Provider: ZZZ ...
|
||||
```
|
||||
Note those messages are displayed just with the enabled DEBUG logging.
|
||||
----
|
||||
|
||||
- For tracking the performance or connection pooling issues, consider setting the value of property `Connection Pool Debug Level` of
|
||||
Note those messages are displayed just with the enabled DEBUG logging.
|
||||
|
||||
For tracking the performance or connection pooling issues, consider setting the value of property `Connection Pool Debug Level` of
|
||||
the LDAP provider to value `all`. This will add lots of additional messages to server log with the included logging for the LDAP connection
|
||||
|
|
@ -189,11 +186,6 @@ of the LDAP provider connection.
|
|||
If no more messages appear for connection pooling even after server restart, it can indicate that connection pooling does not work
|
||||
with your LDAP server.
|
||||
|
||||
- For the case of reporting LDAP issue, you may consider to attach some part of your LDAP tree with the target data, which causes issues
|
||||
in your environment. For example if login of some user takes lot of time, you can consider attach his LDAP entry showing count of `member` attributes
|
||||
of various "group" entries. In this case, it might be useful to add if those group entries are mapped to some Group LDAP mapper (or Role LDAP Mapper)
|
||||
in {project_name} etc.
|
||||
|
||||
For the case of reporting LDAP issue, you may consider to attach some part of your LDAP tree with the target data, which causes issues
|
||||
in your environment. For example if login of some user takes lot of time, you can consider attach his LDAP entry showing count of `member` attributes
|
||||
of various "group" entries. In this case, it might be useful to add if those group entries are mapped to some Group LDAP mapper (or Role LDAP Mapper)
|
||||
|
|
|
|||
|
|
@ -1,45 +0,0 @@
|
|||
|
||||
|
||||
=== Enabling account deletion by users
|
||||
|
||||
{project_name} can allow applications end users to delete their account through the Account Console. The functionality is not enabled by default. To enable it, the following steps needs be taken:
|
||||
|
||||
* Enabling the "Delete Account" Required Action
|
||||
|
||||
Allowing the user to delete their account is done through an AIA (Application Initiated Action). You need first of all to enable the action from the admin console. In the Authentication menu, go to the Required Actions tab and tick the enabled checkbox for the "Delete Account" action.
|
||||
|
||||
image:images/enable-delete-account-action.png[]
|
||||
|
||||
* Making sure the user has the "delete-account" as a client role:
|
||||
|
||||
The delete account functionality is enabled on a per user basis. The second requirement to enable the delete account functionality is to make sure the user has the `delete-account` as a client role.
|
||||
|
||||
To enable the delete account role for a user, go to the Users menu, and find the user for which the delete account functionality is to be enabled. In the "Role Mappings" Tab, select the "account" client from "Clients Role" list.
|
||||
|
||||
Finally, select `delete-account` and click on add selected.
|
||||
|
||||
image:images/delete-account-client-role.png[]
|
||||
|
||||
|
||||
=== Deleting a user in action
|
||||
|
||||
|
||||
Once the functionality is enabled, the user will see a new section named "Delete Account" appear in the bottom of the "Personal Info" page
|
||||
|
||||
image:images/delete-account-page.png[]
|
||||
|
||||
As stated by the warning message, this action is irreversible, and it implies the deletion of all the user's data in Keycloak.
|
||||
|
||||
Once the user clicks on Delete, he will be prompted to enter his credentials again and redirected to the final confirmation step:
|
||||
|
||||
|
||||
image:images/delete-account-confirm.png[]
|
||||
|
||||
|
||||
|
||||
After confirming, the user's account will be deleted.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in a new issue