From cbbae874b20c20ef496f4b461f048fe45a15d2cb Mon Sep 17 00:00:00 2001 From: mposolda Date: Tue, 4 Oct 2016 19:07:07 +0200 Subject: [PATCH] KEYCLOAK-3564 Docs for key rotation on OIDC clients and identity providers --- topics/clients/oidc/confidential.adoc | 7 +++++++ topics/identity-broker/oidc.adoc | 17 +++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/topics/clients/oidc/confidential.adoc b/topics/clients/oidc/confidential.adoc index fb302bdf6b..198328a6c2 100644 --- a/topics/clients/oidc/confidential.adoc +++ b/topics/clients/oidc/confidential.adoc @@ -38,4 +38,11 @@ image:../../../{{book.images}}/import-client-cert.png[] 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. +Finally note that you don't even need to import certificate if you choose to `Use JWKS URL` . In that case, you can provide the URL where +client publishes it's public key in https://self-issued.info/docs/draft-ietf-jose-json-web-key.html[JWK] format. This is flexible because when +client changes it's keys, {{book.project.name}} will automatically download them without need to re-import anything on {{book.project.name}} side. + +If you use client secured by {{book.project.name}} adapter, you can configure the JWKS URL like https://myhost.com/myapp/k_jwks assuming that https://myhost.com/myapp is the +root URL of your client application. See {{book.developerguide.link}}[{{book.developerguide.name}}] for additional details. + diff --git a/topics/identity-broker/oidc.adoc b/topics/identity-broker/oidc.adoc index d72daf8f1d..b89d0ab7f1 100644 --- a/topics/identity-broker/oidc.adoc +++ b/topics/identity-broker/oidc.adoc @@ -49,6 +49,23 @@ You must define the OpenID Connection configuration options as well. They basic |Prompt |Another optional switch. This is the prompt parameter defined by the OIDC specification. Through it you can force re-authentication and other options. See the specification for more details + +|Validate Signatures +|Another optional switch. This is to specify if {{book.project.name}} will verify the signatures on the external ID Token signed by this Identity provider. If this is on, +the {{book.project.name}} will need to know the public key of the external OIDC identity provider. See below for how to setup it. + +|Use JWKS URL +|Applicable just `Validate Signatures` is on. If the switch is on, then identity provider public keys will be downloaded from given JWKS URL. + This allows great flexibility because new keys will be always re-downloaded again when identity provider generates new keypair. If the switch is off, + then public key (or certificate) from the {{book.project.name}} DB is used, so when identity provider keypair changes, you always need to import new key to the {{book.project.name}} DB as well. + +|JWKS URL +|URL where identity provider keys in JWK format are stored. See https://self-issued.info/docs/draft-ietf-jose-json-web-key.html[JWK specification] for more details. + If you use external {{book.project.name}} identity provider, then you can use URL like http://broker-keycloak:8180/auth/realms/test/protocol/openid-connect/certs assuming your brokered + {{book.project.name}} is running on http://broker-keycloak:8180 and it's realm is `test` . + +|Validating Public Key +|Applicable if `Use JWKS URL` is off. Here is the public key in PEM format that must be used to verify external IDP signatures. |=== You can also import all this configuration data by providing a URL or file that points to OpenID Provider Metadata (see OIDC Discovery specification).