On this page

External auth with Dex

Use Dex as an OIDC provider for both authentication and authorization to the Gloo UI.

notifications

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.
- docker, to run Dex as the local OIDC provider.
- kind to create a local Kubernetes cluster.
- krew, the Kubernetes plug-in manager.
- kubectl to manage Kubernetes clusters.
- openssl to generate certificates for your OIDC provider.
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.
Docker Helm
1. Create an OIDC provider with Dex. Note that Dex is added to the kind network so that the Kubernetes API server can reach the OIDC provider.
  docker run -p 5557:5557 -d --network=kind -v ${PWD}:/data:ro -v ${PWD}/ssl:/ssl:ro --name oidc ghcr.io/dexidp/dex:v2.31.0 dex serve /data/dex.yaml
2. Modify the /etc/hosts file so that the OIDC provider can be reached by using the issuer URL. Depending on your file system settings, you might need to run the following command with elevated permissions such as sudo.
  echo $(docker inspect oidc -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}') oidc| sudo tee -a /etc/hosts
  Example output:
  172.18.0.3 oidc
3. Make sure you can reach the OIDC provider.
  curl --cacert ssl/ca.pem https://oidc:5557/dex/.well-known/openid-configuration
1. Add the Dex Helm chart to your cluster.
  helm repo add dex https://charts.dexidp.io
2. Create a namespace for Dex.
  kubectl create namespace dex
3. Install Dex via Helm.
  helm upgrade --install dex dex/dex \ --namespace dex \ --values "${SCRIPT_DIR}/dex-helm-$SETUP-env-values.yaml"
4. Make sure that your deployment rolled out successfully.
  kubectl -n dex rollout status deployment dex

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 Gateway 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.12 sh -
export PATH=$HOME/.gloo-mesh/bin:$PATH

Install Gloo Mesh Gateway 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.glooGatewayLicenseKey=$GLOO_MESH_GATEWAY_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 the userMapping section in the Dashboard custom resource matches the cluster settings from the kindconfig.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 your dex.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 or user@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 the cluster-admin role, as described in the rbac.yaml file.
- user@example.com: This user can authenticate to the Gloo UI because the user is in the dex.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

External auth with Dex

Before you begin link

Create certificates for the OIDC provider link

Create a demo cluster and set up Dex as your OIDC provider link

Optional: Verify your OIDC setup link

Install Gloo Mesh Gateway and configure the Gloo UI for Dex link

Log in to the Gloo UI link

Demo cleanup link

Debug your demo setup link