Skip to content

Commit

Permalink
KEYCLOAK-15756 Initial wording (#58)
Browse files Browse the repository at this point in the history 
* KEYCLOAK-15756 Initial wording

* KEYCLOAK-15756 Post feedback changes
  • Loading branch information
@briandooley @mposolda
briandooley authored and mposolda committed Sep 21, 2021
1 parent 4bcb4a4 commit 9e66b97
Show file tree
Hide file tree
Showing 26 changed files with 496 additions and 805 deletions.
25 changes: 8 additions & 17 deletions server_admin/topics/identity-broker.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,27 +2,18 @@
[[_identity_broker]]
== Integrating identity providers

An Identity Broker is an intermediary service that connects multiple service providers with different identity providers.
As an intermediary service, the identity broker is responsible for creating
a trust relationship with an external identity provider in order to use its identities to access internal services exposed by service providers.
An Identity Broker is an intermediary service connecting service providers with identity providers. The identity broker creates a relationship with an external identity provider to use the provider's identities to access the internal services the service provider exposes.

From a user perspective, an identity broker provides a user-centric and centralized way to manage identities across different security
domains or realms. An existing account can be linked with one or more identities from different identity providers or even created
based on the identity information obtained from them.
From a user perspective, identity brokers provide a user-centric, centralized way to manage identities for security domains and realms. You can link an account with one or more identities from identity providers or create an account based on the identity information from them.

An identity provider is usually based on a specific protocol that is used to authenticate and communicate authentication and authorization information to their users.
It can be a social provider such as Facebook, Google or Twitter. It can be a business partner whose users need to access your services. Or it can be a cloud-based identity
service that you want to integrate with.
An identity provider derives from a specific protocol used to authenticate and send authentication and authorization information to users. It can be:

Usually, identity providers are based on the following protocols:
* A social provider such as Facebook, Google, or Twitter.
* A business partner whose users need to access your services.
* A cloud-based identity service you want to integrate.

Typically, {project_name} bases identity providers on the following protocols:

* `SAML v2.0`
* `OpenID Connect v1.0`
* `OAuth v2.0`

In the next sections we'll see how to configure and use {project_name} as an identity broker, covering some important aspects such as:

* `Social Authentication`
* `OpenID Connect v1.0 Brokering`
* `SAML v2.0 Brokering`
* `Identity Federation`
74 changes: 28 additions & 46 deletions server_admin/topics/identity-broker/configuration.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,87 +1,69 @@

[[_general-idp-config]]

=== General Configuration

The identity broker configuration is all based on identity providers.
Identity providers are created for each realm and by default they are enabled for every single application.
That means that users from a realm can use any of the registered identity providers when signing in to an application.

In order to create an identity provider click the `Identity Providers` left menu item.
The foundations of the identity broker configuration are identity providers (IDPs). {project_name} creates identity providers for each realm and enables them for every application by default. Users from a realm can use any of the registered identity providers when signing in to an application.

.Procedure
. Click *Identity Providers* in the menu.
+
.Identity Providers
image:{project_images}/identity-providers.png[]

In the drop down list box, choose the identity provider you want to add. This will bring you to the
configuration page for that identity provider type.

.Add Identity Provider
image:{project_images}/add-identity-provider.png[]

Above is an example of configuring a Facebook social login provider. Once you configure an IDP, it will appear on the {project_name}
login page as an option. It's possible to have custom icons on login screen for each identity provider.
For more details, please refer to the link:{developerguide_link}#custom-identity-providers-icons[custom icons].

image:{project_images}/identity-providers.png[Identity Providers]
+
. From the `Add provider` list, select the identity provider you want to add. {project_name} displays the configuration page for the identity provider you selected.
+
.Add Facebook Identity Provider
image:{project_images}/add-identity-provider.png[Add Facebook Identity Provider]
+
When you configure an identity provider, the identity provider appears on the {project_name} login page as an option. You can place custom icons on the login screen for each identity provider. See link:{developerguide_link}#custom-identity-providers-icons[custom icons] for more information.
+
.IDP login page
image:{project_images}/identity-provider-login-page.png[]


Social::
Social providers allow you to enable social authentication in your realm.
{project_name} makes it easy to let users log in to your application using an existing account with a social network.
Currently supported providers include: Twitter, Facebook, Google, LinkedIn, Instagram, Microsoft, PayPal, Openshift v3, GitHub, GitLab, Bitbucket, and Stack Overflow.
Social providers enable social authentication in your realm. With {project_name}, users can log in to your application using a social network account. Supported providers include Twitter, Facebook, Google, LinkedIn, Instagram, Microsoft, PayPal, Openshift v3, GitHub, GitLab, Bitbucket, and Stack Overflow.

Protocol-based::
Protocol-based providers are those that rely on a specific protocol in order to authenticate and authorize users.
They allow you to connect to any identity provider compliant with a specific protocol.
{project_name} provides support for SAML v2.0 and OpenID Connect v1.0 protocols.
It makes it easy to configure and broker any identity provider based on these open standards.
Protocol-based providers rely on specific protocols to authenticate and authorize users. Using these providers, you can connect to any identity provider compliant with a specific protocol. {project_name} provides support for SAML v2.0 and OpenID Connect v1.0 protocols. You can configure and broker any identity provider based on these open standards.

Although each type of identity provider has its own configuration options, all of them share some very common configuration.
Regardless of which identity provider you are creating, you'll see the following configuration options available:
Although each type of identity provider has its configuration options, all share a common configuration. The following configuration options available:

.Common Configuration
[cols="1,1", options="header"]
|===
|Configuration|Description

|Alias
|The alias is a unique identifier for an identity provider. It is used to reference an identity provider internally.
Some protocols such as OpenID Connect require a redirect URI or callback url in order to communicate with an identity provider.
In this case, the alias is used to build the redirect URI.
Every single identity provider must have an alias. Examples are `facebook`, `google`, `idp.acme.com`, etc.
|The alias is a unique identifier for an identity provider and references an internal identity provider. {project_name} uses the alias to build redirect URIs for OpenID Connect protocols that require a redirect URI or callback URL to communicate with an identity provider. All identity providers must have an alias. Alias examples include `facebook`, `google`, and `idp.acme.com`.

|Enabled
|Turn the provider on/off.
|Toggles the provider ON or OFF.

|Hide on Login Page
|When this switch is on, this provider will not be shown as a login option on the login page. Clients can still request to use this provider by using the 'kc_idp_hint' parameter in the URL they use to request a login.
|When *ON*, {project_name} does not display this provider as a login option on the login page. Clients can request this provider by using the 'kc_idp_hint' parameter in the URL to request a login.

|Account Linking Only
|When this switch is on, this provider cannot be used to login users and will not be shown as an option on the login page. Existing accounts can still be linked with this provider though.

|When *ON*, {project_name} links existing accounts with this provider. This provider cannot log users in, and {project_name} does not display this provider as an option on the login page.

|Store Tokens
|Whether or not to store the token received from the identity provider.
|When *ON*, {project_name} stores tokens from the identity provider.

|Stored Tokens Readable
|Whether or not users are allowed to retrieve the stored identity provider token. This also applies to the _broker_ client-level
role _read token_.
|When *ON*, users can retrieve the stored identity provider token. This action also applies to the _broker_ client-level role _read token_.

|Trust Email
|If the identity provider supplies an email address this email address will be trusted. If the realm required email validation,
users that log in from this IDP will not have to go through the email verification process.
|When *ON*, {project_name} trusts email addresses from the identity provider. If the realm requires email validation, users that log in from this identity provider do not need to perform the email verification process.

|GUI Order
|The order number that sorts how the available IDPs are listed on the login page.
|The sort order of the available identity providers on the login page.

|First Login Flow
|This is the authentication flow that will be triggered for users that log into {project_name} through this IDP
for the first time ever.
|The authentication flow {project_name} triggers when users use this identity provider to log into {project_name} for the first time.

|Post Login Flow
|Authentication flow that is triggered after the user finishes logging in with the external identity provider.
|The authentication flow {project_name} triggers when a user finishes logging in with the external identity provider.

|Sync Mode
|Strategy of how to update user information from the idp through mappers: When choosing `legacy`, the current behavior is kept,
`import` will never update user data, while `force` will always update user data when possible. See also the documentation for <<_mappers, Identity Provider Mappers>> for more details.
|Strategy to update user information from the identity provider through mappers. When choosing *legacy*, {project_name} used the current behavior. *Import* does not update user data and *force* updates user data when possible. See <<_mappers, Identity Provider Mappers>> for more information.
|===
13 changes: 10 additions & 3 deletions server_admin/topics/identity-broker/default-provider.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,16 @@

[[default_identity_provider]]

=== Default Identity Provider

It is possible to automatically redirect to a identity provider instead of displaying the login form. To enable this go to the `Authentication` page in the administration console and select the `Browser` flow. Then click on config for the `Identity Provider Redirector` authenticator. Set `Default Identity Provider` to the alias of the identity provider you want to automatically redirect users to.
{project_name} can redirect to an identity provider rather than displaying the login form. To enable this redirection:

.Procedure
. Click *Authentication* in the menu.
. Click the *Browser* flow.
. Select *Identity Provider Redirector* from the drop-down list.
. Set *Default Identity Provider* to the identity provider you want to redirect users to.

If the configured default identity provider is not found the login form will be displayed instead.
If {project_name} does not find the configured default identity provider, the login form is displayed.

This authenticator is also responsible for dealing with the `kc_idp_hint` query parameter. See <<_client_suggested_idp, client suggested identity provider>> section for more details.
This authenticator is responsible for processing the `kc_idp_hint` query parameter. See the <<_client_suggested_idp, client suggested identity provider>> section for more information.
Loading

0 comments on commit 9e66b97

Please sign in to comment.