From b929edd2be7d80f92ee80fb399402a6c26cfd469 Mon Sep 17 00:00:00 2001 From: Hynek Mlnarik Date: Fri, 4 Nov 2016 21:43:30 +0100 Subject: [PATCH] KEYCLOAK-1881 - SAML key rotation at IdP side --- SUMMARY.adoc | 1 + .../idp_httpclient_subelement.adoc | 68 +++++++++++++++++++ .../general-config/idp_keys_subelement.adoc | 31 ++++++++- .../idp_singlesignonservice_subelement.adoc | 1 + 4 files changed, 98 insertions(+), 3 deletions(-) create mode 100644 topics/saml/java/general-config/idp_httpclient_subelement.adoc diff --git a/SUMMARY.adoc b/SUMMARY.adoc index fba2af9105..ba5bd402c1 100644 --- a/SUMMARY.adoc +++ b/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] diff --git a/topics/saml/java/general-config/idp_httpclient_subelement.adoc b/topics/saml/java/general-config/idp_httpclient_subelement.adoc new file mode 100644 index 0000000000..bc19d4501c --- /dev/null +++ b/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 +<>. + +[source,xml] +---- + +---- + +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_. diff --git a/topics/saml/java/general-config/idp_keys_subelement.adoc b/topics/saml/java/general-config/idp_keys_subelement.adoc index 195d1564ea..c92cc3fafd 100644 --- a/topics/saml/java/general-config/idp_keys_subelement.adoc +++ b/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 <>. -But again, you only have to define one certificate or public key reference. +It is defined in the same way as the <>. +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 +<>. +Settings of the HTTP client that is used for SAML descriptor retrieval usually +needs no additional configuration, however it can be configured in the +<>. + +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] ---- diff --git a/topics/saml/java/general-config/idp_singlesignonservice_subelement.adoc b/topics/saml/java/general-config/idp_singlesignonservice_subelement.adoc index 3566510450..6166fc63f4 100644 --- a/topics/saml/java/general-config/idp_singlesignonservice_subelement.adoc +++ b/topics/saml/java/general-config/idp_singlesignonservice_subelement.adoc @@ -1,3 +1,4 @@ +[[_sp-idp-singlesignonservice]] ===== IDP SingleSignOnService sub element