Oidckube functions as a wrapper around minikube that will initialize, deploy, and partially configure the instance to use Keycloak; an Open Source Identity and Access Management tool as an Authentication Source. The Keycloak manifests are based off the Keycloak Helm Chart.
NOTE: This script only supports Virtualbox as the virtualization provider for minikube. If the cfssl and jq
requirements are not found, it will attempt to download and install them locally into the
- Within the project directory, create a
configfile based off the supplied config example (
config.example). If you opt to forgo doing so, one based off the
config.examplefile will be generated automatically. This file is used by both
login.shto configure and authenticate to Keycloak.
||Address for the locally deployed instance of Keycloak|
||Name of the realm within Keycloak used for Kubernetes Authentication|
||Name of the OIDC client used for Kubernetes Authentication|
||OIDC Secret associated with the Client ID. NOTE: This cannot be populated ahead of time, and is is generated by Keycloak itself.|
./oidckube.sh init. This will automate the certificate generation, CA certificate insertion, deploy Keycloak, and configure minikube to use the Host's DNS resolver.
- Modify your system's
/etc/hostsfile with the information printed out from the previous step. This will allow both your host and minikube instance to reference the
- Login to keycloak administrator portal by going to
https://keycloak.devlocal, and use the credentials
keycloakNOTE: Keycloak takes a few moments to start after minikube comes up and may not be immediately accessible once booted.
- Create a new auth realm using the same name as defined in the
KEYCLOAK_AUTH_REALMconfig. NOTE: If you are using the default config, at this time you may import the
k8s-realm-example.jsonto skip the group and client configuration (you will however have to generate a new client secret). For the import, select only
Import clients, and
Import client roles, then set it to
skipif the resource already exists.
- Navigate to the
clientssection and create a new client.
- Give it the same name as defined in the
- At the new client configuration page, If you'd like to change the Authorization type from
Access Typeto be
confidential, and configure the
Valid Redirect URIto be
https://<KEYCLOAK_ADDRESS>/*. Then press
Save. Otherwise, you may leave it as is. If you did change it to
Confidential, click on the Credentials Tab and generate a new secret, then copy the Secret and update the config file setting
KEYCLOAK_CLIENT_SECRETto the newly generated value.
- Click on the
MappersTab and then
- Call this new mapping
groups, set the
Token Claim Nameto
groups, then save.
- Add a second Mapping, called
email_verified. Set the
Hardcoded claim, the
Token Claim Nameto
Claim JSON Typeto
boolean. This is ONLY required in versions of Kubernetes less than 1.11. For information regarding this claim, see this Github Issue: kubernetes/kubernetes#59496.
- Navigate to the
Groupssection and create 2 new groups:
cluster-admins. These map to the cluster role bindings created during initialization (
Usersand create two new users giving them fake emails e.g.
firstname.lastname@example.org, assigning them a password under the
Credentialstab, and lastly add one to each of the groups created in the previous step. At this point, Keycloak is now configured. NOTE: If you would like to assign the user an optional TOTP, you may impersonate them from the
Usersview and configure their
- Shut down the VM with
./oidckube.sh stop. This is needed to reconfigure the
./oidckube.sh startto start the minikube instance up with the generated OIDC config. Give it time to fully boot up.
./login.sh. It will prompt you for a username, password and an optional TOTP code. Use the email address of one of the accounts created earlier. the
./login.shscript will add the user automatically to your kube config.
- Create a new context using the newly added account. e.g:
$ kubectl config set-context oidckube-user --cluster=minikube --email@example.com --namespace=default <or> $ kubectl config set-context oidckube-admin --cluster=minikube --firstname.lastname@example.org --namespace=default
Both the instance of minikube and your local client should be configured to use oidc for server authentication.
The cluster role bindings map the group
cluster-users to the
view cluster role, and
cluster-admins to the