libre.sh/keycloak-scim
4
0
Fork 0
Code Issues 15 Pull requests Releases 1 Activity Actions

KEYCLOAK-15756 Initial wording (#58)

Browse source 
* KEYCLOAK-15756 Initial wording

* KEYCLOAK-15756 Post feedback changes
This commit is contained in:
Brian Dooley 2021-03-22 13:20:23 +00:00 committed by Marek Posolda
parent 4bcb4a49d7
commit 9e66b97faf
26 changed files with 488 additions and 797 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
server_admin/topics/identity-broker.adoc
View file

@ -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
server_admin/topics/identity-broker/configuration.adoc
View file

@ -1,43 +1,33 @@
[[_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"]
@ -45,43 +35,35 @@ Regardless of which identity provider you are creating, you'll see the following
|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
server_admin/topics/identity-broker/default-provider.adoc
View file

@ -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:
If the configured default identity provider is not found the login form will be displayed instead.
.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.
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.
If {project_name} does not find the configured default identity provider, the login form is displayed.
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.

111
server_admin/topics/identity-broker/first-login-flow.adoc
View file

@ -1,97 +1,97 @@
[[_identity_broker_first_login]]
=== First Login Flow
When a user logs in through identity brokering some aspects of the user are imported and linked within the realm's local database.
When {project_name} successfully authenticates users through an external identity provider
there can be two situations:
When users log in through identity brokering, {project_name} imports and links aspects of the user within the realm's local database. When {project_name} successfully authenticates users through an external identity provider, two situations can exist:
* There is already a {project_name} user account imported and linked with the authenticated identity provider account.
In this case, {project_name} will just authenticate as the existing user and redirect back to application.
* There is not yet an existing {project_name} user account imported and linked for this external user.
Usually you just want to register and import the new account into {project_name} database, but what if there is an existing
{project_name} account with the same email? Automatically linking the existing local account to the external
identity provider is a potential security hole as you can't always trust the information you get from the external identity provider.
* {project_name} has already imported and linked a user account with the authenticated identity provider account. In this case, {project_name} authenticates as the existing user and redirects back to the application.
* No account exists for this user in {project_name}. Usually, you register and import a new account into the {project_name} database, but there may be an existing {project_name} account with the same email address. Automatically linking the existing local account to the external identity provider is a potential security hole. You cannot always trust the information you get from the external identity provider.
Different organizations have different requirements when dealing with some of the conflicts and situations listed above.
For this, there is a `First Login Flow` option in the IDP settings which allows you to choose a <<_authentication-flows, workflow>> that will be
used after a user logs in from an external IDP the first time.
By default it points to `first broker login` flow, but you can configure and use your own flow and use different flows for different identity providers.
Different organizations have different requirements when dealing with some of these situations. With {project_name}, you can use the `First Login Flow` option in the IDP settings to choose a <<_authentication-flows, workflow>> for a user logging in from an external IDP for the first time. By default, the `First Login Flow` option points to the `first broker login` flow, but you can use your flow or different flows for different identity providers.
The flow itself is configured in admin console under `Authentication` tab.
When you choose `First Broker Login` flow, you will see what authenticators are used by default.
You can re-configure the existing flow. (For example you can disable some authenticators, mark some of them as `required`, configure some authenticators, etc).
The flow is in the Admin Console under the *Authentication* tab. When you choose the `First Broker Login` flow, you see the authenticators used by default. You can re-configure the existing flow. For example, you can disable some authenticators, mark some of them as `required`, or configure some authenticators.
ifeval::[{project_community}==true]
You can also create a new authentication flow and/or write your own Authenticator implementations and use it in your flow.
See link:{developerguide_link}[{developerguide_name}] for more details.
You can also create a new authentication flow, write your own Authenticator implementations, and use it in your flow. See link:{developerguide_link}[{developerguide_name}] for more information.
endif::[]
==== Default First Login Flow
Let's describe the default behavior provided by `First Broker Login` flow.
==== Default First Login Flow Authenticators
Review Profile::
This authenticator might display the profile info page, where the user can review their profile retrieved from an identity provider.
The authenticator is configurable.
You can set the `Update Profile On First Login` option.
When `On`, users will be always presented with the profile page asking for additional information in order to federate their identities.
When `missing`, users will be presented with the profile page only if some mandatory information (email, first name, last name) is not provided by the identity provider.
If `Off`, the profile page won't be displayed, unless user clicks in later phase on `Review profile info` link (page displayed in later phase
by `Confirm Link Existing Account` authenticator).
* This authenticator displays the profile information page, so the users can review their profile that {project_name} retrieves from an identity provider.
* You can set the `Update Profile On First Login` option in the *Actions* menu.
* When *ON*, users are presented with the profile page requesting additional information to federate the user's identities.
* When *missing*, users are presented with the profile page if the identity provider does not provide mandatory information, such as email, first name, or last name.
* 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::
<<<<<<< HEAD
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.
>>>>>>> KEYCLOAK-15756 Initial wording (#58)
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 info page, the user will see that there is an existing {project_name} account with the same email.
They can review their profile again and use different email or username (flow is restarted and goes back to `Review Profile` authenticator).
Or they can confirm that they want to link their identity provider account with their existing {project_name} account.
Disable this authenticator if you don't want users to see this confirmation page, but go straight to linking identity provider account by email verification or re-authentication.
* 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.
* Alternatively, users can confirm that they want to link their identity provider account with their existing {project_name} account.
* Disable this authenticator if you do not want users to see this confirmation page and go straight to linking identity provider account by email verification or re-authentication.
Verify Existing Account By Email::
This authenticator is `ALTERNATIVE` by default, so it's used only if the realm has SMTP setup configured.
It will send email to the user, where they can confirm that they want to link the identity provider with their {project_name} account.
Disable this if you don't want to confirm linking by email, but instead you always want users to reauthenticate with their password (and alternatively OTP).
* This authenticator is `ALTERNATIVE` by default. {project_name} uses this authenticator if the realm has an SMTP setup configured.
* The authenticator sends an email to users to confirm that they want to link the identity provider with their {project_name} account.
* Disable this authenticator if you do not want to confirm linking by email, but want users to reauthenticate with their password.
Verify Existing Account By Re-authentication::
This authenticator is used if email authenticator is disabled or not available (SMTP not configured for realm). It will display a login screen
where the user needs to authenticate to link their {project_name} account with the Identity provider.
User can also re-authenticate with some different identity provider, which is already linked to their {project_name} account.
You can also force users to use OTP. Otherwise it's optional and used only if OTP is already set for the user account.
* Use this authenticator if the email authenticator is not available. For example, you have not configured SMTP for your realm. This authenticator displays a login screen for users to authenticate to link their {project_name} account with the Identity Provider.
* Users can also re-authenticate with another identity provider already linked to their {project_name} account.
* You can force users to use OTP. Otherwise, it is optional and used if you have set OTP for the user account.
==== Automatically Link Existing First Login Flow
WARNING: The AutoLink authenticator would be dangerous in a generic environment where users can register themselves using arbitrary usernames/email addresses. Do not use this authenticator unless registration of users is carefully curated and usernames/email addresses are assigned, not requested.
[WARNING]
====
The AutoLink authenticator is dangerous in a generic environment where users can register themselves using arbitrary usernames or email addresses. Do not use this authenticator unless you are carefully curating user registration and assigning usernames and email addresses.
====
In order to configure a first login flow in which users are automatically linked without being prompted, create a new flow with the following two authenticators:
To configure a first login flow that links users automatically without prompting, create a new flow with the following two authenticators:
Create User If Unique::
This authenticator ensures that unique users are handled. Set the authenticator requirement to "Alternative".
This authenticator ensures {project_name} handles unique users. Set the authenticator requirement to *Alternative*.
Automatically Set Existing User::
Automatically sets an existing user to the authentication context without any verification. Set the authenticator requirement to "Alternative".
This authenticator sets an existing user to the authentication context without verification. Set the authenticator requirement to "Alternative".
NOTE: The described setup uses two authenticators. This setup is the simplest one, but it is possible to use other
authenticators according to your needs. For example, you can add the Review Profile authenticator to the beginning of the flow if you still want
end users to confirm their profile information. You can also add authentication mechanisms to this flow, forcing a user to verify his credentials. This
would require a more complex flow, for example setting the "Automatically Set Existing User" and "Password Form" as "Required" in an "Alternative" sub-flow.
[NOTE]
====
This setup is the simplest setup available, but it is possible to use other authenticators. For example:
* You can add the Review Profile authenticator to the beginning of the flow if you want end users to confirm their profile information.
* You can add authentication mechanisms to this flow, forcing a user to verify their credentials. Adding authentication mechanisms requires a complex flow. For example, you can set the "Automatically Set Existing User" and "Password Form" as "Required" in an "Alternative" sub-flow.
====
[[_disabling_automatic_user_creation]]
==== Disabling Automatic User Creation
The Default first login flow will look up a Keycloak account matching the external identity, and will then offer to link them; if there is no matching Keycloak account, it will automatically create one.
This default behavior may be unsuitable for some setups, for example, when using read-only LDAP user store (which means all users are pre-created).
In this case, automatic user creation should be turned off. To disable user creation:
The Default first login flow looks up the {project_name} account matching the external identity and offers to link them. If no matching {project_name} account exists, the flow automatically creates one.
* open the `First Broker Login` flow configuration;
* set `Create User If Unique` to `DISABLED`;
* set `Confirm Link Existing Account` to `DISABLED`.
This default behavior may be unsuitable for some setups. One example is when you use a read-only LDAP user store, where all users are pre-created. In this case, you must switch off automatic user creation.
To disable user creation:
.Procedure
. Click *Authentication* in the menu.
. Select *First Broker Login* from the list.
. Set *Create User If Unique* to *DISABLED*.
. Set *Confirm Link Existing Account* to *DISABLED*.
<<<<<<< HEAD
This configuration also implies that Keycloak itself won't be able to determine which internal account would correspond to the external identity.
Therefore, the `Verify Existing Account By Re-authentication` authenticator will ask the user to provide both username and password.
@ -112,4 +112,7 @@ Automatically sets an existing user to the authentication context without any ve
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.
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 ...) 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.
>>>>>>> KEYCLOAK-15756 Initial wording (#58)

5
server_admin/topics/identity-broker/logout.adoc
View file

@ -1,7 +1,4 @@
=== Identity broker logout
When logout from {project_name} is triggered, {project_name} will send a request to the external identity provider
that was used to login to Keycloak, and the user will be logged out from this identity provider as well.
It is possible to skip this behavior and avoid logout at the external identity provider.
See link:{adapterguide_logout_link}[adapter logout documentation] for more details.
When logging out, {project_name} sends a request to the external identity provider that is used to log in initially and logs the user out of this identity provider. You can skip this behavior and avoid logging out of the external identity provider. See link:{adapterguide_logout_link}[adapter logout documentation] for more information.

54
server_admin/topics/identity-broker/mappers.adoc
View file

@ -1,36 +1,32 @@
[[_mappers]]
=== Mapping Claims and Assertions
You can import the SAML and OpenID Connect metadata provided by the external IDP you are authenticating with into the environment
of the realm. This allows you to extract user profile metadata and other information so that you can make it available to your
applications.
You can import the SAML and OpenID Connect metadata, provided by the external IDP you are authenticating with, into the realm. After importing, you can extract user profile metadata and other information, so you can make it available to your applications.
Each new user that logs into your realm via an external identity provider will have an entry for them created in the local
{project_name} database, based on the metadata from the SAML or OIDC assertions and claims.
Each user logging into your realm using an external identity provider has an entry in the local {project_name} database, based on the metadata from the SAML or OIDC assertions and claims.
If you click on an identity provider listed in the `Identity Providers` page for your realm, you will be brought to the IDPs
`Settings` tab. On this page there is also a `Mappers` tab. Click on that tab to start mapping your incoming IDP metadata.
.Procedure
. Click *Identity Providers* in the menu.
. Select one of the identity providers in the list.
. Click the *Mappers* tab.
+
.identity provider mappers
image:{project_images}/identity-provider-mappers.png[identity provider mappers]
+
. Click *Create*.
+
.identity provider mapper
image:{project_images}/identity-provider-mapper.png[identity provider mapper]
+
. Select a value for *Sync Mode Override*. The mapper updates user information when users log in repeatedly according to this setting.
.. Select *legacy* to use the behavior of the previous {project_name} version.
.. Select *import* to import data from when the user was first created in {project_name} during the first login to {project_name} with a particular identity provider.
.. Select *force* to update user data at each user login.
.. Select *inherit* to use the sync mode configured in the identity provider. All other options will override this sync mode.
. Select a mapper from the *Mapper Type* list. Hover over the *Mapper Type* for a description of the mapper and configuration to enter for the mapper.
. Click *Save*.
image:{project_images}/identity-provider-mappers.png[]
For JSON-based claims, you can use dot notation for nesting and square brackets to access array fields by index. For example, `contact.address[0].country`.
There is a `Create` button on this page.
Clicking on this create button allows you to create a broker mapper.
Broker mappers can import SAML attributes or OIDC ID/Access token claims into user attributes and user role mappings.
image:{project_images}/identity-provider-mapper.png[]
Select a mapper from the `Mapper Type` list. Hover over the tooltip to see a description of what the mapper does. The
tooltips also describe what configuration information you need to enter. Click `Save` and your new mapper will be added.
The mapper will update user information when the user logs in repeatedly according to the `Sync Mode Override`:
* Choose `legacy` to use the behavior in the previous {project_name} version.
* Choose `import` to import only data from when the user was first created in {project_name} during the first login to {project_name} with a particular identity provider.
* Choose `force` to update user data at each user login.
* Choose `inherit` to use the sync mode configured in the identity provider, all other options will override this sync mode.
For JSON based claims, you can use dot notation for nesting and square brackets to access array fields by index.
For example 'contact.address[0].country'.
To investigate the structure of user profile JSON data provided by social providers you can enable the `DEBUG` level logger `org.keycloak.social.user_profile_dump`.
This is done in the server's app-server configuration file (domain.xml or standalone.xml).
To investigate the structure of user profile JSON data provided by social providers, you can enable the `DEBUG` level logger `org.keycloak.social.user_profile_dump` in the server's app-server configuration file (domain.xml or standalone.xml).

81
server_admin/topics/identity-broker/oidc.adoc
View file

@ -1,103 +1,80 @@
[[_identity_broker_oidc]]
=== OpenID Connect v1.0 Identity Providers
{project_name} can broker identity providers based on the OpenID Connect protocol. These IDPs must support the xref:proc-creating-oidc-client_{context}[Authorization Code Flow]
as defined by the specification in order to authenticate the user and authorize access.
{project_name} brokers identity providers based on the OpenID Connect protocol. These identity providers (IDPs) must support the xref:proc-creating-oidc-client_{context}[Authorization Code Flow] defined in the specification to authenticate users and authorize access.
To begin configuring an OIDC provider, go to the `Identity Providers` left menu item
and select `OpenID Connect v1.0` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Procedure
. Click *Identity Providers* in the menu.
. From the `Add provider` list, select `OpenID Connect v1.0`.
+
.Add Identity Provider
image:{project_images}/oidc-add-identity-provider.png[]
The initial configuration options on this page are described in <<_general-idp-config, General IDP Configuration>>.
You must define the OpenID Connect configuration options as well. They basically describe the OIDC IDP you are communicating with.
image:{project_images}/oidc-add-identity-provider.png[Add Identity Provider]
+
. Enter your initial configuration options. See <<_general-idp-config, General IDP Configuration>> for more information about configuration options.
+
.OpenID Connect Config
|===
|Configuration|Description
|Authorization URL
|Authorization URL endpoint required by the OIDC protocol.
|The authorization URL endpoint the OIDC protocol requires.
|Token URL
|Token URL endpoint required by the OIDC protocol.
|The token URL endpoint the OIDC protocol requires.
|Logout URL
|Logout URL endpoint defined in the OIDC protocol. This value is optional.
|The logout URL endpoint in the OIDC protocol. This value is optional.
|Backchannel Logout
|Backchannel logout is a background, out-of-band, REST invocation to the IDP to logout the user. Some IDPs can only perform logout through browser redirects as they may
only be able to identity sessions via a browser cookie.
|A background, out-of-band, REST request to the IDP to log out the user. Some IDPs perform logout through browser redirects only, as they may identify sessions using a browser cookie.
|User Info URL
|User Info URL endpoint defined by the OIDC protocol. This is an endpoint from which user profile information can be downloaded.
|An endpoint the OIDC protocol defines. This endpoint points to user profile information.
|Client Authentication
|Switch to define the Client Authentication method to be used with the Authorization Code Flow. In the case of JWT signed with private key, the realm private key
is used. In the other cases, a client secret has to be defined.
For more details, see the https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication[Client Authentication specifications].
|Defines the Client Authentication method {project_name} uses with the Authorization Code Flow. In the case of JWT signed with a private key, {project_name} uses the realm private key. In the other cases, define a client secret. See the https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication[Client Authentication specifications] for more information.
|Client ID
|This realm will act as an OIDC client to the external IDP. Your realm will need an OIDC client ID when using the Authorization Code Flow
to interact with the external IDP.
|A realm acting as an OIDC client to the external IDP. The realm must have an OIDC client ID if you use the Authorization Code Flow to interact with the external IDP.
|Client Secret
|This realm will need a client secret to use when using the Authorization Code Flow. The value of this field can refer a value from an external <<_vault-administration,vault>>.
|Client secret from an external <<_vault-administration,vault>>. This secret is necessary if you are using the Authorization Code Flow.
|Client Assertion Signature Algorithm
|Signature algorithm to create JWT assertion as client authentication.
In the case of JWT signed with private key or Client secret as jwt, it is required. If no algorithm is specified, the following algorithm is adapted. `RS256` is adapted in the case of JWT signed with private key. `HS256` is adapted in the case of Client secret as jwt.
|Issuer
|Responses from the IDP may contain an issuer claim. This config value is optional. If specified, this claim will be validated against the value you provide.
|{project_name} validates issuer claims, in responses from the IDP, against this value.
|Default Scopes
|Space-separated list of OIDC scopes to send with the authentication request. The default is `openid`.
|A list of OIDC scopes {project_name} sends with the authentication request. The default value is `openid`. A space separates each scope.
|Prompt
|Another optional switch. This is the prompt parameter defined by the OIDC specification. Through it you can force re-authentication and other options. See the specification for
more details.
|The prompt parameter in the OIDC specification. Through this parameter, you can force re-authentication and other options. See the specification for more details.
|Accepts prompt=none forward from client
|Specifies whether the IDP accepts forwarded authentication requests that contain the prompt=none query parameter or not. When a realm receives an auth request with `prompt=none` it checks
if the user is currently authenticated and normally returns a `login_required` error if the user is not logged in. However, when a default IDP can be determined
for the auth request (either via `kc_idp_hint` query param or by setting up a default IDP for the realm) we should be able to forward the auth request with
`prompt=none` to the default IDP so that it checks if the user is currently authenticated there. Because not all IDPs support requests with `prompt=none` this switch
is used to indicate if the default IDP supports the param before redirecting the auth request.
|Specifies if the IDP accepts forwarded authentication requests containing the `prompt=none` query parameter. If a realm receives an auth request with `prompt=none`, the realm checks if the user is currently authenticated and returns a `login_required` error if the user has not logged in. When {project_name} determines a default IDP for the auth request (using the `kc_idp_hint` query parameter or having a default IDP for the realm), you can forward the auth request with `prompt=none` to the default IDP. The default IDP checks the authentication of the user there. Because not all IDPs support requests with `prompt=none`, {project_name} uses this switch to indicate that the default IDP supports the parameter before redirecting the authentication request.
It is important to note that if the user is not authenticated in the IDP, the client will still get a `login_required` error. Even if the user is currently authenticated in the IDP,
the client might still get an `interaction_required` error if authentication or consent pages requiring user interaction would be otherwise displayed. This includes required actions
(e.g. change password), consent screens and any screens set to be displayed by the `first broker login` flow or `post broker login` flow.
If the user is unauthenticated in the IDP, the client still receives a `login_required` error. If the user is authentic in the IDP, the client can still receive an `interaction_required` error if {project_name} must display authentication pages that require user interaction. This authentication includes required actions (for example, password change), consent screens, and screens set to display by the `first broker login` flow or `post broker login` flow.
|Validate Signatures
|Another optional switch. This is to specify if {project_name} will verify the signatures on the external ID Token signed by this identity provider. If this is on,
the {project_name} will need to know the public key of the external OIDC identity provider. See below for how to set it up.
WARNING: For the performance purposes, {project_name} caches the public key of the external OIDC identity provider. If you think that private key of your identity provider
was compromised, it is obviously good to update your keys, but it's also good to clear the keys cache. See
<<_clear-cache, Clearing the cache>> section for more details.
|Specifies if {project_name} verifies signatures on the external ID Token signed by this IDP. If *ON*, {project_name} must know the public key of the external OIDC IDP. For performance purposes, {project_name} caches the public key of the external OIDC identity provider. If your identity provider's private key is compromised, update your keys and clear the keys cache. See <<_clear-cache, Clearing the cache>> section for more details.
|Use JWKS URL
|Applicable if `Validate Signatures` is on. If the switch is on, then identity provider public keys will be downloaded from given JWKS URL.
This allows great flexibility because new keys will be always re-downloaded when the identity provider generates new keypair. If the switch is off,
then public key (or certificate) from the {project_name} DB is used, so whenever the identity provider keypair changes, you will always need to import the new key to the {project_name} DB as well.
|This switch is applicable if `Validate Signatures` is *ON*. If *Use JWKS URL* is *ON*, {project_name} downloads the IDP's public keys from the JWKS URL. New keys download when the identity provider generates a new keypair. If *OFF*, {project_name} uses the public key (or certificate) from its database, so when the IDP keypair changes, import the new key to the {project_name} database as well.
|JWKS URL
|URL where the identity provider JWK keys are stored. See the https://self-issued.info/docs/draft-ietf-jose-json-web-key.html[JWK specification] for more details.
If you use an external {project_name} as an identity provider, then you can use URL like http://broker-keycloak:8180/auth/realms/test/protocol/openid-connect/certs assuming your brokered
{project_name} is running on http://broker-keycloak:8180 and it's realm is `test`.
|The URL pointing to the location of the IDP JWK keys. For more information, see the https://self-issued.info/docs/draft-ietf-jose-json-web-key.html[JWK specification]. If you use an external {project_name} as an IDP, you can use a URL such as http://broker-keycloak:8180/auth/realms/test/protocol/openid-connect/certs if your brokered {project_name} is running on http://broker-keycloak:8180 and its realm is `test`.
|Validating Public Key
|Applicable if `Use JWKS URL` is off. Here is the public key in PEM format that must be used to verify external IDP signatures.
|The public key in PEM format that {project_name} uses to verify external IDP signatures. This key applies if `Use JWKS URL` is *OFF*.
|Validating Public Key Id
|Applicable if `Use JWKS URL` is off. This field specifies ID of the public key in PEM format. This config value is optional. As there is no standard way
for computing key ID from key, various external identity providers might use different algorithm from {project_name}. If the value of this field
is not specified, the validating public key specified above is used for all requests regardless of key ID sent by external IDP. When set, value of this
field serves as key ID used by {project_name} for validating signatures from such providers and must match the key ID specified by the IDP.
|This setting applies if *Use JWKS URL* is *OFF*. This setting specifies the ID of the public key in PEM format. Because there is no standard way for computing key ID from the key, external identity providers can use different algorithms from what {project_name} uses. If this field's value is not specified, {project_name} uses the validating public key for all requests, regardless of the key ID sent by the external IDP. When *ON*, this field's value is the key ID used by {project_name} for validating signatures from providers and must match the key ID specified by the IDP.
|===
You can also import all this configuration data by providing a URL or file that points to OpenID Provider Metadata (see OIDC Discovery specification).
If you are connecting to a {project_name} external IDP, you can import the IDP settings from the url `<root>/auth/realms/{realm-name}/.well-known/openid-configuration`.
This link is a JSON document describing metadata about the IDP.
You can import all this configuration data by providing a URL or file that points to OpenID Provider Metadata. If you connect to a {project_name} external IDP, you can import the IDP settings from `<root>/auth/realms/{realm-name}/.well-known/openid-configuration`. This link is a JSON document describing metadata about the IDP.

58
server_admin/topics/identity-broker/overview.adoc
View file

@ -1,47 +1,33 @@
[[_identity_broker_overview]]
=== Brokering Overview
When using {project_name} as an identity broker, users are not forced to provide their credentials in order to authenticate in a specific realm.
Instead, they are presented with a list of identity providers from which they can authenticate.
When using {project_name} as an identity broker, {project_name} does not force users to provide their credentials to authenticate in a specific realm. {project_name} displays a list of identity providers from which they can authenticate.
You can also configure a default identity provider. In this case the user will not be given a choice, but will instead be redirected directly to the default provider.
If you configure a default identity provider, {project_name} redirects users to the default provider.
The following diagram demonstrates the steps involved when using {project_name} to broker an external identity provider:
[NOTE]
====
Different protocols may require different authentication flows. All the identity providers supported by {project_name} use the following flow.
====
.Identity Broker Flow
image:images/identity_broker_flow.png[]
image:images/identity_broker_flow.png[Identity Broker Flow]
. User is not authenticated and requests a protected resource in a client application.
. The client applications redirects the user to {project_name} to authenticate.
. At this point the user is presented with the login page where there is a list of identity providers configured in a realm.
. User selects one of the identity providers by clicking on its respective button or link.
. {project_name} issues an authentication request to the target identity provider asking for authentication and the user
is redirected to the login page of the identity provider.
The connection properties and other configuration options for the identity provider were previously set by the administrator in the Admin Console.
. User provides his credentials or consent in order to authenticate with the identity provider.
. Upon a successful authentication by the identity provider, the user is redirected back to {project_name} with an authentication response.
Usually this response contains a security token that will be used by {project_name} to trust the authentication performed by the identity provider
and retrieve information about the user.
. Now {project_name} is going to check if the response from the identity provider is valid.
If valid, it will import and create a new user or just skip that if the user already exists.
If it is a new user, {project_name} may ask the identity provider for information about the user if that info doesn't already exist in the token.
This is what we call _identity federation_.
If the user already exists {project_name} may ask him to link the identity returned from the identity provider with the existing account.
We call this process _account linking_.
What exactly is done is configurable and can be specified by setup of <<_identity_broker_first_login,First Login Flow>>. At the end of this step, {project_name} authenticates the user and issues its own token in order to access the requested resource in the service provider.
. Once the user is locally authenticated, {project_name} redirects the user to the service provider by sending the token previously issued during the local authentication.
. The service provider receives the token from {project_name} and allows access to the protected resource.
. The unauthenticated user requests a protected resource in a client application.
. The client application redirects the user to {project_name} to authenticate.
. {project_name} displays the login page with a list of identity providers configured in a realm.
. The user selects one of the identity providers by clicking its button or link.
. {project_name} issues an authentication request to the target identity provider requesting authentication and redirects the user to the identity provider's login page. The administrator has already set the connection properties and other configuration options for the Admin Console's identity provider.
. The user provides credentials or consents to authenticate with the identity provider.
. Upon successful authentication by the identity provider, the user redirects back to {project_name} with an authentication response. Usually, the response contains a security token used by {project_name} to trust the identity provider's authentication and retrieve user information.
. {project_name} checks if the response from the identity provider is valid.
If valid, {project_name} imports and creates a user if the user does not already exist. {project_name} may ask the identity provider for further user information if the token does not contain that information. This behavior is _identity federation_.
If the user already exists, {project_name} may ask the user to link the identity returned from the identity provider with the existing account. This behavior is _account linking_. With {project_name}, you can configure _Account linking_ and specify it in the <<_identity_broker_first_login,First Login Flow>>. At this step, {project_name} authenticates the user and issues its token to access the requested resource in the service provider.
. When the user authenticates, {project_name} redirects the user to the service provider by sending the token previously issued during the local authentication.
. The service provider receives the token from {project_name} and permits access to the protected resource.
There are some variations of this flow that we will talk about later.
For instance, instead of presenting a list of identity providers, the client application can request a specific one.
Or you can tell {project_name} to force the user to provide additional information before federating his identity.
Variations of this flow are possible. For example, the client application can request a specific identity provider rather than displaying a list of them, or you can set {project_name} to force users to provide additional information before federating their identity.
NOTE: Different protocols may require different authentication flows.
At this moment, all the identity providers supported by {project_name} use a flow just like described above.
However, regardless of the protocol in use, user experience should be pretty much the same.
As you may notice, at the end of the authentication process {project_name} will always issue its own token to client applications.
What this means is that client applications are completely decoupled from external identity providers.
They don't need to know which protocol (eg.: SAML, OpenID Connect, OAuth, etc) was used or how the user's identity was validated.
They only need to know about {project_name}.
At the end of the authentication process, {project_name} issues its token to client applications. Client applications are separate from the external identity providers, so they cannot see the client application's protocol or how they validate the user's identity. The provider only needs to know about {project_name}.

94
server_admin/topics/identity-broker/saml.adoc
View file

@ -3,78 +3,74 @@
{project_name} can broker identity providers based on the SAML v2.0 protocol.
To begin configuring an SAML v2.0 provider, go to the `Identity Providers` left menu item
and select `SAML v2.0` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Procedure
. Click *Identity Providers* in the menu.
. From the `Add provider` list, select `SAML v2.0`.
+
.Add Identity Provider
image:{project_images}/saml-add-identity-provider.png[]
The initial configuration options on this page are described in <<_general-idp-config, General IDP Configuration>>.
You must define the SAML configuration options as well. They basically describe the SAML IDP you are communicating with.
image:{project_images}/saml-add-identity-provider.png[Add Identity Provider]
+
. Enter your initial configuration options. See <<_general-idp-config, General IDP Configuration>> for more information about configuration options.
.SAML Config
|===
|Configuration|Description
|Service Provider Entity ID
|This is a required field and specifies the SAML Entity ID that the remote Identity Provider will use to identify requests coming from this Service Provider. By default it is set to the realm base URL `<root>/auth/realms/{realm-name}`.
|The SAML Entity ID that the remote Identity Provider uses to identify requests from this Service Provider. By default, this setting is set to the realms base URL `<root>/auth/realms/{realm-name}`.
|Single Sign-On Service URL
|This is a required field and specifies the SAML endpoint to start the authentication process. If your SAML IDP publishes an IDP entity descriptor, the value of
this field will be specified there.
|The SAML endpoint that starts the authentication process. If your SAML IDP publishes an IDP entity descriptor, the value of this field is specified there.
|Single Logout Service URL
|This is an optional field that specifies the SAML logout endpoint. If your SAML IDP publishes an IDP entity descriptor, the value of
this field will be specified there.
|The SAML logout endpoint. If your SAML IDP publishes an IDP entity descriptor, the value of this field is specified there.
|Backchannel Logout
|Enable if your SAML IDP supports backchannel logout.
|Toggle this switch to *ON* if your SAML IDP supports back channel logout.
|NameID Policy Format
|Specifies the URI reference corresponding to a name identifier format. Defaults to `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`.
|The URI reference corresponding to a name identifier format. By default, {project_name} sets it to `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`.
|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 Principal is set to either "Attribute [Name]" or "Attribute [Friendly Name]", this field will specify the name or the friendly name of the identifying attribute, respectively.
|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.
|Allow create
|Allow the external identity provider to create a new identifier to represent the principal.
|HTTP-POST Binding Response
|When this realm responds to any SAML requests sent by the external IDP, which SAML binding should be used? If set to `off`, then the Redirect Binding will be used.
|Controls the SAML binding in response to any SAML requests sent by an external IDP. When *OFF*, {project_name} uses Redirect Binding.
|HTTP-POST Binding for AuthnRequest
|When this realm requests authentication from the external SAML IDP, which SAML binding should be used? If set to `off`, then the Redirect Binding will be used.
|Controls the SAML binding when requesting authentication from an external IDP. When *OFF*, {project_name} uses Redirect Binding.
|Want AuthnRequests Signed
|If true, it will use the realm's keypair to sign requests sent to the external SAML IDP.
|When *ON*, {project_name} uses the realm's keypair to sign requests sent to the external SAML IDP.
|Signature Algorithm
|If `Want AuthnRequests Signed` is on, then you can also pick the signature algorithm to use.
|If *Want AuthnRequests Signed* is *ON*, the signature algorithm to use.
|SAML Signature Key Name
|Signed SAML documents sent via POST binding contain identification of signing key in `KeyName`
element. This by default contains {project_name} key ID. However various external SAML IDPs might
expect a different key name or no key name at all. This switch controls whether `KeyName`
contains key ID (option `KEY_ID`), subject from certificate corresponding to the realm key
(option `CERT_SUBJECT` - expected for instance by Microsoft Active Directory Federation
Services), or that the key name hint is completely omitted from the SAML message (option `NONE`).
|Signed SAML documents sent using POST binding contain the identification of signing key in `KeyName` element, which, by default, contains the {project_name} key ID. External SAML IDPs can expect a different key name. This switch controls whether `KeyName` contains:
* `KEY_ID` - Key ID.
* `CERT_SUBJECT` - the subject from the certificate corresponding to the realm key. Microsoft Active Directory Federation Services expect `CERT_SUBJECT`.
* `NONE` - {project_name} omits the key name hint from the SAML message.
|Force Authentication
|Indicates that the user will be forced to enter their credentials at the external IDP even if they are already logged in.
|The user must enter their credentials at the external IDP even when the user is already logged in.
|Validate Signature
|Whether or not the realm should expect that SAML requests and responses from the external IDP to be digitally signed. It is highly recommended you turn this on!
|When *ON*, the realm expects SAML requests and responses from the external IDP to be digitally signed.
|Validating X509 Certificate
|The public certificate that will be used to validate the signatures of SAML requests and responses from the external IDP.
|The public certificate {project_name} uses to validate the signatures of SAML requests and responses from the external IDP.
|Sign Service Provider Metadata
|If true, it will use the realm's keypair to sign the <<_identity_broker_saml_sp_descriptor, SAML Service Provider Metadata descriptor>>.
|When *ON*, {project_name} uses the realm's key pair to sign the <<_identity_broker_saml_sp_descriptor, SAML Service Provider Metadata descriptor>>.
|Pass subject
<<<<<<< HEAD
|Whether or not a `login_hint` query parameter should be forwarded to the IDP. When provided, this login_hint parameter is added to AuthnRequest's Subject. This allows destination providers to prefill their login form. When no login_hint is provided, nothing is forwarded as an AuthnRequest Subject.
|Attribute Consuming Service Index
@ -82,61 +78,57 @@ You must define the SAML configuration options as well. They basically describe
|Attribute Consuming Service Name
|A descriptive name for the set of attributes that are advertised in the autogenerated SP metadata document.
=======
|Controls if {project_name} forwards a `login_hint` query parameter to the IDP. {project_name} adds this field's value to the login_hint parameter in the AuthnRequest's Subject so destination providers can pre-fill their login form.
>>>>>>> 6f455950... KEYCLOAK-15756 Initial wording (#58)
|===
You can also import all this configuration data by providing a URL or file that points to the SAML IDP entity descriptor of the external IDP.
If you are connecting to a {project_name} external IDP, you can import the IDP settings from the URL `<root>/auth/realms/{realm-name}/protocol/saml/descriptor`.
This link is an XML document describing metadata about the IDP.
You can also import all this configuration data by providing a URL or XML file that points to the entity descriptor of the external SAML IDP you want to connect to.
You can import all configuration data by providing a URL or a file pointing to the SAML IDP entity descriptor of the external IDP. If you are connecting to a {project_name} external IDP, you can import the IDP settings from the URL `<root>/auth/realms/{realm-name}/protocol/saml/descriptor`. This link is an XML document describing metadata about the IDP. You can also import all this configuration data by providing a URL or XML file pointing to the external SAML IDP's entity descriptor to connect to.
[[_identity_broker_saml_requested_authncontext]]
==== Requesting specific AuthnContexts
Some Identity Providers let the clients specify particular constraints on the authentication method used to verify the user identity (such as asking for MFA, Kerberos authentication, security requirements, and so on). These constraints are specified using particular AuthnContext criteria. A client can ask for one or more criteria and also specify how the Identity Provider should match the requested AuthnContext - exactly, or by satisfying same-or-better equivalents.
Identity Providers facilitate clients specifying constraints on the authentication method verifying the user identity. For example, asking for MFA, Kerberos authentication, or security requirements. These constraints use particular AuthnContext criteria. A client can ask for one or more criteria and specify how the Identity Provider must match the requested AuthnContext, exactly, or by satisfying other equivalents.
You can list the criteria your Service Provider requires by adding one or more ClassRef or DeclRef in the Requested AuthnContext Constraints section. Usually you need to provide either ClassRefs or DeclRefs; you should check with your Identity Provider documentation which values are supported. If no ClassRefs or DeclRefs are present, the Identity Provider will not enforce additional constraints.
You can list the criteria your Service Provider requires by adding ClassRefs or DeclRefs in the Requested AuthnContext Constraints section. Usually, you need to provide either ClassRefs or DeclRefs, so check with your Identity Provider documentation which values are supported. If no ClassRefs or DeclRefs are present, the Identity Provider does not enforce additional constraints.
.Requested AuthnContext Constraints
|===
|Configuration|Description
|Comparison
|The comparison method the Identity Provider should use to evaluate the context requirements. Available values are `Exact`, `Minimum`, `Maximum` or `Better`. Default value is `Exact`.
|The method the Identity Provider uses to evaluate the context requirements. The available values are `Exact`, `Minimum`, `Maximum`, or `Better`. The default value is `Exact`.
|AuthnContext ClassRefs
|One or more AuthnContext ClassRefs that describe the required criteria.
|The AuthnContext ClassRefs describing the required criteria.
|AuthnContext DeclRefs
|One or more AuthnContext DeclRefs that describe the required criteria.
|The AuthnContext DeclRefs describing the required criteria.
|===
[[_identity_broker_saml_sp_descriptor]]
==== SP Descriptor
If you need to access the provider's SAML SP metadata, look for the `Endpoints` item in the identity provider configuration settings. It contains a link called
`SAML 2.0 Service Provider Metadata` that generates the SAML entity descriptor for the Service Provider. You can either download it or copy its URL and then import it in the remote Identity Provider.
When you access the provider's SAML SP metadata, look for the `Endpoints` item in the identity provider configuration settings. It contains a `SAML 2.0 Service Provider Metadata` link which generates the SAML entity descriptor for the Service Provider. You can download the descriptor or copy its URL and then import it into the remote Identity Provider.
This metadata is also available publicly by going to the URL:
This metadata is also available publicly by going to the following URL:
[source]
----
http[s]://{host:port}/auth/realms/{realm-name}/broker/{broker-alias}/endpoint/descriptor
----
Make sure to save any configuration changes before accessing the descriptor or they will not be reflected in the metadata.
Ensure you save any configuration changes before accessing the descriptor.
[[_identity_broker_saml_login_hint]]
==== Send Subject in SAML requests
By default, a social button pointing to a SAML Identity Provider redirects the user to a login URL:
By default, a social button pointing to a SAML Identity Provider redirects the user to the following login URL:
[source]
----
http[s]://{host:port}/auth/realms/${realm-name}/broker/{broker-alias}/login
----
Adding a query parameter named `login_hint` to this URL will add its value to SAML request as a Subject attribute. When this query parameter is absent or left empty, no subject will be added to the request.
Adding a query parameter named `login_hint` to this URL adds the parameter's value to SAML request as a Subject attribute. If this query parameter is empty, {project_name} does not add a subject to the request.
"Pass subject" option must be enabled.
Enable the "Pass subject" option to send the subject in SAML requests.

9
server_admin/topics/identity-broker/session-data.adoc
View file

@ -1,15 +1,12 @@
=== Available User Session Data
After a user logs in from the external IDP, there is some additional user session note data that {project_name} stores that you can access.
This data can be propagated to the client requesting a login via the token or SAML assertion being passed back to it by using an appropriate client mapper.
After a user login from an external IDP, {project_name} stores user session note data that you can access. This data can be propagated to the client requesting log in using the token or SAML assertion passed back to the client using an appropriate client mapper.
identity_provider::
This is the IDP alias of the broker used to perform the login.
The IDP alias of the broker used to perform the login.
identity_provider_identity::
This is the IDP username of the currently authenticated user. This is often the same as the {project_name} username, but doesn't necessarily needs to be.
For example {project_name} user `john` can be linked to the Facebook user `john123@gmail.com`, so in that case value of user session note will be `john123@gmail.com` .
The IDP username of the currently authenticated user. Often, but not always, the same as the {project_name} username. For example, {project_name} can link a user john` to a Facebook user `john123@gmail.com`. In that case, the value of the user session note is `john123@gmail.com`.
You can use a <<_protocol-mappers, Protocol Mapper>> of type `User Session Note` to propagate this information to your clients.

6
server_admin/topics/identity-broker/social-login.adoc
View file

@ -1,8 +1,4 @@
=== Social Identity Providers
For Internet facing applications, it is quite burdensome for users to have to register at your site to obtain access.
It requires them to remember yet another username and password combination. Social identity providers allow you to delegate
authentication to a semi-trusted and respected entity where the user probably already has an account.
{project_name} provides built-in support for the most common social networks out there, such as Google, Facebook, Twitter, GitHub, LinkedIn, Microsoft and Stack Overflow.
A social identity provider can delegate authentication to a trusted, respected social media account. {project_name} includes support for social networks such as Google, Facebook, Twitter, GitHub, LinkedIn, Microsoft, and Stack Overflow.

44
server_admin/topics/identity-broker/social/bitbucket.adoc
View file

@ -1,34 +1,20 @@
==== Bitbucket
There are a number of steps you have to complete to be able to enable login with Bitbucket.
First, open the `Identity Providers` left menu item and select `Bitbucket` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
To log in with Bitbucket, perform the following procedure.
.Procedure
. Click *Identity Providers* in the menu.
. From the `Add provider` list, select `Bitbucket`.
+
.Add Identity Provider
image:{project_images}/bitbucket-add-identity-provider.png[]
Before you can click `Save`, you must obtain a `Client ID` and `Client Secret` from Bitbucket.
NOTE: You will use the `Redirect URI` from this page in a later step, which you will provide to Bitbucket when you register {project_name} as a client there.
.Add a New App
To enable login with Bitbucket you must first register an application project in
https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/[OAuth on Bitbucket Cloud].
NOTE: Bitbucket often changes the look and feel of application registration, so what you see on the Bitbucket site may differ. If in doubt, see the Bitbucket documentation.
image:images/bitbucket-developer-applications.png[]
Click the `Add consumer` button.
.Register App
image:images/bitbucket-register-app.png[]
Copy the `Redirect URI` from the {project_name} `Add Identity Provider` page and enter it into the Callback URL field on the Bitbucket Add OAuth Consumer page.
On the same page, mark the `Email` and `Read` boxes under `Account` to allow your application to read user email.
.Bitbucket App Page
image:images/bitbucket-app-page.png[]
When you are done registering, click `Save`. This will open the application management page in Bitbucket. Find the client ID and secret from this page so you can enter them into the {project_name} `Add identity provider` page. Click `Save`.
image:{project_images}/bitbucket-add-identity-provider.png[Add Identity Provider]
+
. Copy the value of *Redirect URI* to your clipboard.
. In a separate browser tab, perform the https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/[OAuth on Bitbucket Cloud] process. When you click *Add Consumer*:
.. Paste the value of *Redirect URI* into the *Callback URL* field.
.. Ensure you select *Email* and *Read* in the *Account* section to permit your application to read email.
. Note the `Key` and `Secret` values Bitbucket displays when you create your consumer.
. In {project_name}, paste the value of the `Key` into the *Client ID* field.
. In {project_name}, paste the value of the `Secret` into the *Client Secret* field.
. Click *Save*.

63
server_admin/topics/identity-broker/social/facebook.adoc
View file

@ -2,54 +2,19 @@
[[_facebook]]
==== Facebook
There are a number of steps you have to complete to be able to enable login with Facebook. First, go to the `Identity Providers` left menu item
and select `Facebook` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Procedure
. Click *Identity Providers* in the menu.
. From the `Add provider` list, select `Facebook`. {project_name} displays the configuration page for the Facebook identity provider.
+
.Add Identity Provider
image:{project_images}/facebook-add-identity-provider.png[]
image:{project_images}/facebook-add-identity-provider.png[Add Identity Provider]
. Copy the value of *Redirect URI* to your clipboard.
. In a separate browser tab, follow the https://developers.facebook.com/docs/development/[Facebook Developer Guide's] instructions to create a project and client in Facebook.
.. Ensure your app is a website-type app.
.. Enter the *Redirect URI's* value into the `Site URL` of the Facebook `Website` settings block.
.. Ensure the app is public.
+
. Enter the https://developers.facebook.com/docs/facebook-login/access-tokens/[`Client ID` and `Client Secret`] values from your Facebook app into the `Client ID` and `Client Secret` fields in {project_name}.
. Enter the required scopes into the *Default Scopes* field. By default, {project_name} uses the `email` scope. See https://developers.facebook.com/docs/graph-api[Graph API] for more information about Facebook scopes.
You can't click save yet, as you'll need to obtain a `Client ID` and `Client Secret` from Facebook. One piece of data you'll need from this
page is the `Redirect URI`. You'll have to provide that to Facebook when you register {project_name} as a client there, so
copy this URI to your clipboard.
To enable login with Facebook you first have to create a project and a client in the https://developers.facebook.com/[Facebook Developer Console].
NOTE: Facebook often changes the look and feel of the Facebook Developer Console, so these directions might not always be up to date and the
configuration steps might be slightly different.
Once you've logged into the console there is a pull down menu in the top right corner of the screen that says `My Apps`. Select the `Add a New App`
menu item.
.Add a New App
image:images/facebook-add-new-app.png[]
Select the `Website` icon. Click the `Skip and Create App ID` button.
.Create a New App ID
image:images/facebook-create-app-id.png[]
The email address and app category are required fields. Once you're done with that, you will be brought to the dashboard
for the application. Click the `Settings` left menu item.
.Create a New App ID
image:images/facebook-app-settings.png[]
Click on the `+ Add Platform` button at the end of this page and select the `Website` icon. Copy and paste the `Redirect URI` from the
{project_name} `Add identity provider` page into the `Site URL` of the Facebook `Website` settings block.
.Specify Website
image:images/facebook-app-settings-website.png[]
After this it is necessary to make the Facebook app public. Click `App Review` left menu item and switch button to "Yes".
You will need also to obtain the App ID and App Secret from this page so you can enter them into the {project_name} `Add identity provider` page. To obtain this click on the `Dashboard` left menu item and click on `Show` under `App Secret`. Go back to {project_name} and specify those items and finally save your Facebook Identity Provider.
One config option to note on the `Add identity provider` page for Facebook is the `Default Scopes` field.
This field allows you to manually specify the scopes that users must authorize when authenticating with this provider.
For a complete list of scopes, please take a look at https://developers.facebook.com/docs/graph-api. By default, {project_name}
uses the following scopes: `email`.
Another thing to note is that {project_name} sends a profile request to `graph.facebook.com/me?fields=id,name,email,first_name,last_name` by default, and the response only contains the specified fields.
If you want to fetch additional fields (e.g. birthday) from the Facebook profile then you have to add a corresponding scope as described in a paragraph above and add the field name in `Additional user's profile fields` configuration option field.
You can discover available field names and corresponding scopes by exploring the https://developers.facebook.com/tools/explorer[Facebook GraphQL API Explorer].
{project_name} sends profile requests to `graph.facebook.com/me?fields=id,name,email,first_name,last_name` by default. The response contains the id, name, email, first_name, and last_name fields only. To fetch additional fields from the Facebook profile, add a corresponding scope and add the field name in the `Additional user's profile fields` configuration option field.

46
server_admin/topics/identity-broker/social/github.adoc
View file

@ -3,37 +3,19 @@
==== GitHub
There are a number of steps you have to complete to be able to enable login with GitHub. First, go to the `Identity Providers` left menu item
and select `GitHub` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
To log in with Github, perform the following procedure.
.Procedure
. Click *Identity Providers* in the menu.
. From the `Add provider` list, select `Github`.
+
.Add Identity Provider
image:{project_images}/github-add-identity-provider.png[]
You can't click save yet, as you'll need to obtain a `Client ID` and `Client Secret` from GitHub. One piece of data you'll need from this
page is the `Redirect URI`. You'll have to provide that to GitHub when you register {project_name} as a client there, so
copy this URI to your clipboard.
To enable login with GitHub you first have to register an application project in
https://github.com/settings/developers[GitHub Developer applications].
NOTE: GitHub often changes the look and feel of application registration, so these directions might not always be up to date and the
configuration steps might be slightly different.
.Add a New App
image:images/github-developer-applications.png[]
Click the `Register a new application` button.
.Register App
image:images/github-register-app.png[]
You'll have to copy the `Redirect URI` from the {project_name} `Add Identity Provider` page and enter it into the
`Authorization callback URL` field on the GitHub `Register a new OAuth application` page. Once you've completed this
page you will be brought to the application's management page.
.GitHub App Page
image:images/github-app-page.png[]
You will need to obtain the client ID and secret from this page so you can enter them into the {project_name} `Add identity provider` page.
Go back to {project_name} and specify those items.
image:{project_images}/github-add-identity-provider.png[Add Identity Provider]
+
. Copy the value of *Redirect URI* to your clipboard.
. In a separate browser tab, https://docs.github.com/en/developers/apps/creating-an-oauth-app[create an OAUTH app].
.. Enter the value of *Redirect URI* into the `Authorization callback URL` field when creating the app.
.. Note the Client ID and Client secret on the management page of your OAUTH app.
. In {project_name}, paste the value of the `Client ID` into the *Client ID* field.
. In {project_name}, paste the value of the `Client Secret` into the *Client Secret* field.
. Click *Save*.

39
server_admin/topics/identity-broker/social/gitlab.adoc
View file

@ -1,30 +1,17 @@
==== GitLab
There are a number of steps you have to complete to be able to enable login with GitLab.
First, go to the `Identity Providers` left menu item and select `GitLab` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Procedure
. Click *Identity Providers* in the menu.
. From the `Add provider` list, select `GitLab`.
+
.Add Identity Provider
image:{project_images}/gitlab-add-identity-provider.png[]
Before you can click `Save`, you must obtain a `Client ID` and `Client Secret` from GitLab.
NOTE: You will use the `Redirect URI` from this page in a later step, which you will provide to GitLab when you register {project_name} as a client there.
To enable login with GitLab you first have to register an application in
https://docs.gitlab.com/ee/integration/oauth_provider.html[GitLab as OAuth2 authentication service provider].
NOTE: GitLab often changes the look and feel of application registration, so what you see on the GitLab site may differ. If in doubt, see the GitLab documentation.
.Add a New App
image:images/gitlab-developer-applications.png[]
Copy the `Redirect URI` from the {project_name} `Add Identity Provider` page and enter it into the Redirect URI field on the GitLab Add new application page.
.GitLab App Page
image:images/gitlab-app-page.png[]
When you are done registering, click `Save application`. This will open the application management page in GitLab. Find the client ID and secret from this page so you can enter them into the {project_name} `Add identity provider` page.
To finish, return to {project_name} and enter them. Click `Save`.
image:{project_images}/github-add-identity-provider.png[Add Identity Provider]
+
. Copy the value of *Redirect URI* to your clipboard.
. In a separate browser tab, https://docs.gitlab.com/ee/integration/oauth_provider.html[add a new GitLab application].
.. Use the *Redirect URI* in your clipboard as the *Redirect URI*.
.. Note the `Client ID` and `Client Secret` when you save the application.
. In {project_name}, paste the value of the `Client ID` into the *Client ID* field.
. In {project_name}, paste the value of the `Client Secret` into the *Client Secret* field.
. Click *Save*.

87
server_admin/topics/identity-broker/social/google.adoc
View file

@ -2,72 +2,23 @@
[[_google]]
==== Google
There are a number of steps you have to complete to be able to enable login with Google. First, go to the `Identity Providers` left menu item
and select `Google` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Procedure
. Click *Identity Providers* in the menu.
. From the `Add provider` list, select `Google`.
+
.Add Identity Provider
image:{project_images}/google-add-identity-provider.png[]
You can't click save yet, as you'll need to obtain a `Client ID` and `Client Secret` from Google. One piece of data you'll need from this
page is the `Redirect URI`. You'll have to provide that to Google when you register {project_name} as a client there, so
copy this URI to your clipboard.
To enable login with Google you first have to create a project and a client in the https://console.cloud.google.com/project[Google Developer Console].
Then you need to copy the client ID and secret into the {project_name} Admin Console.
NOTE: Google often changes the look and feel of the Google Developer Console, so these directions might not always be up to date and the
configuration steps might be slightly different.
Let's see first how to create a project with Google.
Log in to the link:https://console.cloud.google.com/project[Google Developer Console].
.Google Developer Console
image:images/google-developer-console.png[]
Click the `Create Project` button.
Use any value for `Project name` and `Project ID` you want, then click the `Create` button.
Wait for the project to be created (this may take a while). Once created you will be brought to the project's dashboard.
.Dashboard
image:images/google-dashboard.png[]
Then navigate to the `APIs & Services` section in the Google Developer Console. On that screen, navigate to `Credentials` administration.
When users log into Google from {project_name} they will see a consent screen from Google which will ask the user
if {project_name} is allowed to view information about their user profile. Thus Google requires some basic information about the product before creating any secrets for it. For a new project, you have first to configure `OAuth consent screen`.
For the very basic setup, filling in the Application name is sufficient. You can also set additional details like scopes for Google APIs in this page.
.Fill in OAuth consent screen details
image:images/google-oauth-consent-screen.png[]
The next step is to create OAuth client ID and client secret. Back in `Credentials` administration, navigate to `Credentials` tab and select `OAuth client ID` under the `Create credentials` button.
.Create credentials
image:images/google-create-credentials.png[]
You will then be brought to the `Create OAuth client ID` page. Select `Web application` as the application type. Specify the name you want for your client. You'll also need to
copy and paste the `Redirect URI` from the {project_name} `Add Identity Provider` page into the
`Authorized redirect URIs` field. After you do this, click the `Create` button.
.Create OAuth client ID
image:images/google-create-oauth-id.png[]
After you click `Create` you will be brought to the `Credentials` page. Click on your new OAuth 2.0 Client ID to view
the settings of your new Google Client.
.Google Client Credentials
image:images/google-client-credentials.png[]
You will need to obtain the client ID and secret from this page so you can enter them into the {project_name} `Add identity provider` page.
Go back to {project_name} and specify those items.
One config option to note on the `Add identity provider` page for Google is the `Default Scopes` field.
This field allows you to manually specify the scopes that users must authorize when authenticating with this provider.
For a complete list of scopes, please take a look at https://developers.google.com/oauthplayground/ . By default, {project_name}
uses the following scopes: `openid` `profile` `email`.
If your organization uses the G Suite and you want to restrict access to only members of your organization,
you must enter the domain that is used for the G Suite into the `Hosted Domain` field to enable it.
image:{project_images}/google-add-identity-provider.png[Add Identity Provider]
+
. In a separate browser tab, https://support.google.com/googleapi/answer/6251787[create a google project].
. In the Google dashboard for your Google app, click the *OAuth consent screen* menu. Create a consent screen, ensuring that the user type of the consent screen is external.
. In the Google dashboard:
.. Click the *Credentials* menu.
.. Click *CREATE CREDENTIALS* - *OAuth Client ID*.
.. From the *Application type* list, select *Web application*.
.. Click *Create*.
.. Note *Your Client ID* and *Your Client Secret*.
. In {project_name}, paste the value of the *Your Client ID* into the *Client ID* field.
. In {project_name}, paste the value of the *Your Client Secret* into the *Client Secret* field.
. Enter the required scopes into the *Default Scopes* field. By default, {project_name} uses the following scopes: `openid` `profile` `email`. See the https://developers.google.com/oauthplayground/[OAuth Playground] for a list of Google scopes.
. To restrict access to your GSuite organization's members only, enter the G Suite domain into the `Hosted Domain` field.
. Click *Save*.

95
server_admin/topics/identity-broker/social/instagram.adoc
View file

@ -1,60 +1,59 @@
==== Instagram
There are a number of steps you have to complete to be able to enable login with Instagram. First, go to the `Identity Providers` left menu item
and select `Instagram` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Procedure
. Click *Identity Providers* in the menu.
. From the `Add provider` list, select `Instagram`. {project_name} displays the configuration page for the Instagram identity provider.
+
.Add Identity Provider
image:{project_images}/instagram-add-identity-provider.png[]
You can't click save yet, as you'll need to obtain a `Client ID` and `Client Secret` from Instagram. One piece of data you'll need from this
page is the `Redirect URI`. You'll have to provide that to Instagram when you register {project_name} as a client there, so
copy this URI to your clipboard.
To enable login with Instagram you first have to create a project and a client. Instagram API is managed through the https://developers.facebook.com/[Facebook Developer Console].
NOTE: Facebook often changes the look and feel of the Facebook Developer Console, so these directions might not always be up to date and the
configuration steps might be slightly different.
Once you've logged into the console there is a menu in the top right corner of the screen that says `My Apps`. Select the `Add a New App`
menu item.
image:{project_images}/instagram-add-identity-provider.png[Add Identity Provider]
. Copy the value of *Redirect URI* to your clipboard.
. In a separate browser tab, open the https://developers.facebook.com/[Facebook Developer Console].
.. Click *My Apps*.
.. Select *Add a New App*.
+
.Add a New App
image:images/instagram-add-new-app.png[]
Select `For Everything Else`.
image:images/instagram-add-new-app.png[Add a New App]
+
.. Select `For Everything Else`.
+
.Create a New App ID
image:images/instagram-create-app-id.png[]
Fill all required fields. Once you're done with that, you will be brought to the dashboard
for the application. In the menu in the left navigation panel select `Basic` under `Settings`.
+
.. Fill in all required fields.
.. Click *Create App*. Facebook then brings you to the dashboard.
.. In the navigation panel, select *Settings* - *Basic*.
+
.Add Platform
image:images/instagram-add-platform.png[]
Select `+ Add Platform` at the bottom and then click `[Website]` with the globe icon. Specify URL of your site.
image:images/instagram-add-platform.png[Add Platform]
+
.. Select *+ Add Platform*.
.. Click *[Website]*.
.. Enter a URL for your site.
+
.Add a Product
image:images/instagram-add-product.png[]
Select `Dashboard` from the left menu and click `Set Up` in the Instagram box. In the left menu then select `Basic Display` under `Instagram`
and click `Create New App`.
+
.. Select `Dashboard` from the menu.
.. Click *Set Up* in the Instagram box.
.. Select *Instagram* - *Basic Display* from the menu.
.. Click *Create New App*.
+
.Create a New Instagram App ID
image:images/instagram-create-instagram-app-id.png[]
Specify `Display Name`.
image:images/instagram-create-instagram-app-id.png[Create a New Instagram App ID]
+
.. Enter a value into *Display Name*.
+
.Setup the App
image:images/instagram-app-settings.png[]
Copy and paste the `Redirect URI` from the {project_name} `Add identity provider` page into the `Valid OAuth Redirect URIs` of the Instagram `Client OAuth Settings` settings block.
You can use this URL also for `Deauthorize Callback URL` and `Data Deletion Request URL`. {project_name} currently doesn't support either of them,
but the Facebook Developer Console requires both of them to be filled.
You will need also to obtain the App ID and App Secret from this page so you can enter them into the {project_name} `Add identity provider` page.
To obtain this click on `Show` under `App Secret`. Go back to {project_name} and specify those items and finally save your Instagram Identity Provider.
Now you can make the Instagram app public. Click `App Review` left menu item and then `Requests`. After that follow the instructions on screen.
image:images/instagram-app-settings.png[Setup the App]
+
.. Paste the *Redirect URL* from {project_name} into the *Valid OAuth Redirect URIs* field.
.. Paste the *Redirect URL* from {project_name} into the *Deauthorize Callback URL* field.
.. Paste the *Redirect URL* from {project_name} into the *Data Deletion Request URL* field.
.. Click *Show* in the *Instagram App Secret* field.
.. Note the *Instagram App ID* and the *Instagram App Secret*.
.. Click *App Review* - *Requests*.
.. Follow the instructions on the screen.
. In {project_name}, paste the value of the *Instagram App ID* into the *Client ID* field.
. In {project_name}, paste the value of the *Instagram App Secret* into the *Client Secret* field.
. Click *Save*.

47
server_admin/topics/identity-broker/social/linked-in.adoc
View file

@ -3,37 +3,18 @@
==== LinkedIn
There are a number of steps you have to complete to be able to enable login with LinkedIn. First, go to the `Identity Providers` left menu item
and select `LinkedIn` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Procedure
. Click *Identity Providers* in the menu.
. From the `Add provider` list, select `LinkedIn`.
+
.Add Identity Provider
image:{project_images}/linked-in-add-identity-provider.png[]
You can't click save yet, as you'll need to obtain a `Client ID` and `Client Secret` from LinkedIn. One piece of data you'll need from this
page is the `Redirect URI`. You'll have to provide that to LinkedIn when you register {project_name} as a client there, so
copy this URI to your clipboard.
To enable login with LinkedIn you first have to create an application in https://www.linkedin.com/developer/apps[LinkedIn Developer Network].
NOTE: LinkedIn may change the look and feel of application registration, so these directions may not always be up to date.
.Developer Network
image:images/linked-in-developer-network.png[]
Click on the `Create Application` button. This will bring you to the `Create a New Application` Page.
.Create App
image:images/linked-in-create-app.png[]
Fill in the form with the appropriate values, then click the `Submit` button. This will bring you to the new application's settings page.
.App Settings
image:images/linked-in-app-settings.png[]
Select `r_basicprofile` and `r_emailaddress` in the `Default Application Permissions` section.
You'll have to copy the `Redirect URI` from the {project_name} `Add Identity Provider` page and enter it into the
`OAuth 2.0` `Authorized Redirect URLs` field on the LinkedIn app settings page. Don't forget to click the `Update` button after
you do this!
You will then need to obtain the client ID and secret from this page so you can enter them into the {project_name} `Add identity provider` page.
Go back to {project_name} and specify those items.
image:{project_images}/google-add-identity-provider.png[Add Identity Provider]
+
. Copy the value of *Redirect URI* to your clipboard.
. In a separate browser tab, https://www.linkedin.com/developer/apps[create an app].
.. After you create the app, click the *Auth* tab.
.. Enter the value of *Redirect URI* into the *Authorized redirect URLs for your app* field.
.. Note *Your Client ID* and *Your Client Secret*.
. In {project_name}, paste the value of the *Client ID* into the *Client ID* field.
. In {project_name}, paste the value of the *Client Secret* into the *Client Secret* field.
. Click *Save*.

59
server_admin/topics/identity-broker/social/microsoft.adoc
View file

@ -3,50 +3,17 @@
==== Microsoft
There are a number of steps you have to complete to be able to enable login with Microsoft. First, go to the `Identity Providers` left menu item
and select `Microsoft` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Procedure
. Click *Identity Providers* in the menu.
. From the `Add provider` list, select `Microsoft`.
+
.Add Identity Provider
image:{project_images}/microsoft-add-identity-provider.png[]
You can't click save yet, as you'll need to obtain a `Client ID` and `Client Secret` from Microsoft. One piece of data you'll need from this
page is the `Redirect URI`. You'll have to provide that to Microsoft when you register {project_name} as a client there, so
copy this URI to your clipboard.
To enable login with Microsoft account you first have to register an OAuth application at Microsoft.
Go to the https://account.live.com/developers/applications/create[Microsoft Application Registration] url.
NOTE: Microsoft often changes the look and feel of application registration, so these directions might not always be up to date and the
configuration steps might be slightly different.
.Register Application
image:images/microsoft-app-register.png[]
Enter in the application name and click `Create application`. This will bring you to the application settings page of your
new application.
.Settings
image:images/microsoft-app-settings.png[]
You'll have to copy the `Redirect URI` from the {project_name} `Add Identity Provider` page and add it to the
`Redirect URIs` field on the Microsoft application page. Be sure to click the `Add Url` button and `Save` your changes.
Finally, you will need to obtain the Application ID and secret from this page so you can enter them back on the {project_name} `Add identity provider` page.
Go back to {project_name} and specify those items.
ifeval::[{project_community}==true]
WARNING: From November 2018 onwards, Microsoft is removing support for the Live SDK API in favor of the new Microsoft Graph API.
The {project_name} Microsoft identity provider has been updated to use the new endpoints so make sure to upgrade to
{project_name} version 4.6.0 or later in order to use this provider.
Furthermore, client applications registered with Microsoft under "Live SDK applications" will need to be re-registered
in the https://account.live.com/developers/applications/create[Microsoft Application Registration] portal to obtain an application id that
is compatible with the Microsoft Graph API.
endif::[]
ifeval::[{project_product}==true]
WARNING: From November 2018 onwards, Microsoft is removing support for the Live SDK API in favor of the new Microsoft Graph API.
The {project_name} Microsoft identity provider has been updated to use the new endpoints so make sure to upgrade to
{project_name} version 7.2.5 or later in order to use this provider.
Furthermore, client applications registered with Microsoft under "Live SDK applications" will need to be re-registered
in the https://account.live.com/developers/applications/create[Microsoft Application Registration] portal to obtain an application id that
is compatible with the Microsoft Graph API.
endif::[]
image:{project_images}/google-add-identity-provider.png[Add Identity Provider]
+
. Copy the value of *Redirect URI* to your clipboard.
. In a separate browser tab, https://account.live.com/developers/applications/create[create a Microsoft app].
.. Click *Add URL* to add the redirect URL to the Microsoft app.
.. Note the *Application ID* and *Application Secret*.
. In {project_name}, paste the value of the *Application ID* into the *Client ID* field.
. In {project_name}, paste the value of the *Application Secret* into the *Client Secret* field.
. Click *Save*.

95
server_admin/topics/identity-broker/social/openshift.adoc
View file

@ -1,20 +1,17 @@
==== OpenShift 3
NOTE: OpenShift Online is currently in the developer preview mode. This documentation has been based on on-premise installations and local `minishift` development environment.
There are a just a few steps you have to complete to be able to enable login with OpenShift. First, go to the `Identity Providers` left menu item
and select `OpenShift` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Procedure
. Click *Identity Providers* in the menu.
. From the `Add provider` list, select `Openshift`.
+
.Add Identity Provider
image:images/openshift-add-identity-provider.png[]
.Registering OAuth client
You can register your client using `oc` command line tool.
====
[source,bash]
image:images/openshift-add-identity-provider.png[Add Identity Provider]
+
. Copy the value of *Redirect URI* to your clipboard.
. Register your client using the `oc` command-line tool.
+
[source, subs="attributes"]
----
$ oc create -f <(echo '
kind: OAuthClient
@ -27,34 +24,40 @@ redirectURIs:
grantMethod: prompt <4>
')
----
+
<1> The `name` of your OAuth client. Passed as `client_id` request parameter when making requests to `_<openshift_master>_/oauth/authorize` and `_<openshift_master>_/oauth/token`.
<2> `secret` is used as the `client_secret` request parameter.
<3> The `redirect_uri` parameter specified in requests to `_<openshift_master>_/oauth/authorize` and `_<openshift_master>_/oauth/token` must be equal to (or prefixed by) one of the URIs in `redirectURIs`.
<4> The `grantMethod` is used to determine what action to take when this client requests tokens and has not yet been granted access by the user.
====
Use client ID and secret defined by `oc create` command to enter them back on the {project_name} `Add identity provider` page.
Go back to {project_name} and specify those items.
Please refer to https://docs.okd.io/latest/authentication/configuring-oauth-clients.html#oauth-register-additional-client_configuring-oauth-clients[official OpenShift documentation] for more detailed guides.
<2> The `secret` {project_name} uses for the `client_secret` request parameter.
<3> The `redirect_uri` parameter specified in requests to `_<openshift_master>_/oauth/authorize` and `_<openshift_master>_/oauth/token` must be equal to (or prefixed by) one of the URIs in `redirectURIs`. You can obtain this from the *Redirect URI* field in the Identity Provider screen
<4> The `grantMethod` {project_name} uses to determine the action when this client requests tokens but has not been granted access by the user.
+
. In {project_name}, paste the value of the *Client ID* into the *Client ID* field.
. In {project_name}, paste the value of the *Client Secret* into the *Client Secret* field.
. Click *Save*.
==== OpenShift 4
NOTE: Prior to configuring OpenShift 4 Identity Provider, please locate the correct OpenShift 4 API URL up.
In some scenarios, that URL might be hidden from users. The easiest way to obtain it is to invoke the following command (this might require installing `jq` command separately) `curl -s -k -H "Authorization: Bearer $(oc whoami -t)" \https://<openshift-user-facing-api-url>/apis/config.openshift.io/v1/infrastructures/cluster | jq ".status.apiServerURL"`. In most cases, the address will be protected by HTTPS. Therefore, it is essential to configure `X509_CA_BUNDLE` in the container and set it to `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`. Otherwise, {project_name} won't be able to communicate
with the API Server.
There are a just a few steps you have to complete to be able to enable login with OpenShift 4. First, go to the `Identity Providers` left menu item and select `OpenShift v4` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Prerequisites
. Installation of https://stedolan.github.io/jq/[jq].
. `X509_CA_BUNDLE` configured in the container and set to `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`.
.Procedure
. Run the following command on the command line and note the OpenShift 4 API URL output.
+
[source, subs="attributes"]
----
curl -s -k -H "Authorization: Bearer $(oc whoami -t)" \https://<openshift-user-facing-api-url>/apis/config.openshift.io/v1/infrastructures/cluster | jq ".status.apiServerURL"
----
+
. Click *Identity Providers* in the {project_name} menu.
. From the `Add provider` list, select `Openshift`.
+
.Add Identity Provider
image:images/openshift-4-add-identity-provider.png[]
.Registering OAuth client
You can register your client using `oc` command line tool.
====
[source,bash]
image:images/openshift-4-add-identity-provider.png[Add Identity Provider]
+
. Copy the value of *Redirect URI* to your clipboard.
. Register your client using the `oc` command-line tool.
+
[source, subs="attributes"]
----
$ oc create -f <(echo '
kind: OAuthClient
@ -67,18 +70,14 @@ redirectURIs:
grantMethod: prompt <4>
')
----
<1> The `name` of your OAuth client. Passed as `client_id` request parameter when making requests to `_<openshift_master>_/oauth/authorize` and `_<openshift_master>_/oauth/token`. The `name` parameter needs to be the same
in `OAuthClient` object as well as in {project_name} configuration.
<2> `secret` is used as the `client_secret` request parameter.
<3> The `redirect_uri` parameter specified in requests to `_<openshift_master>_/oauth/authorize` and `_<openshift_master>_/oauth/token` must be equal to (or prefixed by) one of the URIs in `redirectURIs`. The easiest way to configure it correctly is to copy-paste
it from {project_name} OpenShift 4 Identity Provider configuration page (`Redirect URI` field).
<4> The `grantMethod` is used to determine what action to take when this client requests tokens and has not yet been granted access by the user.
====
Use the client ID and secret defined by `oc create` command to enter them back on the {project_name} `Add identity provider` page.
Go back to {project_name} and specify those items.
<1> The `name` of your OAuth client. Passed as `client_id` request parameter when making requests to `_<openshift_master>_/oauth/authorize` and `_<openshift_master>_/oauth/token`. The `name` parameter must be the same in the `OAuthClient` object and the {project_name} configuration.
<2> The `secret` {project_name} uses as the `client_secret` request parameter.
<3> The `redirect_uri` parameter specified in requests to `_<openshift_master>_/oauth/authorize` and `_<openshift_master>_/oauth/token` must be equal to (or prefixed by) one of the URIs in `redirectURIs`. The easiest way to configure it correctly is to copy-paste it from {project_name} OpenShift 4 Identity Provider configuration page (`Redirect URI` field).
<4> The `grantMethod` {project_name} uses to determine the action when this client requests tokens but has not been granted access by the user.
+
. In {project_name}, paste the value of the *Client ID* into the *Client ID* field.
. In {project_name}, paste the value of the *Client Secret* into the *Client Secret* field.
. Click *Save*.
TIP: The OpenShift API server returns `The client is not authorized to request a token using this method` whenever `OAuthClient`
`name`, `secret` or `redirectURIs` is incorrect. Make sure you copy-pasted them into {project_name} OpenShift 4 Identity Provider page correctly.
Please refer to https://docs.okd.io/latest/authentication/configuring-oauth-clients.html#oauth-register-additional-client_configuring-oauth-clients[official OpenShift documentation] for more detailed guides.
See https://docs.okd.io/latest/authentication/configuring-oauth-clients.html#oauth-register-additional-client_configuring-oauth-clients[official OpenShift documentation] for more information.

47
server_admin/topics/identity-broker/social/paypal.adoc
View file

@ -1,36 +1,19 @@
==== PayPal
There are a number of steps you have to complete to be able to enable login with PayPal. First, go to the `Identity Providers` left menu item
and select `PayPal` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Procedure
. Click *Identity Providers* in the menu.
. From the `Add provider` list, select `PayPal`.
+
.Add Identity Provider
image:{project_images}/paypal-add-identity-provider.png[]
You can't click save yet, as you'll need to obtain a `Client ID` and `Client Secret` from PayPal. One piece of data you'll need from this
page is the `Redirect URI`. You'll have to provide that to PayPal when you register {project_name} as a client there, so
copy this URI to your clipboard.
To enable login with PayPal you first have to register an application project in
https://developer.paypal.com/developer/applications[PayPal Developer applications].
.Add a New App
image:images/paypal-developer-applications.png[]
Click the `Create App` button.
.Register App
image:images/paypal-register-app.png[]
You will now be brought to the app settings page.
.Do the following changes
- Choose to configure either Sandbox or Live (choose Live if you haven't enabled the `Target Sandbox` switch on the `Add identity provider` page)
- Copy Client ID and Secret so you can paste them into the {project_name} `Add identity provider` page.
- Scroll down to `App Settings`
- Copy the `Redirect URI` from the {project_name} `Add Identity Provider` page and enter it into the `Return URL` field.
- Check the `Log In with PayPal` checkbox.
- Check the `Full name` checkbox under the personal information section.
- Check the `Email address` checkbox under the address information section.
- Add both a privacy and a user agreement URL pointing to the respective pages on your domain.
image:{project_images}/google-add-identity-provider.png[Add Identity Provider]
+
. Copy the value of *Redirect URI* to your clipboard.
. In a separate browser tab, open the https://developer.paypal.com/developer/applications[PayPal Developer applications area].
.. Click *Create App* to create a PayPal app.
.. Note the Client ID and Client Secret. Click the *Show* link to view the secret.
.. Ensure *Connect with PayPal* is checked.
.. Set the value of the *Return URL* field to the value of *Redirect URI* from {project_name}.
. In {project_name}, paste the value of the *Client ID* into the *Client ID* field.
. In {project_name}, paste the value of the *Client Secret* into the *Client Secret* field.
. Click *Save*.

40
server_admin/topics/identity-broker/social/stack-overflow.adoc
View file

@ -3,26 +3,26 @@
==== Stack Overflow
There are a number of steps you have to complete to be able to enable login with Stack Overflow. First, go to the `Identity Providers` left menu item
and select `Stack Overflow` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Procedure
. Click *Identity Providers* in the menu.
. From the `Add provider` list, select `Stack Overflow`.
+
.Add Identity Provider
image:{project_images}/stack-overflow-add-identity-provider.png[]
To enable login with Stack Overflow you first have to register an OAuth application on https://stackapps.com/[StackApps].
Go to https://stackapps.com/apps/oauth/register[registering your application on Stack Apps] URL and login.
NOTE: Stack Overflow often changes the look and feel of application registration, so these directions might not always be up to date and the
configuration steps might be slightly different.
image:{project_images}/google-add-identity-provider.png[Add Identity Provider]
+
. In a separate browser tab, log into https://stackapps.com/apps/oauth/register[registering your application on Stack Apps].
+
.Register Application
image:images/stack-overflow-app-register.png[]
Enter in the application name and the OAuth Domain Name of your application and click `Register your Application`. Type in anything you want
for the other items.
image:images/stack-overflow-app-register.png[Register Application]
+
.. Enter your application name into the *Application Name* field.
.. Enter the OAuth domain into the *OAuth Domain* field.
.. Click *Register Your Application*.
+
.Settings
image:images/stack-overflow-app-settings.png[]
Finally, you will need to obtain the client ID, secret, and key from this page so you can enter them back on the {project_name} `Add identity provider` page.
Go back to {project_name} and specify those items.
image:images/stack-overflow-app-settings.png[Settings]
+
. Note the *Client ID* and *Client Secret*.
. In {project_name}, paste the value of the *Client ID* into the *Client ID* field.
. In {project_name}, paste the value of the *Client Secret* into the *Client Secret* field.
. Click *Save*.

54
server_admin/topics/identity-broker/social/twitter.adoc
View file

@ -3,42 +3,22 @@
==== Twitter
There are a number of steps you have to complete to be able to enable login with Twitter. First, go to the `Identity Providers` left menu item
and select `Twitter` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Prerequisites
. A Twitter developer account.
.Procedure
. Click *Identity Providers* in the menu.
. From the `Add provider` list, select `Twitter`.
+
.Add Identity Provider
image:{project_images}/twitter-add-identity-provider.png[]
You can't click save yet, as you'll need to obtain a `Client ID` and `Client Secret` from Twitter. One piece of data you'll need from this
page is the `Redirect URI`. You'll have to provide that to Twitter when you register {project_name} as a client there, so
copy this URI to your clipboard.
To enable login with Twtter you first have to create an application in the https://developer.twitter.com/apps/[Twitter Application Management].
.Register Application
image:images/twitter-app-register.png[]
Click on the `Create New App` button. This will bring you to the `Create an Application` page.
.Register Application
image:images/twitter-app-create.png[]
Enter in a Name and Description. The Website can be anything, but cannot have a `localhost` address. For the
`Callback URL` you must copy the `Redirect URI` from the {project_name} `Add Identity Provider` page.
WARNING: You cannot use `localhost` in the `Callback URL`. Instead replace it with `127.0.0.1` if you are trying to test drive Twitter login on your laptop.
After clicking save you will be brought to the `Details` page.
.App Details
image:images/twitter-details.png[]
Next go to the `Keys and Access Tokens` tab.
.Keys and Access Tokens
image:images/twitter-keys.png[]
Finally, you will need to obtain the API Key and secret from this page and copy them back into the `Client ID` and `Client Secret` fields on the {project_name} `Add identity provider` page.
image:{project_images}/twitter-add-identity-provider.png[Add Identity Provider]
+
. Copy the value of *Redirect URI* to your clipboard.
. In a separate browser tab, create an app in https://developer.twitter.com/apps/[Twitter Application Management].
.. Enter any value for name and description.
.. The value for *Website* can be any valid URL except `localhost`.
.. Paste the value of the *Redirect URL* into the *Callback URL* field.
.. When you create your Twitter app, note the value of *Consumer Key* and *Consumer Secret* in the *Keys and Access Tokens* section.
. In {project_name}, paste the value of the *Consumer Key* into the *Client ID* field.
. In {project_name}, paste the value of the *Consumer Secret* into the *Client Secret* field.
. Click *Save*.

18
server_admin/topics/identity-broker/suggested.adoc
View file

@ -1,25 +1,22 @@
[[_client_suggested_idp]]
=== Client-suggested Identity Provider
OIDC applications can bypass the {project_name} login page by specifying a hint on which
identity provider they want to use.
OIDC applications can bypass the {project_name} login page by hinting at the identity provider they want to use. You can enable this by setting the `kc_idp_hint` query parameter in the Authorization Code Flow authorization endpoint.
This is done by setting the `kc_idp_hint` query parameter in the Authorization Code Flow authorization endpoint.
{project_name} OIDC client adapters also allow you to specify this query parameter when you access a secured resource
at the application.
With {project_name} OIDC client adapters, you can specify this query parameter when you access a secured resource in the application.
For example:
[source]
[source,bash,subs=+attributes]
----
GET /myapplication.com?kc_idp_hint=facebook HTTP/1.1
Host: localhost:8080
----
In this case, it is expected that your realm has an identity provider with an alias `facebook`. If this provider doesn't exist the login form will be displayed.
In this case, your realm must have an identity provider with a `facebook` alias. If this provider does not exist, the login form is displayed.
If you are using `keycloak.js` adapter, you can also achieve the same behavior:
If you are using the `keycloak.js` adapter, you can also achieve the same behavior as follows:
[source,javascript]
----
@ -30,5 +27,4 @@ keycloak.createLoginUrl({
});
----
The `kc_idp_hint` query parameter also allows the client to override the default identity provider if one is configured for the `Identity Provider Redirector` authenticator. The client can also disable the automatic redirecting by setting the `kc_idp_hint` query parameter to an empty value.
With the `kc_idp_hint` query parameter, the client can override the default identity provider if you configure one for the `Identity Provider Redirector` authenticator. The client can disable the automatic redirecting by setting the `kc_idp_hint` query parameter to an empty value.

19
server_admin/topics/identity-broker/tokens.adoc
View file

@ -1,26 +1,17 @@
=== Retrieving External IDP Tokens
{project_name} allows you to store tokens and responses from the authentication process with the external IDP.
For that, you can use the `Store Token` configuration option on the IDP's settings page.
With {project_name}, you can store tokens and responses from the authentication process with the external IDP using the `Store Token` configuration option on the IDP's settings page.
Application code can retrieve these tokens and responses to pull in extra user information, or to securely invoke requests on the external IDP.
For example, an application might want to use the Google token to invoke on other Google services and REST APIs.
To retrieve a token for a particular identity provider you need to send a request as follows:
Application code can retrieve these tokens and responses to import extra user information or to request the external IDP securely. For example, an application can use the Google token to use other Google services and REST APIs. To retrieve a token for a particular identity provider, send a request as follows:
[source]
[source, subs="attributes"]
----
GET /auth/realms/{realm}/broker/{provider_alias}/token HTTP/1.1
Host: localhost:8080
Authorization: Bearer <KEYCLOAK ACCESS TOKEN>
----
An application must have authenticated with {project_name} and have received an access token. This access token
will need to have the `broker` client-level role `read-token` set. This means that the user must have a role mapping for this role
and the client application must have that role within its scope.
In this case, given that you are accessing a protected service in {project_name}, you need to send the access token issued by {project_name} during the user authentication.
In the broker configuration page you can automatically assign this role to newly imported users by turning on the `Stored Tokens Readable` switch.
These external tokens can be re-established by either logging in again through the provider, or using the client-initiated account linking API.
An application must authenticate with {project_name} and receive an access token. This access token must have the `broker` client-level role `read-token` set, so the user must have a role mapping for this role, and the client application must have that role within its scope. In this case, since you are accessing a protected service in {project_name}, send the access token issued by {project_name} during the user authentication. You can assign this role to newly imported users in the broker configuration page by setting the *Stored Tokens Readable* switch to *ON*.
These external tokens can be re-established by logging in again through the provider or using the client-initiated account linking API.

2
server_admin/topics/users/proc-setting-password-user.adoc
View file

@ -17,7 +17,7 @@ If a user already has a password, it can be reset in the *Reset Password* sectio
. Type a new password in the *Set Password* section.
. Click *Set Password*.
+
NOTE: If *Temporary* is set to *ON*, the user must change the password at the first login. To allow users to keep the password supplied, set *Temporary* to *OFF.* The user must click *Set Password* to change the password.
NOTE: If *Temporary* is *ON*, the user must change the password at the first login. To allow users to keep the password supplied, set *Temporary* to *OFF.* The user must click *Set Password* to change the password.
+
. Alternatively, you can send an email to the user that requests the user reset the password.
.. Navigate to the *Reset Actions* list under *Credential Reset*.