libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases Packages Activity Actions

Vault Guide v1 (#9772)

Browse source 
* Vault Guide v1

Containing only Kubernetes / OpenShift  secrets via file based vault for now

Closes #9462

* Apply suggestions from code review

Co-authored-by: Andrea Peruffo <andrea.peruffo1982@gmail.com>

Co-authored-by: Andrea Peruffo <andrea.peruffo1982@gmail.com>
This commit is contained in:
Dominik Guhr 2022-01-27 11:18:50 +01:00 committed by GitHub
parent 47ad9a29eb
commit 6395e89cfc
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 59 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

59
docs/guides/src/main/server/vault.adoc Normal file
View file

@ -0,0 +1,59 @@
<#import "/templates/guide.adoc" as tmpl>
<#import "/templates/kc.adoc" as kc>
<@tmpl.guide
title="Using Kubernetes Secrets"
summary="Learn how to use Kubernetes / OpenShift secrets in Keycloak"
priority=30
includedOptions="vault vault-*">
Keycloak supports a file based vault implementation for Kubernetes / OpenShift secrets. Mount Kubernetes secrets into the Keycloak Container, and the data fields will be available in the mounted folder with a flat-file structure.
== Available integrations
You can use Kubernetes / OpenShift secrets for the following use-cases:
* Obtain the SMTP Mail server Password
* Obtain the LDAP Bind Credential when using LDAP-based User Federation
* Obtain the OIDC identity providers Client Secret when integrating external identity providers
== Enabling the vault
Enable the file based vault by building Keycloak using the following build option:
<@kc.build parameters="--vault=file"/>
== Setting the base directory to lookup secrets
Kubernetes / OpenShift secrets are basically mounted files, so you have to configure a directory for these files to be mounted in:
<@kc.start parameters="--vault-dir=/my/path"/>
== Realm-specific secret files
Kubernetes / OpenShift Secrets are used per-realm basis in Keycloak, so there's a naming convention for the file in place:
[source, bash]
----
${r"${vault.<realmname>_<secretname>}"}
----
=== Using underscores in the Name
In order to process the secret correctly, it is needed to double all underscores in the <realmname> or the <secretname>, separated by a single underscore.
.Example
* Realm Name: `sso_realm`
* Desired Name: `ldap_credential`
* Resulting file Name:
[source, bash]
----
sso__realm_ldap__credential
----
Note the doubled underscores between __sso__ and __realm__ and also between __ldap__ and __credential__.
== Example: Use an LDAP bind credential secret in the admin console
.Example setup
* A realm named `secrettest`
* A desired Name `ldapBc` for the bind Credential
* Resulting file name: `secrettest_ldapBc`
.Usage in admin console
You can then use this secret from the admin console by using `${r"${vault.ldapBc}"}` as value for the `Bind Credential` when configuring your LDAP User federation.
</@tmpl.guide>