Merge pull request #7 from keycloak/master

sync with latest changes

topics/oidc/javascript-adapter.adoc

@@ -13,7 +13,7 @@ specific as possible.
 To use the JavaScript adapter you must first create a client for your application in the {{book.project.name}} Administration Console. Make sure `public`
 is selected for `Access Type`.
 
-You also need to configure valid redirect URIs and valid web origins. Be as specific as possible as failing to do so may results in a security vulnerability.
+You also need to configure valid redirect URIs and valid web origins. Be as specific as possible as failing to do so may result in a security vulnerability.
 
 Once the client is created click on the `Installation` tab select `Keycloak OIDC JSON` for `Format Option` then click on `Download`. The downloaded
 `keycloak.json` file should be hosted on your web server at the same location as your HTML pages.
@@ -44,7 +44,7 @@ If the `keycloak.json` file is in a different location you can specify it:
 var keycloak = Keycloak('http://localhost:8080/myapp/keycloak.json'));
 ----
 
-You can also skip the file altogether and manually configure the adapter:
+Alternatively, you can pass in a JavaScript object with the required configuration instead:
 
 [source,javascript]
 ----
@@ -122,7 +122,8 @@ your application.
 ==== Implicit and Hybrid Flow
 
 By default, the JavaScript adapter uses the http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code] flow.
-With this flow the {{book.project.name}} server returns a authorization code, not a authentication token, to the application. The JavaScript adapter exchanges
+
+With this flow the {{book.project.name}} server returns an authorization code, not an authentication token, to the application. The JavaScript adapter exchanges
 the `code` for an access token and a refresh token after the browser is redirected back to the application.
 
 {{book.project.name}} also supports the http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth[Implicit] flow where an access token
@@ -254,7 +255,7 @@ Redirects to login form on (options is an optional object with redirectUri and/o
 Options is an Object, where: 
 
 * redirectUri - Specifies the uri to redirect to after login.
-* prompt - Can be set to 'none' to check if the user is logged in already (if not logged in, a login form is not displayed).
+* prompt - By default the login screen is displayed if the user is not logged-in to {{book.project.name}}. To only authenticate to the application if the user is already logged-in and not display the login page if the user is not logged-in, set this option to `none`.
 * loginHint - Used to pre-fill the username/email field on the login form.
 * action - If value is 'register' then user is redirected to registration page, otherwise to login page.
 * locale - Specifies the desired locale for the UI.
@@ -288,13 +289,13 @@ Options is an Object, where:
 
 Redirects to registration form. Shortcut for login with option action = 'register'
 
-Options are same as login method but 'action' is set to 'register'
+Options are same as for the login method but 'action' is set to 'register'
 
 ====== createRegisterUrl(options)
 
 Returns the url to registration page. Shortcut for createLoginUrl with option action = 'register'
 
-Options are same as createLoginUrl method but 'action' is set to 'register'
+Options are same as for the createLoginUrl method but 'action' is set to 'register'
 
 ====== accountManagement()
 
@@ -368,4 +369,4 @@ The available events are:
 * onAuthRefreshSuccess - Called when the token is refreshed.
 * onAuthRefreshError - Called if there was an error while trying to refresh the token.
 * onAuthLogout - Called if the user is logged out (will only be called if the session status iframe is enabled, or in Cordova mode).
-* onTokenExpired - Called when access token expired. When this happens you can for example refresh token, or if refresh not available (ie. with implicit flow) you can redirect to login screen.
+* onTokenExpired - Called when the access token is expired. When this happens you can for refresh the token, or if refresh is not available (ie. with implicit flow) you can redirect to login screen.

topics/oidc/oidc-generic.adoc

@@ -11,10 +11,10 @@ The most important endpoint to know is the `well-known` configuration endpoint.
 Connect implementation in {{book.project.name}}. The endpoint is:
 
 ....
-/realms/REALM-NAME/.well-known/openid-configuration
+/realms/{realm-name}/.well-known/openid-configuration
 ....
 
-To get the full URL add the base URL for {{book.project.name}} and replace `REALM-NAME` with the name of your realm. For example:
+To get the full URL add the base URL for {{book.project.name}} and replace `{realm-name}` with the name of your realm. For example:
 
 $$http://localhost:8080/auth/realms/master/.well-known/openid-configuration$$
 
@@ -22,7 +22,7 @@ Some RP libraries will retrieve all required endpoints from this endpoint, but f
 
 ===== Authorization Endpoint
 ....
-/realms/master/protocol/openid-connect/auth
+/realms/{realm-name}/protocol/openid-connect/auth
 ....
 
 Performs authentication of the end-user. This is done by redirecting user agent to this endpoint.
@@ -31,7 +31,7 @@ For more details see http://openid.net/specs/openid-connect-core-1_0.html#Author
 
 ===== Token Endpoint
 ....
-/realms/master/protocol/openid-connect/token
+/realms/{realm-name}/protocol/openid-connect/token
 ....
 
 Used to obtain tokens. Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used.
@@ -41,7 +41,7 @@ For more details see http://openid.net/specs/openid-connect-core-1_0.html#TokenE
 
 ===== Userinfo Endpoint
 ....
-/realms/master/protocol/openid-connect/userinfo
+/realms/{realm-name}/protocol/openid-connect/userinfo
 ....
 
 Returns standard claims about the authenticated user. Protected by a bearer token.
@@ -50,7 +50,7 @@ For more details see http://openid.net/specs/openid-connect-core-1_0.html#UserIn
 
 ===== Logout Endpoint
 ....
-/realms/master/protocol/openid-connect/logout
+/realms/{realm-name}/protocol/openid-connect/logout
 ....
 
 Logs out the authenticated user.
@@ -62,7 +62,7 @@ required to authenticate the client.
 
 ===== Certificate Endpoint
 ....
-/realms/master/protocol/openid-connect/certs
+/realms/{realm-name}/protocol/openid-connect/certs
 ....
 
 Public key used by realm encoded as a JSON Web Key (JWK). This key can be used to verify tokens issued by {{book.project.name}} without making invocations to
@@ -72,7 +72,7 @@ For more details see https://tools.ietf.org/html/rfc7517[JSON Web Key specificat
 
 ===== Introspection Endpoint
 ....
-/realms/master/protocol/openid-connect/token/introspect
+/realms/{realm-name}/protocol/openid-connect/token/introspect
 ....
 
 Used to retrieve the active state of a token. Protected by a bearer token and can only be invoked by confidential clients.
@@ -81,7 +81,7 @@ For more details see https://tools.ietf.org/html/rfc7662[OAuth 2.0 Token Introsp
 
 ===== Dynamic Client Registration Endpoint
 ....
-/realms/master/clients-registrations/openid-connect
+/realms/{realm-name}/clients-registrations/openid-connect
 ....
 
 Used to dynamically register clients.
@@ -95,8 +95,8 @@ https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dyn
 ===== Authorization Code
 
 The Authorization Code flow redirects the user agent to {{book.project.name}}. Once the user has successfully authenticated with {{book.project.name}} an
-Authorization Code is created and the user agent is redirected back to the application. The application then uses the authorization code to along with its
-credentials to obtain an Access Roken, Refresh Token and ID Token from {{book.project.name}}.
+Authorization Code is created and the user agent is redirected back to the application. The application then uses the authorization code along with its
+credentials to obtain an Access Token, Refresh Token and ID Token from {{book.project.name}}.
 
 The flow is targeted towards web applications, but is also recommended for native applications, including mobile applications, where it is possible to embed
 a user agent.
@@ -133,7 +133,7 @@ There are a number of limitations of using this flow, including:
 * No support for identity brokering or social login
 * Flows are not supported (user self-registration, required actions, etc.)
 
-For a client to be permitted to use the Resource Owner Password Credentials grant the client has to have `Direct Access Grants Enabled` enabled.
+For a client to be permitted to use the Resource Owner Password Credentials grant the client has to have the `Direct Access Grants Enabled` option enabled.
 
 This flow is not included in OpenID Connect, but is a part of the OAuth 2.0 specification.
 

topics/saml/java/general-config/idp_element.adoc

@@ -16,7 +16,7 @@ Everything in the IDP element describes the settings for the identity provider (
 Here are the attribute config options you can specify within the `IDP` element declaration.
 
 entityID::
-  This is the issuer ID of the IDP. This setting is _REQUIRED._.
+  This is the issuer ID of the IDP. This setting is _REQUIRED_.
 
 signaturesRequired::
   If set to `true`, the client adapter will sign every document it sends to the IDP.
@@ -29,6 +29,6 @@ signatureAlgorithm::
   This setting is _OPTIONAL_
   and defaults to `RSA_SHA256`.
 signatureCanonicalizationMethod::
-  This is the signature canonicalization method that the IDP expects signed documents to use.  This setting is  _OPTIONAL._.
+  This is the signature canonicalization method that the IDP expects signed documents to use.  This setting is  _OPTIONAL_.
   The default value is `http://www.w3.org/2001/10/xml-exc-c14n#` and should be good for most IDPs.         
 

topics/saml/java/general-config/idp_singlelogoutservice_subelement.adoc

@@ -17,25 +17,25 @@ to the IDP formatted via the settings within this element when it wants to logou
 ----
 
 signRequest::
-  Should the client sign logout requests it makes to the IDP? This setting _OPTIONAL._.
+  Should the client sign logout requests it makes to the IDP? This setting is _OPTIONAL_.
   Defaults to whatever the IDP `signaturesRequired` element value is. 
 
 signResponse::
-  Should the client sign logout responses it sends to the IDP requests? This setting _OPTIONAL._.
+  Should the client sign logout responses it sends to the IDP requests? This setting is _OPTIONAL_.
   Defaults to whatever the IDP `signaturesRequired` element value is. 
 
 validateRequestSignature::
-  Should the client expect signed logout request documents from the IDP? This setting is _OPTIONAL._ Defaults to whatever the IDP `signaturesRequired` element value is.
+  Should the client expect signed logout request documents from the IDP? This setting is _OPTIONAL_. Defaults to whatever the IDP `signaturesRequired` element value is.
 
 validateResponseSignature::
-  Should the client expect signed logout response documents from the IDP? This setting is _OPTIONAL._ Defaults to whatever the IDP `signaturesRequired` element value is.
+  Should the client expect signed logout response documents from the IDP? This setting is _OPTIONAL_. Defaults to whatever the IDP `signaturesRequired` element value is.
 
 requestBinding::
-  This is the SAML binding type used for communicating SAML requests to the IDP.  This setting is  _OPTIONAL._.
+  This is the SAML binding type used for communicating SAML requests to the IDP. This setting is _OPTIONAL_.
   The default value is `POST`, but you can set it to REDIRECT as well.
 
 responseBinding::
-  This is the SAML binding type used for communicating SAML responses to the IDP The values of this can be `POST` or `REDIRECT`.  This setting is _OPTIONAL._.
+  This is the SAML binding type used for communicating SAML responses to the IDP. The values of this can be `POST` or `REDIRECT`.  This setting is _OPTIONAL_.
   The default value is `POST`, but you can set it to `REDIRECT` as well.
 
 postBindingUrl::

topics/saml/java/general-config/idp_singlesignonservice_subelement.adoc

@@ -17,23 +17,23 @@ to the IDP formatted via the settings within this element when it wants to login
 Here are the config attributes you can define on this element:
 
 signRequest::
-  Should the client sign authn requests? This setting is _OPTIONAL._.
+  Should the client sign authn requests? This setting is _OPTIONAL_.
   Defaults to whatever the IDP `signaturesRequired` element value is. 
 
 validateResponseSignature::
   Should the client expect the IDP to sign the assertion response document sent back from an auhtn request?
-  This setting _OPTIONAL._ Defaults to whatever the IDP `signaturesRequired` element value is.
+  This setting _OPTIONAL_. Defaults to whatever the IDP `signaturesRequired` element value is.
 
 requestBinding::
-  This is the SAML binding type used for communicating with the IDP.  This setting is _OPTIONAL._.
+  This is the SAML binding type used for communicating with the IDP.  This setting is _OPTIONAL_.
   The default value is `POST`, but you can set it to `REDIRECT` as well.
 
 responseBinding::
   SAML allows the client to request what binding type it wants authn responses to use.
-  The values of this can be `POST` or `REDIRECT`.  This setting is _OPTIONAL._.
+  The values of this can be `POST` or `REDIRECT`.  This setting is _OPTIONAL_.
   The default is that the client will not request a specific binding type for responses. 
 
 bindingUrl::
-  This is the URL for the IDP login service that the client will send requests to. This setting is _REQUIRED._.
+  This is the URL for the IDP login service that the client will send requests to. This setting is _REQUIRED_.
 
 

topics/saml/java/general-config/sp-keys.adoc

@@ -7,7 +7,7 @@ For client signed documents you must define both the private and public key or c
 For encryption, you only have to define the private key that will be used to decrypt. 
 
 There are two ways to describe your keys.
-They can be stored within a Java KeyStore or you can  or you can cut and paste the keys directly within `keycloak-saml.xml` in the PEM format.
+They can be stored within a Java KeyStore or you can copy/paste the keys directly within `keycloak-saml.xml` in the PEM format.
 
 [source,xml]
 ----

topics/saml/java/general-config/sp-keys/keystore_element.adoc

@@ -21,14 +21,14 @@ a `KeyStore` element.
 Here are the XML config attributes that are defined with the `KeyStore` element.
 
 file::
-  File path to the key store. _OPTIONAL._  The file or resource attribute must be set. 
+  File path to the key store. This option is _OPTIONAL_.  The file or resource attribute must be set. 
 
 resource::
   WAR resource path to the KeyStore.
-  This is a path used in method call to ServletContext.getResourceAsStream(). _OPTIONAL._  The file or resource attribute must be set. 
+  This is a path used in method call to ServletContext.getResourceAsStream(). This option is _OPTIONAL_.  The file or resource attribute must be set. 
 
 password::
-  The password of the KeyStore _REQUIRED._                                        
+  The password of the KeyStore. This option is _REQUIRED_.
 
 If you are defining keys that the SP will use to sign document, you must also specify references to your private keys
 and certificates within the Java KeyStore.

topics/saml/java/general-config/sp_element.adoc

@@ -16,7 +16,7 @@ Here is the explanation of the SP element attributes
 ----
 entityID::
   This is the identifier for this client.
-  The IDP needs this value to determine who the client is that is communicating with it. This setting _REQUIRED._
+  The IDP needs this value to determine who the client is that is communicating with it. This setting is _REQUIRED_.
 
 sslPolicy::
   This is the SSL policy the adapter will enforce.
@@ -24,28 +24,28 @@ sslPolicy::
   For `ALL`, all requests must come in via HTTPS.
   For `EXTERNAL`, only non-private IP addresses must come over the wire via HTTPS.
   For `NONE`, no requests are required to come over via HTTPS.
-  This is _OPTIONAL._ and defaults to `EXTERNAL`.
+  This settings is _OPTIONAL_. Default value is `EXTERNAL`.
 
 nameIDPolicyFormat::
   SAML clients can request a specific NameID Subject format.
   Fill in this value if you want a specific format.
-  It must be a standard SAML format identifier, i.e. `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`
-  This setting is _OPTIONAL._.
+  It must be a standard SAML format identifier, i.e. `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`.
+  This setting is _OPTIONAL_.
   By default, no special format is requested. 
 
 forceAuthentication::
   SAML clients can request that a user is re-authenticated even if they are already logged in at the IDP.
-  Set this to `true` if you want this. This setting is _OPTIONAL._.
-  Set to `false` by default. 
+  Set this to `true` to enable. This setting is _OPTIONAL_.
+  Default value is `false`.
 
 isPassive::
   SAML clients can request that a user is never asked to authenticate even if they are not logged in at the IDP.
   Set this to `true` if you want this.
-  Do not use together with `forceAuthentication` as they are opposite. This setting is _OPTIONAL._.
-  It is set to `false` by default.
+  Do not use together with `forceAuthentication` as they are opposite. This setting is _OPTIONAL_.
+  Default value is `false`.
 
 turnOffChangeSessionIdOnLogin::
-  The session id is changed by default on a successful login on some platforms to plug a security attack vector (Tomcat 8, Jetty9, Undertow/Wildfly).
-  Change this to `true` if you want to turn this off.  It is recommended you do not turn it off.
-  The default value is `false`.
+  The session id is changed by default on a successful login on some platforms to plug a security attack vector.
+  Change this to `true` to disable this.  It is recommended you do not turn it off.
+  Default value is `false`.
 

topics/saml/java/idp-registration.adoc

@@ -3,3 +3,4 @@
 
 For each servlet based adapter, the endpoint you register for the assert consumer service url and and single logout service
 must be the base url of your servlet application with `/saml` appended to it i.e. `$$https://example.com/contextPath/saml$$`
+

topics/saml/java/jboss-adapter.adoc

@@ -1,8 +1,19 @@
 [[_saml-jboss-adapter]]
 
-==== JBoss/Wildfly Adapter
+{% if book.community %}
+==== JBoss EAP/Wildfly Adapter
+{% endif %}
+{% if book.product %}
+==== JBoss EAP Adapter
+{% endif %}
+
+{% if book.community %}
+To be able to secure WAR apps deployed on JBoss EAP or Wildfly, you must install and configure the {{book.project.name}} SAML Adapter Subsystem.
+{% endif %}
+{% if book.product %}
+To be able to secure WAR apps deployed on JBoss EAP, you must install and configure the {{book.project.name}} SAML Adapter Subsystem.
+{% endif %}
 
-To be able to secure WAR apps deployed on JBoss EAP 6.x or Wildfly, you must install and configure the {{book.project.name}} SAML Adapter Subsystem.
 You then provide a keycloak config, `/WEB-INF/keycloak-saml.xml` file in your WAR and change the auth-method to KEYCLOAK-SAML within web.xml.
 Both methods are described in this section. 
 

topics/saml/java/jboss-adapter/required_per_war_configuration.adoc

@@ -4,7 +4,7 @@
 This section describes how to secure a WAR directly by adding config and editing files within your WAR package. 
 
 The first thing you must do is create a `keycloak-saml.xml` adapter config file within the `WEB-INF` directory of your WAR.
-The format of this config file is describe in the <<fake/../../../../saml/java/general-config.adoc#_saml-general-config,General Adapter Config>> section.
+The format of this config file is described in the <<fake/../../../../saml/java/general-config.adoc#_saml-general-config,General Adapter Config>> section.
 
 Next you must set the `auth-method` to `KEYCLOAK-SAML` in `web.xml`.
 You also have to use standard servlet security to specify role-base constraints on your URLs.