Merge pull request #15 from ssilvert/clients-chapter

SSO Protocols chapter and Clients chapter

topics/clients.adoc

@@ -2,9 +2,9 @@
 == Managing Clients
 
 Clients are entities that can request authentication of a user.  Clients come in two forms.
-he first type of client is an application that wants
+The first type of client is an application that wants
 to participate in single-sign-on.  These clients just want {{book.project.name}} to provide security for them.  The other type
-of client is one that is requesting an access token so that it can invoke on other services on behalf of the authenticated user.
+of client is one that is requesting an access token so that it can invoke other services on behalf of the authenticated user.
 This section discusses various aspects around configuring clients and various ways to do it.
 
 

topics/clients/client-oidc.adoc

@@ -2,9 +2,9 @@
 === OIDC Clients
 
 <<fake/../../sso-protocols/oidc.adoc#_oidc,OpenID Connect>> is the preferred protocol to secure applications.  It was designed from the ground up to be web friendly
-and works best with HTML5/JavaScript applications.
+and work best with HTML5/JavaScript applications.
 
-To create a OIDC client go to the `Clients` left menu item.  On this page you'll see a `create` button on the right.
+To create an OIDC client go to the `Clients` left menu item.  On this page you'll see a `Create` button on the right.
 
 .Clients
 image:../../{{book.images}}/clients.png[]
@@ -15,7 +15,7 @@ This will bring you to the `Add Client` page.
 .Add Client
 image:../../{{book.images}}/add-client-oidc.png[]
 
-Enter in the `Client ID` of the client.  This should be a simple string
+Enter in the `Client ID` of the client.  This should be a simple
 alpha-numeric string that will be used in requests and in the {{book.project.name}} database to identity the client.
 Next select `openid-connect` in the `Client Protocol` drop down box.
 Ignore the `Client Template` listbox for now,
@@ -58,14 +58,14 @@ If you've ever done a social login to Google, you'll often see a similar page.
 This defines the type of the OIDC client.
 
 _confidential_::
-  Confidential access type is for clients that need to perform a browser login and that you want to require a client secret when they turn an access code into an access token,
+  Confidential access type is for clients that need to perform a browser login and require a client secret when they turn an access code into an access token,
-  (see http://tools.ietf.org/html/rfc6749#section-4.1.3[Access Token Request] in the OAuth 2.0 spec for more details).  The advantages of this is that it is a little extra security.
+  (see http://tools.ietf.org/html/rfc6749#section-4.1.3[Access Token Request] in the OAuth 2.0 spec for more details).  The advantage of this is that it is a little extra security.
   Since {{book.project.name}} requires you to register valid redirect-uris, we're not exactly sure what this little extra security is though.
   :) The disadvantages of this access type is that confidential access type is pointless for pure JavaScript clients as anybody could easily figure out your client's secret!
 
 _public_::
   Public access type is for clients that need to perform a browser login and that you feel that the added extra security of confidential access type is not needed.
-  FYI, Pure javascript clients are by nature public.
+  Pure javascript clients are by nature public.
 
 _bearer-only_::
   Bearer-only access type means that the application only allows bearer token requests.
@@ -84,7 +84,7 @@ This is a required field.  Enter in a URL pattern and click the + sign to add.
 Remember that you still have to click the `Save` button!
 Only wildcards, * ,are allowed at the end of of a URI, i.e. http://host.com/*
 
-You should take extra precautions when registering valid redirect URI patterns as if you make
+You should take extra precautions when registering valid redirect URI patterns. If you make
 them too general you are vulnerable to attacks.  See <<fake/../../threat/redirect.adoc#_unspecific-redirect-uris, Threat Model Mitigation>> chapter
 for more information.
 
@@ -114,8 +114,8 @@ See link:{{book.adapterguide.link}}[{{book.adapterguide.name}}] for more informa
 *Web Origins*
 
 This option centers around link:http://www.w3.org/TR/cors/[CORS] which stands for Cross-Origin Resource Sharing.
-If executing browser JavaScript tries to make an AJAX HTTP request to a server whose domain is different than the one the
+If browser JavaScript tries to make an AJAX HTTP request to a server whose domain is different from the one the
-JavaScript code came from, then the request uses the CORS.
+JavaScript code came from, then the request must use CORS.
 The server must handle CORS requests in a special way, otherwise the browser will not display or allow the request to be processed.
 This protocol exists to protect against XSS, CSRF and other JavaScript-based attacks.
 

topics/clients/client-saml.adoc

@@ -5,7 +5,7 @@
 Both POST and Redirect bindings are supported.
 You can choose to require client signature validation and can have the server sign and/or encrypt responses as well.
 
-To create a SAML client go to the `Clients` left menu item.  On this page you'll see a `create` button on the right.
+To create a SAML client go to the `Clients` left menu item.  On this page you'll see a `Create` button on the right.
 
 .Clients
 image:../../{{book.images}}/clients.png[]
@@ -23,7 +23,7 @@ we'll go over that later in this chapter.
 Finally enter in the `Client SAML Endpoint` URL.  Enter the
 URL you want the {{book.project.name}} server to send SAML requests and responses to.  Usually applications have only one URL for processing SAML requests.
 If your application has different URLs for its bindings, don't worry, you can fix this in the `Settings` tab of the client.
-application in the `Root URL` field and click `Save`.  This will create the client and bring you to the client `Settings`
+Click `Save`.  This will create the client and bring you to the client `Settings`
 tab.
 
 .Client Settings
@@ -82,7 +82,7 @@ Force POST Binding::
 
 Front Channel Logout::
   If true, this application requires a browser redirect to be able to perform a logout.
-  For example, the application may require a cookie to be reset which could only be done by a done via a redirect.
+  For example, the application may require a cookie to be reset which could only be done via a redirect.
   If this switch is false, then {{book.project.name}} will invoke a background SAML request to logout the application.
 
 Force Name ID Format::
@@ -106,7 +106,7 @@ Base URL::
   If {{book.project.name}} needs to link to the client, this URL would be used.
 
 Master SAML Processing URL::
-  This URL will be used for all SAML requests and responsed directed to the SP.
+  This URL will be used for all SAML requests and the response will be directed to the SP.
   It will be used as the Assertion Consumer Service URL and the Single Logout Service URL.
   If a login request contains the Assertion Consumer Service URL, that will take precedence, but this URL must be valided by a registered Valid Redirect URI pattern 
 

topics/clients/installation.adoc

@@ -1,11 +1,11 @@
 
 === Generating Client Adapter Config
 
-The {{book.project.name}} can pre-generate configure files that you can use to install a client adapter for in your application's
+The {{book.project.name}} can pre-generate configuration files that you can use to install a client adapter for in your application's
 deployment environment.  A number of adapter types are supported for both OIDC and SAML.  Go to the `Installation` tab of the
 client you want to generate configuration for.
 
 image:../../{{book.images}}/client-installation.png[]
 
-Select the `format option` you want configuration generated for.  All {{book.project.name}} client adapters for OIDC and SAML
+Select the `Format Option` you want configuration generated for.  All {{book.project.name}} client adapters for OIDC and SAML
 are supported.  The mod-auth-mellon Apache HTTPD adapter for SAML is supported as well as standard SAML entity descriptor files.

topics/clients/oidc/confidential.adoc

@@ -9,7 +9,7 @@ type of client you have to configure the client's credentials.
 .Credentials Tab
 image:../../../{{book.images}}/client-credentials.png[]
 
-The `Client Authenticator` list box is the type of credential you are going to use for your confidential client.
+The `Client Authenticator` list box specifies the type of credential you are going to use for your confidential client.
 It defaults to client ID and secret.  The secret is automatically generated for you and the `Regenerate Secret`
 button allows you to recreate this secret if you want or need to.
 
@@ -35,7 +35,7 @@ generate these via an external tool and just import the client's certificate.
 .Import Certificate
 image:../../../{{book.images}}/import-client-cert.png[]
 
-There's multiple formats you can import from, just choose the archive format you have the certificate stored in,
+There are multiple formats you can import from, just choose the archive format you have the certificate stored in,
 select the file, and click the `Import` button.
 
 

topics/clients/oidc/service-accounts.adoc

@@ -2,7 +2,7 @@
 
 === Service Accounts
 
-Each OIDC client has a built in _service account_ which allows them to obtain an access token.
+Each OIDC client has a built in _service account_ which allows it to obtain an access token.
 This is covered in the OAuth 2.0 specifiation under <<fake/../../../sso-protocols/oidc.adoc#_oidc-auth-flows,Client Credentials Grant>>
 To use this feature you must set the <<fake/../../../clients/client-oidc.adoc#_access-type, Access Type>> of your client to `confidential`.  When you do this,
 the `Service Accounts Enabled` switch will appear.  You need to turn on this switch.  Also make sure that you have
@@ -10,14 +10,14 @@ configured your <<fake/../../../clients/oidc/confidential.adoc#_client-credentia
 
 To use it you must have registered a valid `confidential` Client and you need to check the switch `Service Accounts Enabled` in {{book.project.name}} admin console for this client.
 In tab `Service Account Roles` you can configure the roles available to the service account retrieved on behalf of this client.
-Don't forget that you need those roles to be available in Scopes of this client as well (unless you have `Full Scope Allowed` on). As in normal login, roles from access token are intersection of scopes and the service account roles. 
+Don't forget that you need those roles to be available in Scopes of this client as well (unless you have `Full Scope Allowed` on). As in normal login, roles from access token are the intersection of scopes and the service account roles. 
 
 The REST URL to invoke on is `/\{server-root-usualy-auth}/realms/\{realm-name}/protocol/openid-connect/token`.
 Invoking on this URL is a POST request and requires you to post the client credentials.
-By default, client credentials are represented by clientId and clientSecret of the client in `Authorization: Basic` header, but you can also authenticate client with signed JWT assertion or any other custom mechanism for client authentication.
+By default, client credentials are represented by clientId and clientSecret of the client in `Authorization: Basic` header, but you can also authenticate the client with a signed JWT assertion or any other custom mechanism for client authentication.
-You also need to use parameter `grant_type=client_credentials` as per OAuth2 specification.
+You also need to use the parameter `grant_type=client_credentials` as per the OAuth2 specification.
 
-For example the POST invocation to retrieve service account can look like this: 
+For example the POST invocation to retrieve a service account can look like this: 
 
 [source]
 ----
@@ -50,4 +50,4 @@ Pragma: no-cache
 }
 ----    
 
-The retrieved access token can be refreshed or logged out by out-of-bound request. 
+The retrieved access token can be refreshed or logged out by an out-of-bound request. 

topics/clients/protocol-mappers.adoc

@@ -15,19 +15,19 @@ an OIDC based client.
 .Mappers Tab
 image:../../{{book.images}}/mappers-oidc.png[]
 
-Every client has a bunch of built-in mappers that are created for it by default.  They map things like, for example, email address to
+Each client has several built-in mappers that are created for it by default.  They map things like, for example, email address to
-a specific claim in the identity and access token.  Their function should each be self explanatory from their name.  There's
+a specific claim in the identity and access token.  Their function should each be self explanatory from their name.  There
-is additional pre-configured mappers that are not attached to the client that you can add
+are additional pre-configured mappers that are not attached to the client that you can add
 by clicking the `Add Builtin` button.
 
-Each mapper has common settings as well as additional ones depending on which type of mapper you are adding.  Click the `edit` button
+Each mapper has common settings as well as additional ones depending on which type of mapper you are adding.  Click the `Edit` button
 next to one of the mappers in the list to get to the config screen.
 
 .Mapper Config
 image:../../{{book.images}}/mapper-config.png[]
 
-The best way to find out what a config option is is to moveover the tooltips.  There are a few config options that
+The best way to learn about a config option is to hover over its tooltip.  There are a few config options that
-are common to all mappers.
+are common to all mappers:
 
 Consent::
   If your client requires consent, this mapper will be displayed on the consent screen shown to the user.
@@ -40,7 +40,7 @@ Consent Text::
 Most OIDC mappers also allow you to control where the claim gets put.  You can opt to include or exclude the claim from both the
 _id_ and _access_ tokens by fiddling with the `Add to ID token` and `Add to access token` switches.
 
-Finaly, you can also add other mapper types.  if you go back to the `Mappers` tab, click the `Create` button.
+Finally, you can also add other mapper types.  If you go back to the `Mappers` tab, click the `Create` button.
 
 .Add Mapper
 image:../../{{book.images}}/add-mapper.png[]

topics/sso-protocols/oidc.adoc

@@ -4,10 +4,10 @@
 
 link:http://openid.net/connect/[Open ID Connect] (OIDC) is an authentication protocol that is an extension of link:https://tools.ietf.org/html/rfc6749[OAuth 2.0].
 While OAuth 2.0 is only a framework for building authorization protocols and is mainly incomplete, OIDC is a full-fledged authentication and authorization
-protocol.  OIDC also makes heavy use of the link:https://jwt.io[Json Web Token] (JWT) set of standards.  These standards define a
+protocol.  OIDC also makes heavy use of the link:https://jwt.io[Json Web Token] (JWT) set of standards.  These standards define an
 identity token JSON format and ways to digitally sign and encrypt that data in a compact and web-friendly way.
 
-There is really two types of use cases when using OIDC.  The first is an application that asks the {{book.project.name}} server to authenticate
+There are really two types of use cases when using OIDC.  The first is an application that asks the {{book.project.name}} server to authenticate
 a user for them.  After a successful login, the application will receive an _identity token_ and an _access token_.  The _identity token_
 contains information about the user such as username, email, and other profile information.  The _access token_ is digitally signed by
 the realm and contains access information (like user role mappings) that the application can use to determine what resources the user
@@ -30,14 +30,14 @@ OIDC and OAuth 2.0 specifications so only a brief overview will be provided here
 
 ===== Authorization Code Flow
 
-This is a browser-based protocol and what we recommend you use to authenticate and authorize browser-based applications.  It makes
+This is a browser-based protocol and it is what we recommend you use to authenticate and authorize browser-based applications.  It makes
-heavy use of browser redirects to obtain an _identity_ and _access_ token.  Here's a brief summary
+heavy use of browser redirects to obtain an _identity_ and _access_ token.  Here's a brief summary:
 
 . Browser visits application.  The application notices the user is not logged in, so it redirects the browser to {{book.project.name}}
   to be authenticated.  The application passes along a callback URL (a redirect URL) as a query parameter in this browser redirect
   that {{book.project.name}} will use when it finishes authentication.
 . {{book.project.name}} authenticates the user and creates a one-time, very short lived, temporary code.  {{book.project.name}}
-  redirects back to the application using the callback URL provided earlier and additionally adding the temporary code
+  redirects back to the application using the callback URL provided earlier and additionally adds the temporary code
   as a query parameter in the callback URL.
 . The application extracts the temporary code and makes a background out of band REST invocation to {{book.project.name}}
   to exchange the code for an _identity_, _access_ and _refresh_ token.  Once this temporary code has been used once
@@ -53,7 +53,7 @@ has revoked access.  This makes things more secure and more scalable.
 Another important aspect of this flow is the concept of a _public_ vs. a _confidential_ client.  _Confidential_ clients are required
 to provide a client secret when they exchange the temporary codes for tokens.  _Public_ clients are not required to provide this client secret.
 _Public_ clients are perfectly fine so long as HTTPS is strictly enforced and you are very strict about what redirect URIs are registered for the
-client.  HTML5/JavaScript clients actually always have to be _public_ clients because there is no way to transmit the client secret to them in a secure
+client.  HTML5/JavaScript clients always have to be _public_ clients because there is no way to transmit the client secret to them in a secure
 manner.  Again, this is ok so long as you use HTTPS and strictly enforce redirect URI registration.  This guide goes more detail
 into this in the
 
@@ -64,7 +64,7 @@ into this in the
 This is a browser-based protocol that is similar to Authorization Code Flow except there are fewer requests and no refresh tokens involved.
 We do not recommend this flow as there remains the possibility of _access_ tokens being leaked in the browser history as tokens are transmitted
 via redirect URIs (see below).  Also, since this flow doesn't provide the client with a refresh token, access tokens would either have to
-be long-lived or users would have to re-authenticate when they expired.  This flow is supported because its in the OIDC and OAuth 2.0 specification.
+be long-lived or users would have to re-authenticate when they expired.  This flow is supported because it is in the OIDC and OAuth 2.0 specification.
 Here's a brief summary of the protocol:
 
 . Browser visits application.  The application notices the user is not logged in, so it redirects the browser to {{book.project.name}}
@@ -77,7 +77,7 @@ Here's a brief summary of the protocol:
 
 ===== Resource Owner Password Credentials Grant (Direct Grants)
 
-This is referred to in the Admin Console as _Direct Grants_ This is used by REST clients that want to obtain a token on behalf of a user.  It is one HTTP POST request that contains
+This is referred to in the Admin Console as _Direct Grants_. This is used by REST clients that want to obtain a token on behalf of a user.  It is one HTTP POST request that contains
 the credentials of the user as well as the id of the client and the client's secret (if it is a confidential client).  The user's credentials
 are sent within form parameters.  The HTTP response contains
 _identity_, _access_, and _refresh_ tokens.

topics/sso-protocols/saml-vs-oidc.adoc

@@ -2,12 +2,12 @@
 === OIDC vs. SAML
 
 Choosing between OIDC and SAML is not just a matter of using a newer, sexier protocol (OIDC) instead of the old, mature, dinosaur (SAML).
-{{book.project.name}} has chosen OIDC as the protocol we use to both recommend and write all our extensions on top of.
+{{book.project.name}} has chosen OIDC as the protocol we recommend.  It is also what we use with all of our extensions.
 SAML tends to be a bit more verbose than OIDC.
 
 Beyond verbosity of exchanged data, if you compare the specifications you'll find that OIDC was designed to work with the
 web while SAML was retrofitted to work on top of the web.  For example,
-OIDC is also much better suited for HTML5/JavaScript applications because it is
+OIDC is much better suited for HTML5/JavaScript applications because it is
 much much simpler to implement on the client side than SAML.  Since tokens are in the JSON format,
 they can be directly consumed by JavaScript.  Also, you'll find many nice little switches and features that
 make implementing security in your web applications easier.  For example, check out the iframe trick that the specification

topics/sso-protocols/saml.adoc

@@ -7,22 +7,22 @@ of WS-* specifications so it tends to be a bit more verbose than OIDC.  SAML 2.0
 that works by exchanging XML documents between the authentication server and the application.  XML signatures and encryption
 is used to verify requests and responses.
 
-In {{book.project.name}} SAML serves two types of use cases: browser applications and REST invocations.
+In {{book.project.name}}, SAML serves two types of use cases: browser applications and REST invocations.
 
-There is really two types of use cases when using SAML.  The first is an application that asks the {{book.project.name}} server to authenticate
+There are really two types of use cases when using SAML.  The first is an application that asks the {{book.project.name}} server to authenticate
 a user for them.  After a successful login, the application will receive an XML document that contains
 something called a SAML assertion that specify various attributes about the user.  This XML document is digitally signed by
 the realm and contains access information (like user role mappings) that the application can use to determine what resources the user
 is allowed to access on the application.
 
 The second type of use cases is that of a client that wants to gain access to remote services.  In this case, the client asks {{book.project.name}}
-to obtain an SAML assertion it can use to invoke on other remote services on behalf of the user.
+to obtain a SAML assertion it can use to invoke on other remote services on behalf of the user.
 
 ==== SAML Bindings
 
 SAML defines a few different ways to exchange XML documents when executing the authentication protocol.  The _Redirect_ and _Post_ bindings
 cover browser based applications.  The _ECP_ binding covers REST invocations.  There are other binding types but {{book.project.name}} only
-supports those 3.
+supports those three.
 
 ===== Redirect Binding
 
@@ -31,14 +31,14 @@ how it works.
 
 . The user visits the application and the application finds the user is not authenticated.  It generates an XML authentication
   request document and encodes it as a query param in a URI that is used to redirect to the {{book.project.name}} server.
-  Depending on your settings, the application may also digitally sign this XML document and also stuffs this signature as a query
+  Depending on your settings, the application may also digitally sign this XML document and also stuff this signature as a query
-  param in the redirect URI to {{book.project.name}}.  This is signature is used to validate the client that sent this
+  param in the redirect URI to {{book.project.name}}.  This signature is used to validate the client that sent this
   request.
 . The browser is redirected to {{book.project.name}}.  The server extracts the XML auth request document and verifies
-  the digital signature if required.  The user then has to enter in their credentials to be authenticated
+  the digital signature if required.  The user then has to enter in their credentials to be authenticated.
 . After authentication, the server generates an XML authentication response document.  This document contains
-  a SAML assertion that holds metadata about the user like name, address, email, and also an role mappings the user
+  a SAML assertion that holds metadata about the user like name, address, email, and any role mappings the user
-  might have.  This document is almost always digitally signed and using XML signatures, and may also be encrypted.
+  might have.  This document is almost always digitally signed using XML signatures, and may also be encrypted.
 . The XML auth response document is then encoded as a query param in a redirect URI that brings the browser back
   to the application.  The digital signature is also included as a query param.
 . The application receives the redirect URI and extracts the XML document and verifies the realm's signature to make
@@ -47,7 +47,7 @@ how it works.
 
 ===== POST Binding
 
-The SAML _POST_ binding works almost the exact same way as the _Redirect_ Binding, but instead of GET requests, XML
+The SAML _POST_ binding works almost the exact same way as the _Redirect_ binding, but instead of GET requests, XML
 documents are exchanged by POST requests.  The _POST_ Binding uses JavaScript to trick the browser into making a POST request to
 the {{book.project.name}} server or application when exchanging documents.  Basically HTTP responses contain an HTML document
 that contains an HTML form with embedded JavaScript.  When the page is loaded, the JavaScript automatically invokes the form.