External auth with Dex
Use Dex as an OIDC provider for both authentication and authorization to the Gloo UI.
The following instructions are for Linux operating systems. The example uses kind for a demo Kubernetes cluster and Dex for the OIDC provider.
You can follow a similar process for your production setup. After you complete the demonstration steps, continue to the OIDC settings in Helm.
Before you begin
- Make sure that you install the following tools.
- Optional: Review the information about how authentication and authorization work with the Gloo UI.
Create certificates for the OIDC provider
You can test out these steps with a self-signed certificate that uses OpenSSL.
Download the gencerts.sh script.
Optional depending on your file settings: Give the script execution permissions.
cd ~/Downloads chmod +x ./gencerts.sh
Run the script.
./gencerts.sh
The script generates certificates for the OIDC provider in an
ssl
folder, such as in the following example.ls ssl/ ca-key.pem ca.pem cert.pem csr.pem key.pem req.cnf
Create a demo cluster and set up Dex as your OIDC provider
Set up Dex as the OIDC provider for your Kubernetes cluster. To unify authentication and authorization, the cluster’s OIDC provider must match the provider that you want to use to authenticate to the Gloo UI.
- Download the
kindconfig.yaml
configuration file. Note that the API server is set up with the Dex OIDC information. - Create a Kubernetes cluster locally with the kind configuration file.
kind create cluster --config=kindconfig.yaml
- Download the
dex.yaml
configuration file. This configuration file refers to the certificates that you previously generated. It also configures the redirect URLs for accessing the Gloo UI on the local host. - Run Dex as the OIDC provider for your cluster. You can choose to run Dex via a Docker command, or install Dex as a deployment in your cluster via Helm.
Optional: Verify your OIDC setup
You can check that your OIDC setup works by enforcing your kubectl
CLI client to authenticate with Dex.
- To log in to Kubernetes with an OIDC provider and
kubectl
, install the OIDC login plug-in.kubectl krew install oidc-login
- Set up the OIDC credentials with the OIDC client information that you previously generated from the script.
kubectl oidc-login setup --oidc-issuer-url=https://oidc:5557/dex --oidc-client-id=kuberentes --oidc-client-secret=ZXhhbXBsZS1hcHAtc2VjcmV0 --certificate-authority=${PWD}/ssl/ca.pem --oidc-extra-scope=email
- Follow the steps that the plug-in suggests. In particular, add the user’s OIDC access tokens to your
kubectl
config.kubectl config set-credentials oidc-user \ --exec-api-version=client.authentication.k8s.io/v1beta1 \ --exec-command=kubectl \ --exec-arg=oidc-login \ --exec-arg=get-token \ --exec-arg=--oidc-issuer-url=https://oidc:5557/dex \ --exec-arg=--oidc-client-id=kubernetes \ --exec-arg=--oidc-client-secret=ZXhhbXBsZS1hcHAtc2VjcmV0 \ --exec-arg=--oidc-extra-scope=email \ --exec-arg=--certificate-authority=${PWD}/ssl/ca.pem
- Check that your user can view the Kubernetes resources he was granted access to with cluster RBAC rules.
kubectl --user oidc-user get pods
Install Gloo Mesh Core and configure the Gloo UI for Dex
The following steps are for a demonstration setup only.
- Install the latest version of
meshctl
.curl -sL https://run.solo.io/meshctl/install | GLOO_MESH_VERSION=v2.5.10 sh - export PATH=$HOME/.gloo-mesh/bin:$PATH
- Install Gloo Mesh Core in your kind cluster with the following settings.
meshctl install --profiles gloo-core-single-cluster \ --set common.cluster=kind \ --set common.devMode=true \ --set common.verbose=true \ --set common.insecure=true \ --set common.cluster=$CLUSTER_NAME \ --set licensing.glooMeshCoreLicenseKey=$GLOO_MESH_CORE_LICENSE_KEY \ --set glooAgent.relay.serverAddress=gloo-mesh-mgmt-server.gloo-mesh.svc.cluster.local:9900 \
- Create a ConfigMap with the root CA.
kubectl create configmap -n gloo-mesh oidc-root-ca --from-file=ca.crt=ssl/ca.pem
- Download the
dashboard-settings.yaml
configuration file, to make the Gloo UI use the same OIDC provider and settings as the Kubernetes cluster. Note theuserMapping
section in theDashboard
custom resource matches the cluster settings from thekindconfig.yaml
file that you previously downloaded. For more options, see the API documentation.apiVersion: admin.gloo.solo.io/v2 kind: Dashboard metadata: name: settings namespace: gloo-mesh spec: authz: multiClusterRbac: {} authn: oidc: caCertConfigmapName: oidc-root-ca userMapping: usernameClaim: "email" usernamePrefix: "oidc:" appUrl: http://localhost:8090/ clientId: dashboard clientSecretName: dashboard issuerUrl: https://oidc:5557/dex scopes: - openid - profile - email --- apiVersion: v1 kind: Secret metadata: name: dashboard namespace: gloo-mesh stringData: oidc-client-secret: ZXhhbXBsZS1hcHAtc2VjcmV0
- Apply the dashboard configuration to your cluster.
kubectl apply -f dashboard-settings.yaml
- Download the Kubernetes
rbac.yaml
configuration file to give permissions to your OIDC users. Note that the configuration is for one user that matches yourdex.yaml
configuration,admin@example.com
.kind: ClusterRoleBinding apiVersion: rbac.authorization.k8s.io/v1 metadata: name: oidc-admin subjects: - kind: User name: oidc:admin@example.com roleRef: kind: ClusterRole name: cluster-admin apiGroup: rbac.authorization.k8s.io
- Apply the RBAC configuration to your cluster.
kubectl apply -f rbac.yaml
Log in to the Gloo UI
Test that authentication and authorization with Dex work in the Gloo UI.
- Open a port on your local machine to access the Gloo UI.
kubectl port-forward -n gloo-mesh deploy/gloo-mesh-ui 8090
- Open the Gloo UI in your browser: http://localhost:8090.
- Log in to the Gloo UI with your OIDC-provided users,
admin@example.com
oruser@example.com
. The different users have different views, depending on their RBAC permissions.admin@example.com
: This user can authenticate to the Gloo UI. Additionally, the user is authorized to all resources by thecluster-admin
role, as described in therbac.yaml
file.user@example.com
: This user can authenticate to the Gloo UI because the user is in thedex.yaml
OIDC configuration. However, without an RBAC role, the user is not authorized to view any resources in the Gloo UI.
Demo cleanup
To clean up the resources from your local machine, run the following commands.
docker rm -f oidc
kind delete cluster
rm -rf ssl
Debug your demo setup
To troubleshoot connection problems between the OIDC provider and your cluster, review the Kubernetes API server logs.
docker exec -ti kind-control-plane crictl ps
APISERVERID="$(docker exec -ti kind-control-plane crictl ps --name kube-apiserver -q|tr -d '\r')"
docker exec -ti kind-control-plane crictl logs "$APISERVERID"
To check the OIDC token that kubectl
uses, run the following command from the directory where you generated the ssl
folder with the gencerts.sh
script.
kubectl oidc-login get-token --oidc-issuer-url=https://oidc:5557/dex --oidc-client-id=kuberentes --oidc-client-secret=ZXhhbXBsZS1hcHAtc2VjcmV0 --oidc-extra-scope=email --certificate-authority=${PWD}/ssl/ca.pem