requested changes

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

@@ -29,39 +29,39 @@ endif::[]
 
 ==== Default First Login Flow
 
-Let's describe the default behaviour provided by `First Broker Login` flow.
+Let's describe the default behavior provided by `First Broker Login` flow.
 
 Review Profile::
-  This authenticator might display the profile info page, where the user can review his profile retrieved from an identity provider.
+  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)
+  by `Confirm Link Existing Account` authenticator).
 
 Create User If Unique::
-  This authenticator checks if there is already an existing {project_name} account with same email or username like the account from the identity provider.
+  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 existing {project_name} account and the user will need 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 an existing {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 {project_name} account with same email.
-  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 {project_name} 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.
 
 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 the user, where he can confirm that he wants to link the identity provider with his {project_name} account.
+  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).
 
 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 a login screen
-  where the user needs to authenticate with his password to link his {project_name} account with the Identity provider.
-  User can also re-authenticate with some different identity provider, which is already linked to his {project_name} account.
+  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 with his password 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.
 
 ==== Automatically Link Existing First Login Flow
@@ -70,9 +70,9 @@ WARNING: The AutoLink authenticator would be dangerous in a generic environment
 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:
 
 Create User If Unique::
-This authenticator ensures unique users are handled. Set the authenticator requirement to "Alternative".
+This authenticator ensures that unique users are handled. Set the authenticator requirement to "Alternative".
 
-Automatically Link Existing Account::
+Automatically Link Brokered Account::
 Automatically link brokered identities without any validation with this authenticator. This is useful in an intranet environment of multiple user databases each with overlapping usernames/email addresses, but different passwords, and you want to allow users to use any password without having to validate. This is only reasonable if you manage all internal databases, and usernames/email addresses from one database matching those in another database belong to the same person. Set the authenticator requirement to "Alternative".
 
 NOTE: The described setup uses two authenticators, and is the simplest one, but it is possible to use other

server_admin/topics/identity-broker/logout.adoc

@@ -3,5 +3,5 @@
 
 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 behaviour and avoid logout at the external identity provider.
+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.

server_admin/topics/identity-broker/mappers.adoc

@@ -5,12 +5,11 @@ 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 have an entry for it created in the local
-{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.
+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.
 
 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.
+`Settings` tab.  On this page there is also a `Mappers` tab.  Click on that tab to start mapping your incoming IDP metadata.
 
 image:{project_images}/identity-provider-mappers.png[]
 

server_admin/topics/identity-broker/saml.adoc

@@ -25,10 +25,10 @@ You must define the SAML configuration options as well.  They basically describe
  this field will be specified there.
  
 |Backchannel Logout
-|Enable if your SAML IDP supports backchannel logout
+|Enable if your SAML IDP supports backchannel 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.
+|Specifies the URI reference corresponding to a name identifier format. Defaults to `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`.
 
 |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.
@@ -37,7 +37,7 @@ You must define the SAML configuration options as well.  They basically describe
 |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
+|If true, it will use 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.
@@ -51,10 +51,10 @@ You must define the SAML configuration options as well.  They basically describe
  Services), or that the key name hint is completely omitted from the SAML message (option `NONE`).
 
 |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.
+|Indicates that the user will be forced to enter their credentials at the external IDP even if they are already logged in.
 
 |Validate Signature
-|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!
+|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!
 
 |Validating X509 Certificate
 |The public certificate that will be used to validate the signatures of SAML requests and responses from the external IDP.
@@ -62,7 +62,7 @@ You must define the SAML configuration options as well.  They basically describe
 
 
 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`.
+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.
 
 
@@ -74,7 +74,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.
 
-This metadata is also available publicly by going to the URL
+This metadata is also available publicly by going to the URL.
 
 [source]
 ----

server_admin/topics/identity-broker/session-data.adoc

@@ -1,14 +1,14 @@
 
 === Available User Session Data
 
-After a user logs in from the external IDP, there's some additional user session note data that {project_name} stores that you can access.
+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.
 
 identity_provider::
   This is 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 same like the {project_name} username, but doesn't necessarily needs to be.
+  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` .
 
 You can use a <<_protocol-mappers, Protocol Mapper>> of type `User Session Note` to propagate this information to your clients.

server_admin/topics/identity-broker/suggested.adoc

@@ -1,5 +1,5 @@
 [[_client_suggested_idp]]
-=== Client Suggested Identity Provider
+=== 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.
@@ -9,7 +9,7 @@ This is done by setting the `kc_idp_hint` query parameter in the Authorization C
 {project_name} OIDC client adapters also allow you to specify this query parameter when you access a secured resource
 at the application.
 
-For example
+For example:
 
 [source]
 ----
@@ -17,7 +17,7 @@ GET /myapplication.com?kc_idp_hint=facebook HTTP/1.1
 Host: localhost:8080
 ----
 
-In this case, 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, 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.
 
 If you are using `keycloak.js` adapter, you can also achieve the same behavior:
 

server_admin/topics/identity-broker/tokens.adoc

@@ -21,6 +21,6 @@ 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.
+These external tokens can be re-established by either logging in again through the provider, or using the client-initiated account linking API.