Merge pull request #19 from ssilvert/identity-brokering-chapter

Minor changes to identity brokering chapter.

topics/identity-broker.adoc

@@ -6,13 +6,14 @@ An Identity Broker is an intermediary service that connects multiple service pro
 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.
 
-From an user perspective, an identity broker provides an user-centric and centralized way to manage identities across different security
+From a user perspective, an identity broker provides a user-centric and centralized way to manage identities across different security
-domains or realms, where an existing account can be linked with one or more identities from different identity providers or even created
+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.
 
 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, a business partner which you want to allow its users to access your services or a cloud-based identity
+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 an be a cloud-based identity
 service that you want to integrate with.
+
 Usually, identity providers are based on the following protocols: 
 
 * `SAML v2.0`            

topics/identity-broker/configuration.adoc

@@ -25,9 +25,9 @@ image:../../{{book.images}}/identity-provider-login-page.png[]
 
 
 Social::
-  Social providers allows you to enable social authentication to your realm.
+  Social providers allow you to enable social authentication in your realm.
   {{book.project.name}} makes it easy to let users log in to your application using an existing account with a social network.
-  Currently Facebook, Google, Twitter, GitHub, LinkedIn, Microsoft and StackOverflow are supported with more planned for the future.
+  Currently Facebook, Google, Twitter, GitHub, LinkedIn, Microsoft, and StackOverflow are supported with more planned for the future.
 
 Protocol-based::
   Protocol-based providers are those that rely on a specific protocol in order to authenticate and authorize users.
@@ -44,10 +44,10 @@ Regardless the identity provider you are creating, you'll see the following conf
 |Configuration|Description
 
 |Alias
-|The alias is an unique identifier for an identity provider. It is used to reference internally an identity provider.
+|The alias is an unique identifier for an identity provider. It is used to reference an identity provider internally.
- Some protocols require a redirect URI or callback url in order to communicate with an identity provider. For instance, OpenID Connect.
+ 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. For example, facebook, google, idp.acme.com, etc.
+ Every single identity provider must have an alias. Examples are facebook, google, idp.acme.com, etc.
 
 |Enabled
 |Turn the provider on/off
@@ -56,11 +56,11 @@ Regardless the identity provider you are creating, you'll see the following conf
 |Whether or not to store the token received from the identity provider.
 
 |Stored Tokens Readable
-|Whether or not users are allowed to retrieve the stored identity provider token.  This also applies the _broker_ client-level
+|Whether or not users are allowed to retrieve the stored identity provider token.  This 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
+|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.
 
 |Authenticate By Default
@@ -72,10 +72,10 @@ Regardless the identity provider you are creating, you'll see the following conf
 
 |First Login Flow
 |This is the authentication flow that will be triggered for users that log into {{book.project.name}} through this IDP
- for the first time ever
+ for the first time ever.
 
 |Post Login Flow
-|Authentication flow that is triggered after the user finishes logging in with the external identity provider
+|Authentication flow that is triggered after the user finishes logging in with the external identity provider.
 |===
 
 

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

@@ -9,19 +9,19 @@ there can be two situations:
 * There is already a {{book.project.name}} user account imported and linked with the authenticated identity provider account.
   In this case, {{book.project.name}} will just authenticate as the existing user and redirect back to application.
 * There is not yet an existing {{book.project.name}} user account imported and linked for this external user.
-  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 and import the new account into {{book.project.name}} database, but what if there is an existing
   {{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.
 
 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 <<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.
+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.
 
 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).
+You can re-configure the existing flow. (For example you can 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.
+Or you can even create a 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.
 
 ==== Default First Login Flow
@@ -29,35 +29,35 @@ See link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more det
 Let's describe the default behaviour provided by `First Broker Login` flow.
 
 Review Profile::
-  This authenticator might display the profile info page, where user can review his profile retrieved from identity provider.
+  This authenticator might display the profile info page, where the user can review his profile retrieved from an identity provider.
   The authenticator is configurable.
-  You can set `Update Profile On First Login` option.
+  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 identity provider.
+  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)
 
 Create User If Unique::
-  This authenticator checks if there is already existing {{book.project.name}} account with same email or username like the account from identity provider.
+  This authenticator checks if there is already an existing {{book.project.name}} account with same email or username like the account from the identity provider.
-  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.
+  If it's not, then the authenticator just creates a new local {{book.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 existing {{book.project.name}} account and user needs to link his identity provider account through Account management.
+  will see the error page if there is existing {{book.project.name}} account and the user will need to link his identity provider account through Account management.
 
 Confirm Link Existing Account::
   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).
+  He can 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 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 {{book.project.name}} account.
+  It will send mail to the user, where he can confirm that he wants to link the 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
+  This authenticator is used if email authenticator is disabled or non-available (SMTP not configured for realm). It will display a login screen
-  where the user needs to authenticate with his password to link his {{book.project.name}} account with Identity provider.
+  where the user needs to authenticate with his password to link his {{book.project.name}} account with the Identity provider.
   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.
+  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

@@ -5,7 +5,7 @@ You can import the SAML and OpenID Connect metadata provided by the external IDP
 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
+Each new user that logs into your realm via an external identity provider will 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.
 
@@ -23,8 +23,8 @@ image:../../{{book.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.
 
-For JSON based claims, you can use dot notation for nesting and square brackets to access fields in array by index.
+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 structure of user profile JSON data provided by social providers you can enable `DEBUG` level logger `org.keycloak.social.user_profile_dump`.
+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).

topics/identity-broker/oidc.adoc

@@ -5,7 +5,7 @@
 as defined by the specification in order to authenticate the user and authorize access.
 
 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.
+and select `OpenID Connect v1.0` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
 
 .Add Identity Provider
 image:../../{{book.images}}/oidc-add-identity-provider.png[]

topics/identity-broker/overview.adoc

@@ -3,7 +3,8 @@
 === Brokering Overview
 
 When using {{book.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 where they can pick one and authenticate.
+Instead, they are presented with a list of identity providers from which they can authenticate.
+
 You can also configure a default broker.
 In this case the user will not be given a choice, but instead be redirected directly to the parent broker.
 The following diagram demonstrates the steps involved when using {{book.project.name}} to broker an external identity provider:
@@ -13,7 +14,7 @@ image:../../images/identity_broker_flow.png[]
 
 . User is not authenticated and requests a protected resource in a client application.
 . The client applications redirects the user to {{book.project.name}} to authenticate.
-. At this point the user is presented to the login page where there is a list of identity providers supported by a realm.
+. At this point the user is presented with the login page where there is a list of identity providers supported by a realm.
 . User selects one of the identity providers by clicking on its respective button or link.
 . {{book.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.
@@ -27,20 +28,20 @@ image:../../images/identity_broker_flow.png[]
   If it is a new user, {{book.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 {{book.project.name}} may ask him to link the identity returned from the identity provider with his existing account.
-  A process that we call _account linking_.
+  We call this process _account linking_.
   What exactly is done is configurable and can be specified by setup of <<fake/../../identity-broker/first-login-flow.adoc#_identity_broker_first_login,First Login Flow>> . At the end of this step, {{book.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, {{book.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 {{book.project.name}} and allows 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 request a specific one.
+For instance, instead of presenting a list of identity providers, the client application can request a specific one.
-Or you can tell {{book.project.name}} to force the user to provide additional information before federate his identity.
+Or you can tell {{book.project.name}} to force the user to provide additional information before federating his identity.
 
 NOTE: Different protocols may require different authentication flows.
       At this moment, all the identity providers supported by {{book.project.name}} use a flow just like described above.
       However, despite the protocol in use, user experience should be pretty much the same.
 
-As you may notice, at the end of the authentication process {{book.project.name}} will always issue its own token to client applications,
+As you may notice, at the end of the authentication process {{book.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.
+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 {{book.project.name}} !

topics/identity-broker/saml.adoc

@@ -4,7 +4,7 @@
 {{book.project.name}} can broker identity providers based on the SAML v2.0 protocol.
 
 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.
+and select `SAML v2.0` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
 
 .Add Identity Provider
 image:../../{{book.images}}/saml-add-identity-provider.png[]
@@ -12,7 +12,7 @@ image:../../{{book.images}}/saml-add-identity-provider.png[]
 The initial configuration options on this page are described in <<fake/../../identity-broker/configuration.adoc#_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.
 
-.SAML Confnig
+.SAML Config
 |===
 |Configuration|Description
 
@@ -59,7 +59,7 @@ You can also import all this configuration data by providing a URL or XML file t
 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
+This metadata is also available publicly by going to the URL
 
 [source]
 ----

topics/identity-broker/social/facebook.adoc

@@ -2,7 +2,7 @@
 ==== Facebook
 
 There are a number of steps you have to complete to be able to login to Facebook.  First, go to the `Identity Providers` left menu item
-and selected `Facebook` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
+and select `Facebook` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
 
 .Add Identity Provider
 image:../../../{{book.images}}/facebook-add-identity-provider.png[]

topics/identity-broker/social/github.adoc

@@ -2,7 +2,7 @@
 ==== Github
 
 There are a number of steps you have to complete to be able to login to Github.  First, go to the `Identity Providers` left menu item
-and selected `Github` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
+and select `Github` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
 
 .Add Identity Provider
 image:../../../{{book.images}}/github-add-identity-provider.png[]
@@ -11,7 +11,7 @@ You can't click save yet, as you'll need to obtain a `Client ID` and `Client Sec
 page is the `Redirect URI`.  You'll have to provide that to Github when you register {{book.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 the and a client in
+To enable login with Github you first have to register an application project in
 https://github.com/settings/applications[GitHub Application Settings].  Select the `Developer applications` tab.
 
 NOTE: Github often changes the look and feel of application registration, so these directions might not always be up to date and the
@@ -28,7 +28,7 @@ image:../../../images/github-register-app.png[]
 
 You'll have to copy the `Redirect URI` from the {{book.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 brough to the application's management page.
+page you will be brought to the application's management page.
 
 .Github App Page
 image:../../../images/github-app-page.png[]

topics/identity-broker/social/google.adoc

@@ -1,7 +1,7 @@
 ==== Google
 
 There are a number of steps you have to complete to be able to login to Google.  First, go to the `Identity Providers` left menu item
-and selected `Google` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
+and select `Google` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
 
 .Add Identity Provider
 image:../../../{{book.images}}/google-add-identity-provider.png[]

topics/identity-broker/social/linked-in.adoc

@@ -2,7 +2,7 @@
 ==== LinkedIn
 
 There are a number of steps you have to complete to be able to login to LinkedIn.  First, go to the `Identity Providers` left menu item
-and selected `LinkedIn` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
+and select `LinkedIn` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
 
 .Add Identity Provider
 image:../../../{{book.images}}/linked-in-add-identity-provider.png[]

topics/identity-broker/social/microsoft.adoc

@@ -2,7 +2,7 @@
 ==== Microsoft
 
 There are a number of steps you have to complete to be able to login to Microsoft.  First, go to the `Identity Providers` left menu item
-and selected `Microsoft` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
+and select `Microsoft` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
 
 .Add Identity Provider
 image:../../../{{book.images}}/microsoft-add-identity-provider.png[]

topics/identity-broker/social/stack-overflow.adoc

@@ -2,7 +2,7 @@
 ==== StackOverflow
 
 There are a number of steps you have to complete to be able to login to StackOverflow.  First, go to the `Identity Providers` left menu item
-and selected `StackOverflow` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
+and select `StackOverflow` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
 
 .Add Identity Provider
 image:../../../{{book.images}}/stack-overflow-add-identity-provider.png[]

topics/identity-broker/social/twitter.adoc

@@ -2,7 +2,7 @@
 ==== Twitter
 
 There are a number of steps you have to complete to be able to login to Twitter.  First, go to the `Identity Providers` left menu item
-and selected `Twitter` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
+and select `Twitter` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.
 
 .Add Identity Provider
 image:../../../{{book.images}}/twitter-add-identity-provider.png[]

topics/identity-broker/suggested.adoc

@@ -1,8 +1,8 @@
 
 === Client Suggested Identity Provider
 
-Each identity provider has an 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 to be automatically selected during authentication.
-User won't even see the {{book.project.name}} login page and will instead be automatically redirected to the default identity provider.
+The user won't see the {{book.project.name}} login page and will instead be automatically redirected to the default identity provider.
 
 OIDC applications can also bypass the {{book.project.name}} login page by specifying a hint on which
 identity provider they want to use.

topics/identity-broker/tokens.adoc

@@ -18,7 +18,7 @@ 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 {{book.project.name}}, you need to send the access token issued by {{book.project.name}} during the user authentication.
+In this case, given that you are accessing a protected service in {{book.project.name}}, you need to send the access token issued by {{book.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.