Merge pull request #48 from hmlnarik/KEYCLOAK-1881

KEYCLOAK-1881 - SAML key rotation at IdP side
This commit is contained in:
Stian Thorgersen 2016-11-08 07:57:49 +01:00 committed by GitHub
commit 61cb030309
4 changed files with 98 additions and 3 deletions

View file

@ -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]

View file

@ -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_.

View file

@ -1,9 +1,34 @@
[[_sp-idp-keys]]
===== 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>>.
But again, you only have to define one certificate or public key reference.
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. 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]
----

View file

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