Merge pull request #48 from hmlnarik/KEYCLOAK-1881

KEYCLOAK-1881 - SAML key rotation at IdP side

SUMMARY.adoc

@@ -59,6 +59,7 @@
  .... link:topics/saml/java/general-config/idp_singlesignonservice_subelement.adoc[IDP SingleSignOnService sub element]
  .... link:topics/saml/java/general-config/idp_singlelogoutservice_subelement.adoc[IDP SingleLogoutService sub element]
  .... link:topics/saml/java/general-config/idp_keys_subelement.adoc[IDP Keys subelement]
+ .... link:topics/saml/java/general-config/idp_httpclient_subelement.adoc[IDP HttpClient subelement]
  ... link:topics/saml/java/jboss-adapter.adoc[JBoss EAP/Wildfly Adapter]
  .... link:topics/saml/java/jboss-adapter/jboss_adapter_installation.adoc[Adapter Installation]
  .... link:topics/saml/java/jboss-adapter/required_per_war_configuration.adoc[Per WAR Configuration]

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

@@ -0,0 +1,68 @@
+[[_sp-idp-httpclient]]
+
+===== IDP HttpClient sub element
+
+The `HttpClient` optional sub element defines the properties of HTTP client used
+for automatic obtaining of certificates containing public keys for IDP signature
+verification via SAML descriptor of the IDP when
+<<fake/../../../../saml/java/general-config/idp-keys_subelement.adoc#_sp-idp-keys-automatic,enabled>>.
+
+[source,xml]
+----
+<HttpClient connectionPoolSize="10"
+            disableTrustManager="false"
+            allowAnyHostname="false"
+            clientKeystore="classpath:keystore.jks"
+            clientKeystorePassword="pwd"
+            truststore="classpath:truststore.jks"
+            truststorePassword="pwd"
+            proxyUrl="http://proxy/" />
+----
+
+connectionPoolSize::
+  Adapters will make separate HTTP invocations to the {{book.project.name}} server to turn an access code into an access token.
+  This config option defines how many connections to the {{book.project.name}} server should be pooled.
+  This is _OPTIONAL_.
+  The default value is `10`.
+
+disableTrustManager::
+  If the {{book.project.name}} server requires HTTPS and this config option is set to `true` you do not have to specify a truststore.
+  This setting should only be used during development and *never* in production as it will disable verification of SSL certificates.
+  This is _OPTIONAL_.
+  The default value is `false`.
+
+allowAnyHostname::
+  If the {{book.project.name}} server requires HTTPS and this config option is set to `true`
+  the {{book.project.name}} server's certificate is validated via the truststore,
+  but host name validation is not done.
+  This setting should only be used during development and *never* in production
+  as it will partly disable verification of SSL certificates.
+  This seting may be useful in test environments. This is _OPTIONAL_.
+  The default value is `false`.
+
+truststore::
+  The value is the file path to a keystore file.
+  If you prefix the path with `classpath:`, then the truststore will be obtained from the deployment's classpath instead.
+  Used for outgoing HTTPS communications to the {{book.project.name}} server.
+  Client making HTTPS requests need a way to verify the host of the server they are talking to.
+  This is what the trustore does.
+  The keystore contains one or more trusted host certificates or certificate authorities.
+  You can create this truststore by extracting the public certificate of the {{book.project.name}} server's SSL keystore. 
+  This is _REQUIRED_ unless `disableTrustManager` is `true`.
+
+truststorePassword::
+  Password for the truststore keystore.
+  This is _REQUIRED_ if `truststore` is set and the truststore requires a password.
+
+clientKeystore::
+  This is the file path to a keystore file.
+  This keystore contains client certificate for two-way SSL when the adapter makes HTTPS requests to the {{book.project.name}} server.
+  This is _OPTIONAL_.
+
+clientKeystorePassword::
+  Password for the client keystore and for the client's key.
+  This is _REQUIRED_ if `clientKeystore` is set.
+
+proxyUrl::
+  URL to HTTP proxy to use for HTTP connections.
+  This is _OPTIONAL_.

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

@@ -1,9 +1,34 @@
+[[_sp-idp-keys]]
 
-===== IDP Keys subelement
+===== IDP Keys sub element
 
 The Keys sub element of IDP is only used to define the certificate or public key to use to verify documents signed by the IDP.
-It is defined in the same way as the <<fake/../../../../saml/java/general-config/sp-keys.adoc#_saml-sp-keys,SP's Key's element>>.
+It is defined in the same way as the <<fake/../../../../saml/java/general-config/sp-keys.adoc#_saml-sp-keys,SP's Keys element>>.
-But again, you only have to define one certificate or public key reference.
+But again, you only have to define one certificate or public key reference. Note that, if both IDP and SP are realized by
+{{book.project.name}} server and adapter, respectively, there is no need to specify the keys for signature validation, see below.
+
+[[_sp-idp-keys-automatic]]
+It is possible to configure SP to obtain public keys for IDP signature validation
+from published certificates automatically, provided both SP and IDP are
+implemented by {{book.project.name}}.
+This is done by removing all declarations of signature validation keys in Keys
+sub element. If the Keys sub element would then remain empty, it can be omitted
+completely. The keys are then automatically obtained by SP from SAML descriptor,
+location of which is derived from SAML endpoint URL specified in the
+<<fake/../../../../saml/java/general-config/idp_singlesignonservice_subelement.adoc#_sp-idp-singlesignonservice,IDP SingleSignOnService sub element>>.
+Settings of the HTTP client that is used for SAML descriptor retrieval usually
+needs no additional configuration, however it can be configured in the
+<<fake/../../../../saml/java/general-config/idp_httpclient_subelement.adoc#_sp-idp-httpclient,IDP HttpClient sub element>>.
+
+It is also possible to specify multiple keys for signature verification. This is done by declaring multiple Key elements
+within Keys sub element that have `signing` attribute set to `true`.
+This is useful for example in situation when the IDP signing keys are rotated: There is
+usually a transition period when new SAML protocol messages and assertions are signed
+with the new key but those signed by previous key should still be accepted.
+
+It is not possible to configure {{book.project.name}} to both obtain the keys
+for signature verification automatically and define additional static signature
+verification keys.
 
 [source,xml]
 ----

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

@@ -1,3 +1,4 @@
+[[_sp-idp-singlesignonservice]]
 
 ===== IDP SingleSignOnService sub element