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 bin
sub-directory.
- Within the project directory, create a
config
file based off the supplied config example (config.example
). If you opt to forgo doing so, one based off theconfig.example
file will be generated automatically. This file is used by bothoidckube.sh
andlogin.sh
to configure and authenticate to Keycloak.
Variable | Default | Description |
---|---|---|
KEYCLOAK_ADDRESS |
keycloak.devlocal |
Address for the locally deployed instance of Keycloak |
KEYCLOAK_AUTH_REALM |
k8s |
Name of the realm within Keycloak used for Kubernetes Authentication |
KEYCLOAK_CLIENT_ID |
oidckube |
Name of the OIDC client used for Kubernetes Authentication |
KEYCLOAK_CLIENT_SECRET |
OIDC Secret associated with the Client ID. NOTE: This cannot be populated ahead of time, and is is generated by Keycloak itself. |
- Run
./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/hosts
file with the information printed out from the previous step. This will allow both your host and minikube instance to reference theKEYCLOAK_ADDRESS
. - Login to keycloak administrator portal by going to
https://<KEYCLOAK_ADDRESS>
e.g.https://keycloak.devlocal
, and use the credentialskeycloak
/keycloak
NOTE: 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_REALM
config. NOTE: If you are using the default config, at this time you may import thek8s-realm-example.json
to skip the group and client configuration (you will however have to generate a new client secret). For the import, select onlyImport groups
,Import clients
, andImport client roles
, then set it toskip
if the resource already exists. - Navigate to the
clients
section and create a new client. - Give it the same name as defined in the
KEYCLOAK_CLIENT_ID
config. - At the new client configuration page, If you'd like to change the Authorization type from
Public
toConfidential
change theAccess Type
to beconfidential
, and configure theValid Redirect URI
to behttps://<KEYCLOAK_ADDRESS>/*
. Then pressSave
. Otherwise, you may leave it as is. If you did change it toConfidential
, click on the Credentials Tab and generate a new secret, then copy the Secret and update the config file settingKEYCLOAK_CLIENT_SECRET
to the newly generated value. - Click on the
Mappers
Tab and thenCreate
. - Call this new mapping
groups
, set theMapper Type
toGroup Membership
andToken Claim Name
togroups
, then save. - Add a second Mapping, called
email_verified
. Set theMapper Type
toHardcoded claim
, theToken Claim Name
toemail_verified
,Claim value
totrue
, andClaim JSON Type
toboolean
. 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
Groups
section and create 2 new groups:cluster-users
andcluster-admins
. These map to the cluster role bindings created during initialization (manifests/crb-users.yaml
andmanifests/crb-admins.yaml
). - Goto
Users
and create two new users giving them fake emails e.g.[email protected]
and[email protected]
, assigning them a password under theCredentials
tab, 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 theUsers
view and configure theirAuthenticator
. - Shut down the VM with
./oidckube.sh stop
. This is needed to reconfigure thekube-apiserver
. - Run
./oidckube.sh start
to start the minikube instance up with the generated OIDC config. Give it time to fully boot up. - Run
./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.sh
script 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 protected] --namespace=default
<or>
$ kubectl config set-context oidckube-admin --cluster=minikube [email protected] --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
cluster-admin
role.