broker

SUMMARY.adoc

@@ -72,10 +72,10 @@
  .. link:topics/identity-broker/oidc.adoc[OIDC Providers]
  .. link:topics/identity-broker/saml.adoc[SAML Providers]
  .. link:topics/identity-broker/suggested.adoc[Client Suggested Identity Provider]
- .. link:topics/identity-broker/mappers.adoc[Importing External Metadata]
+ .. link:topics/identity-broker/mappers.adoc[Mapping Claims and Assertions]
  .. link:topics/identity-broker/session-data.adoc[Available User Session Data]
- .. link:topics/identity-broker/session-data.adoc[Available User Session Data]
+ .. link:topics/identity-broker/first-login-flow.adoc[First Login Flow]
- .. link:topics/identity-broker/tokens.adoc[Retrieving Tokens from Identity Providers]
+ .. link:topics/identity-broker/tokens.adoc[Retrieving External IDP Tokens]
  . link:topics/cors.adoc[CORS]
  . link:topics/timeouts.adoc[Cookie settings, Session Timeouts, and Token Lifespans]
  . link:topics/events.adoc[Auditing and Events]

topics/authentication/flows.adoc

@@ -1,3 +1,4 @@
+[[_authentication-flows]]
 
 === Authentication Flows
 

topics/clients/protocol-mappers.adoc

@@ -1,4 +1,4 @@
-[[_mappers]]
+[[_protocol-mappers]]
 
 === OIDC Token and SAML Assertion Mappings
 

topics/identity-broker/configuration.adoc

@@ -1,3 +1,4 @@
+[[_general-idp-config]]
 
 === General Configuration
 

topics/identity-broker/first-login-flow.adoc

@@ -2,30 +2,31 @@
 
 === First Login Flow
 
-When Keycloak successfully authenticates user through identity provider (step 8 in <<_identity_broker_overview,Overview>> chapter), there can be two situations:
+When a user logs in through identity brokering some aspects of the user are imported and linked within the realm's local database.
+When {{book.project.name}} successfully authenticates users through an external identity provider
+there can be two situations:
 
-. There is already Keycloak user account linked with the authenticated identity provider account.
+* There is already a {{book.project.name}} user account imported and linked with the authenticated identity provider account.
-  In this case, Keycloak will just authenticate as the existing user and redirect back to application (step 9 in <<_identity_broker_overview,Overview>> chapter).
+  In this case, {{book.project.name}} will just authenticate as the existing user and redirect back to application.
-. There is not yet existing Keycloak user account linked with the identity provider account.
+* There is not yet an existing {{book.project.name}} user account imported and linked for this external user.
-  This situation is more tricky.
+  Usually you just want to register and import the new account into {{book.project.name} database, but what if there is existing
-  Usually you just want to register new account into Keycloak database, but what if there is existing Keycloak account with same email like the identity provider account? Automatically link identity provider account with existing Keycloak account is not very good option as there are possible security flaws related to that...
+  {{book.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.
 
-Because we had various requirements what to do in second case, we changed the behaviour to be flexible and configurable through <<_auth_spi,Authentication Flows SPI>>.
+Different organizations have different requirements when dealing with some of the conflicts and situations listed above.
-In admin console in Identity provider settings, there is option `First Login Flow`, which allows you to choose, which workflow will be used after "first login" with this identity provider account.
+For this, there is a `First Login Flow` option in the IDP settings which allows you to choose a <<fake/../../authentication/flows.adoc#_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 etc.
 
 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 either re-configure existing flow (For example disable some authenticators, mark some of them as `required`, configure some authenticators etc). Or you can even create new authentication flow and/or write your own Authenticator implementations and use it in your flow.
+You can either re-configure existing flow (For example disable some authenticators, mark some of them as `required`, configure some authenticators etc).
-See <<_auth_spi,Authentication Flows SPI>> for more details on how to do it.
+Or you can even create new authentication flow and/or write your own Authenticator implementations and use it in your flow.
-
+See link:{{book.developerguide.link}}[{{book.developerguide.name}} for more details.
-For `First Broker Login` case, it might be useful if your Authenticator is subclass of `org.keycloak.authentication.authenticators.broker.AbstractIdpAuthenticator`            so you have access to all details about authenticated Identity provider account.
-But it's not a requirement.
 
 ==== Default First Login Flow
 
 Let's describe the default behaviour provided by `First Broker Login` flow.
-There are those authenticators:
 
 Review Profile::
   This authenticator might display the profile info page, where user can review his profile retrieved from identity provider.
@@ -33,26 +34,30 @@ Review Profile::
   You can set `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 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)
+  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)
 
 Create User If Unique::
-  This authenticator checks if there is already existing Keycloak account with same email or username like the account from identity provider.
+  This authenticator checks if there is already existing {{book.project.name}} account with same email or username like the account from identity provider.
-  If it's not, then authenticator just creates new Keyclok account and link it with identity provider and whole flow is finished.
+  If it's not, then authenticator just creates a new local {{book.project.name}} account and links it with 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 existing Keycloak account and user needs to link his identity provider account through Account management.
+  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 existing {{book.project.name}} account and user needs to link his identity provider account through Account management.
 
 Confirm Link Existing Account::
-  User will see the info page, that there is existing Keycloak account with same email.
+  On the info page, the user will see that there is an existing {{book.project.name}} account with same email.
-  He can either review his profile again and use different email or username (flow is restarted and goes back to `Review Profile` authenticator). Or he can confirm that he wants to link identity provider account with his existing Keycloak account.
+  He can either review his profile again and use different email or username (flow is restarted and goes back to `Review Profile` authenticator).
+  Or he can confirm that he wants to link the identity provider account with his existing {{book.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.
 
 Verify Existing Account By Email::
-  This authenticator is `ALTERNATIVE` by default, so it's used only if realm has SMTP setup configured.
+  This authenticator is `ALTERNATIVE` by default, so it's used only if the realm has SMTP setup configured.
-  It will send mail to user, where he can confirm that he wants to link identity provider with his Keycloak account.
+  It will send mail to user, where he can confirm that he wants to link identity provider with his {{book.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).
 
 Verify Existing Account By Re-authentication::
-  This authenticator is used if email authenticator is disabled or non-available (SMTP not configured for realm). It will display login screen where user needs to authenticate with his password to link his Keycloak account with Identity provider.
+  This authenticator is used if email authenticator is disabled or non-available (SMTP not configured for realm). It will display login screen
-  User can also re-authenticate with some different identity provider, which is already linked to his keycloak account.
+  where the user needs to authenticate with his password to link his {{book.project.name}} account with Identity provider.
-  You can also force users to use OTP, otherwise it's optional and used only if OTP is already set for user account.
+  User can also re-authenticate with some different identity provider, which is already linked to his {{book.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.
 

topics/identity-broker/mappers.adoc

@@ -1,25 +1,30 @@
 
-=== Mapping/Importing SAML and OIDC Metadata
+=== 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.
+
+Each new user that logs into your realm via an external identity provider will be have an entry for it created in the local
+{{book.project.name}} database.  The act of importing metadata from the SAML or OIDC assertions and claims will create this data
+with the local realm database.
+
+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 is also a `Mappers` tab.  Click on that tab to start mapping your incoming IDP metadata.
+
+image:../../{{book.images}}/identity-provider-mappers.png[]
 
-You can import SAML assertion data, OpenID Connect ID Token claims, and Keycloak access token claims into new users that are imported from a brokered IDP.
-After you configure a broker, you'll see a `Mappers`            button appear.
-Click on that and you'll get to the list of mappers that are assigned to this broker.
 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.
+Broker mappers can import SAML attributes or OIDC ID/Access token claims into user attributes and user role mappings.
-You can assign a role mapping to a user if a claim or external role exists.
-There's a bunch of options here so just mouse over the tool tips to see what each mapper can do for you.
 
-=== Mapping/Importing User profile data from Social Identity Provider
+image:../../{{book.images}}/identity-provider-mapper.png[]
 
-You can import user profile data provided by social identity providers like Google, GitHub, LinkedIn, Microsoft, Stackoverflow and Facebook  into new Keycloak user created from given social accounts.
+Select a mapper from the `Mapper Type` list.  Hover over the tooltip to see a description of what the mapper does.  The
-After you configure a broker, you'll see a `Mappers`            button appear.
+tooltips also describe what configuration information you need to enter. Click `Save` and your new mapper will be added.
-Click on that and you'll get to the list of mappers that are assigned to this broker.
-There is a `Create` button on this page.
-Clicking on this create button allows you to create a broker mapper.
-"Attribute Importer" mapper allows you to define path in JSON user profile data provided by the provider to get value from.
-You can use dot notation for nesting and square brackets to access fields in array by index.
-For example 'contact.address[0].country'.  Then you can define name of Keycloak's user profile attribute this value is stored into.
 
-To investigate structure of user profile JSON data provided by social providers you can enable `DEBUG` level for  logger `org.keycloak.social.user_profile_dump` and login using given provider.
+For JSON based claims, you can use dot notation for nesting and square brackets to access fields in array by index.
-Then you can find user profile  JSON structure in Keycloak log file.
+For example 'contact.address[0].country'.
+
+To investigate structure of user profile JSON data provided by social providers you can enable `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).

topics/identity-broker/oidc.adoc

@@ -1,66 +1,56 @@
+
 === OpenID Connect v1.0 Identity Providers
 
-Keycloak can broker identity providers based on the OpenID Connect v1.0 protocol.
+{{book.project.name}} can broker identity providers based on the OpenID Connect protocol.  These IDPs must support the <<fake/../../sso-protocols/oidc.adoc, Authorization Code Flow>>
+as defined by the specification in order to authenticate the user and authorize access.
 
-In order to configure a OIDC identity provider, follow these steps:
+To begin configuring an OIDC provider, go to the `Identity Providers` left menu item
+and selected `OpenID Connect v1.0` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
 
-. Select the `OpenID Connect v1.0` identity provider from the drop-down box on the top right corner of the identity providers table in Keycloak's Admin Console.
+.Add Identity Provider
-  You should be presented with a specific page to configure the selected provider.
+image:../../../{{book.images}}/oidc-add-identity-provider.png[]
 
-When configuring an OIDC identity provider you are presented with different configuration options in order to send authentication requests to the external identity provider.
+The initial configuration options on this page are described in <<fake/../../identity-broker/configuration.adoc#_general-idp-config, General IDP Configuration>>.
-In this case, the brokered identity provider must support the Authorization Code Flow (as defined by the specification) in order to authenticate the user and authorize access for the scopes specified in the configuration.
+You must define the OpenID Connection configuration options as well.  They basically describe the OIDC IDP you are communicating with.
 
-.Configuration Options
+.OpenID Connect Config
-[cols="1,1", options="header"]
 |===
-|
+|Configuration|Description
-                            Configuration
 
-|
+|Authorization URL
-                            Description
+|Authorization URL endpoint required by the OIDC protocol
 
-|
+|Token URL
-                            Authorization Url
+|Token URL endpoint required by the OIDC protocol
 
+|Logout URL
+|Logout URL endpoint defined in the OIDC protocol.  This value is optional.
 
-|
+|Backchannel Logout
-                            Token Url
+|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.
 
+|User Info URL
+|User Info URL endpoint defined by the OIDC protocol.  This is an endpoint from which user profile information can be downloaded.
 
-|
+|Client ID
-                            Logout Url
+|This realm will act as an OIDC client to the external federation IDP you are configuring here.  Your realm will need a OIDC client ID when using 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.
 
-|
+|Issuer
-                            Backchannel Logout
+|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.
 
+|Default Scopes
+|Space-separated list of OIDC scopes to send with the authentication request.  The default is `openid`
 
-|
+|Prompt
-                            User Info Url
+|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
-
-|
-                            Client ID
-
-
-|
-                            Client Secret
-
-
-|
-                            Issuer
-
-
-|
-                            Default Scopes
-
-|
-                            Allows you to specify additional scopes when asking for user authentication and consent. By default, scope openid is always appended to the list of the scopes.
-
-
-|
-                            Prompt
-
 |===
 
-You can also import all this configuration data by providing a URL or file that points to OpenID Provider Metadata (see OIDC Discovery specification)
+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 {{book.project.name}} external IDP, you can import the IDP setttings from the url `<root>/auth/realms/\{realm-name}/.well-known/openid-configuration`.
+This link is a JSON document describing metadata about the IDP.

topics/identity-broker/saml.adoc

@@ -1,78 +1,65 @@
 
 === SAML v2.0 Identity Providers
 
-Keycloak can broker identity providers based on the SAML v2.0 protocol.
+{{book.project.name}} can broker identity providers based on the SAML v2.0 protocol.
 
-In order to configure a SAML identity provider, follow these steps:
+To begin configuring an OIDC provider, go to the `Identity Providers` left menu item
+and selected `OpenID Connect v1.0` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
 
-. Select the `SAML v2.0` identity provider from the drop-down box on the top right corner of the identity providers table in Keycloak's Admin Console.
+.Add Identity Provider
-  You should be presented with a specific page to configure the selected provider.
+image:../../../{{book.images}}/saml-add-identity-provider.png[]
 
-When configuring a SAML identity provider you are presented with different configuration options in order to properly communicate and integrate with the external identity provider.
+The initial configuration options on this page are described in <<fake/../../identity-broker/configuration.adoc#_general-idp-config, General IDP Configuration>>.
-In this case, you must keep in mind that Keycloak will act as an Service Provider that issues authentication requests(AuthnRequest) to the external identity provider.
+You must define the SAML configuration options as well.  They basically describe the SAML IDP you are communicating with.
 
-.Configuration Options
+.SAML Confnig
-[cols="1,1", options="header"]
 |===
-|
+|Configuration|Description
-                            Configuration
 
-|
+|Single Sign-On Service URL
-                            Description
+|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.
 
-|
+|Single Logout Service URL
-                            Import IdP SAML Metadata
+|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.
 
+|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.
 
-|
+|HTTP-POST Binding for AuthnRequest
-                            Single Sign-On Service Url
+|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.
 
+|Want AuthnRequests Signed
+|If true, it will use the realm's keypair to sign requests sent to the external SAML IDP
 
-|
+|Signature Algorithm
-                            Single Logout Service Url
+|If `Want AuthnRequests Signed` is on, then you can also pick the signature algorithm to use.
 
+|Force Authentication
+|Indicates that the user will be forced to enter in their credentials at the external IDP even if they are already logged in.
 
-|
+|Validate Signature
-                            Backchannel Logout
+|Whether or not the realm should expect that SAML requests and responses from the external IDP be digitally signed.  It is highly recommended you turn this on!
-
-
-|
-                            NameID Policy Format
-
-
-|
-                            Validating X509 Certificate
-
-
-|
-                            Want AuthnRequests Signed
-
-
-|
-                            Force Authentication
-
-
-|
-                            Validate Signature
-
-
-|
-                            HTTP-POST Binding Response
-
-
-|
-                            HTTP-POST Binding for AuthnReques
 
+|Validating X509 Certificate
+|The public certificate that will be used to validate the signatures of SAML requests and responses from the external IDP.
 |===
 
+
+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 {{book.project.name}} external IDP, you can import the IDP setttings 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.
 
-Once you create a SAML provider, there is an `EXPORT` button that appears when viewing that provider.
-Clicking this button will export a SAML entity descriptor which you can use to
-
 ==== SP Descriptor
 
-The SAML SP Descriptor XML file for the broker is available publically by going to this URL
+Once you create a SAML provider, there is an `EXPORT` button that appears when viewing that provider.
+Clicking this button will export a SAML SP entity descriptor which you can use to import into the external SP provider.
+
+This metadata is also available publically by going to the URL
 
 [source]
 ----
@@ -80,5 +67,4 @@ The SAML SP Descriptor XML file for the broker is available publically by going
                 http[s]://{host:port}/auth/realms/{realm-name}/broker/{broker-alias}/endpoint/descriptor
 ----
 
-This URL is useful if you need to import this information into an IDP that needs or is more user friendly to load from a remote URL.
 

topics/identity-broker/session-data.adoc

@@ -1,3 +1,4 @@
+
 === Available User Session Data
 
 After a user logs in from the external IDP, there's some additional user session note data that Keycloak stores that you can access.
@@ -6,3 +7,5 @@ This data can be propagated to the client requesting a login via the token or SA
 BROKER_PROVIDER_ID::
   This is the IDP alias of the broker used to perform the login.
 
+You can use a <<fake/../../clients/protocol-mappers.adoc#_protocol-mappers, Protocol Mapper>> to propagate this information to your clients.
+

topics/identity-broker/suggested.adoc

@@ -1,15 +1,17 @@
 
 === Client Suggested Identity Provider
 
-Each Identity provider has option `Authenticate By Default`, which allows that Identity provider is automatically selected during authentication.
+Each identity provider has an option `Authenticate By Default`, which allows that Identity provider is automatically selected during authentication.
-User won't even see Keycloak login page, but is automatically redirected to the identity provider.
+User won't even see the {{book.project.name}} login page and will instead be automatically redirected to the default identity provider.
 
-Applications can also automatically select an identity provider in order to authenticate an user.
+OIDC applications can also bypass the {{book.project.name}} login page by specifying a hint on which
-Selection per application is preferred over `Authenticate By Default` option if you need more control on when exactly is Identity provider automatically selected.
+identity provider they want to use.
+This is done by appending the `kc_idp_hint` query parameter in the Authorization Code Flow authorization endpoint.
 
-Keycloak supports a specific HTTP query parameter that you can use as a hint to tell the server which identity provider should be used to authenticate the user.
+{{book.project.name}} OIDC client adapters also allow you to specify this query parameter when you access a secured resource
+at the application.
 
-For that, you can append the `kc_idp_hint` as a query parameter to your application url, as follows:
+For example
 
 [source,java]
 ----

topics/identity-broker/tokens.adoc

@@ -1,11 +1,11 @@
-=== Retrieving Tokens from Identity Providers
 
-Keycloak allows you to store tokens and responses from identity providers during the authentication process.
+=== Retrieving External IDP Tokens
-For that, you can use the `Store Token` configuration option, as mentioned before.
 
-It also allows you to retrieve these tokens and responses once the user is authenticated in order to use their information or use them to invoke external resources protected by these tokens.
+{{book.project.name}} allows you to store tokens and responses from the authentication process with the external IDP.
-The latter case is usually related with social providers, where you usually need to use their tokens to invoke methods on their APIs.
+For that, you can use 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:
 
 [source,java]
@@ -15,12 +15,10 @@ Host: localhost:8080
 Authorization: Bearer {keycloak_access_token}
 ----
 
+An application must have authenticated with {{book.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 an protected service in Keycloak, you need to send the access token issued by Keycloak during the user authentication.
 
-By default, the Keycloak access token issued for the application can't be automatically used for retrieve thirdparty token.
-A user will have to have the `broker.read-token` role.
-The client will also have to have that role in its scope.
 In the broker configuration page you can automatically assign this role to newly imported users by turning on the `Stored Tokens Readable` switch.
 
-NOTE: If your application is not at the same origin as the authentication server, make sure you have properly configured CORS.
-