Dex configuration reference for Lokomotive

Introduction

Dex is an OpenID Connect (OIDC) and OAuth 2.0 provider with connectors to many other identity providers such as GitHub, Google or LDAP.

Dex acts as a portal to other identity providers through “connectors.” This lets dex defer authentication to LDAP servers, SAML providers, or established identity providers like GitHub, Google, and Active Directory. Clients write their authentication logic once to talk to dex, then dex handles the protocols for a given backend.

In a Kubernetes context, dex enables:

  • usage of authentication providers that don’t support OIDC itself and
  • grouping of multiple authentication providers.

Prerequisites

  • A Lokomotive cluster accessible via kubectl.

  • An ingress controller such as Contour for HTTP ingress.

  • A certificate manager such as cert-manager for valid certificates.

Configuration

# dex.lokocfg

variable "google_client_id" {
  type = "string"
}

variable "google_client_secret" {
  type = "string"
}

variable "github_client_id" {
  type = "string"
}

variable "github_client_secret" {
  type = "string"
}

variable "dex_static_client_clusterauth_id" {
  type = "string"
}

variable "dex_static_client_clusterauth_secret" {
  type = "string"
}

variable "gangway_redirect_url" {
  type = "string"
}

component "dex" {
  ingress_host = "dex.example.lokomotive-k8s.org"
  issuer_host = "https://dex.example.lokomotive-k8s.org"

  # You can configure one or more connectors. Currently only GitHub and
  # OIDC (for example with Google) are supported from lokoctl.

  # A GitHub connector
  # Requires GitHub OAuth app credentials from https://github.com/settings/developers
  connector "github" {
    id = "github"
    name = "GitHub"

    config {
      client_id = var.github_client_id
      client_secret = var.github_client_secret
      redirect_uri = "https://dex.example.lokomotive-k8s.org/callback"
      team_name_field = "slug"

      org {
        name = "kinvolk"
        teams = [
          "lokomotive-developers",
        ]
      }
    }
  }

  # A OIDC connector
  # Here configured for use with Google
  connector "oidc" {
    id = "google"
    name = "Google"

    config {
      client_id = var.google_client_id
      client_secret = var.google_client_secret
      redirect_uri = "https://dex.example.lokomotive-k8s.org/callback"
      issuer = "https://accounts.google.com"
    }
  }

  # A Google native connector
  connector "google" {
    id   = "google"
    name = "Google"

    config {
      client_id = var.google_client_id
      client_secret = var.google_client_secret
      redirect_uri = "https://dex.example.lokomotive-k8s.org/callback"
      admin_email = "[email protected]"
    }
  }
  # only to be defined with Google connector
  gsuite_json_config_path = "project-testing-123456-er12t34y56ui.json"

  static_client {
    name   = "clusterauth"
    id     = var.dex_static_client_clusterauth_id
    secret = var.dex_static_client_clusterauth_secret
    redirect_uris = [var.gangway_redirect_url]
  }
}

The secrets can be defined in another file (lokocfg.vars) like following:

google_client_id     = "1234567890123-SqDIX1KFvKPYmuV9Sa8eL92cvxtS3TuP.apps.googleusercontent.com"
google_client_secret = "63zYPITtigLxLaYBEjNP9Taw"

# A random secret key (create one with `openssl rand -base64 32`)
dex_static_client_clusterauth_secret = "2KBvQkjOZdc3iHt4KSb9GUECdenH/VDl04TwMdSyPcs="
dex_static_client_clusterauth_id     = "clusterauth"

gangway_redirect_url = "https://gangway.example.lokomotive-k8s.org/callback"

Note: More information on the variables used in above dex config can be found in the gangway doc .

Attribute reference

Table of all the arguments accepted by the component.

Argument Description Default Type Required
ingress_host Used as the hosts domain in the ingress resource for dex that is automatically created. - string true
issuer_host Dex’s issuer URL. - string true
certmanager_cluster_issuer ClusterIssuer to be used by cert-manager while issuing TLS certificates. Supported values: letsencrypt-production, letsencrypt-staging. letsencrypt-production string false
connector Dex implements connectors that target OpenID Connect and specific platforms such as GitHub, Google etc. Currently only GitHub and OIDC (Google) are supported from lokoctl. - list(object) true
connector.id ID of the connector. - string true
connector.name Name of the connector. - string true
connector.config Configuration for the chosen connector. - object true
connector.config.client_id OAuth app client id. - string true
connector.config.client_secret OAuth app client secret. - string true
connector.config.issuer The OIDC issuer endpoint. For oidc connector only. - string true
connector.config.redirect_uri The authorization callback URL. - string true
connector.config.team_name Can be ‘name’, ‘slug’ or ‘both’, see https://github.com/dexidp/dex/blob/master/Documentation/connectors/github.md. For github connector only. - string true
connector.config.admin_email The email of a GSuite super user. For google connector only. - string false
connector.config.hosted_domains If this field is nonempty, only users from a listed domain will be allowed to log in. For oidc and google connectors only. - list(string) false
connector.config.org Define one or more organizations and teams. For github connector only. - list(object) true
connector.config.org.name Name of the GitHub organization. - string true
connector.config.org.teams Name of the team in the provided GitHub organization. - list(string) true
gsuite_json_config_path Path to the Gsuite Service Account JSON file. For google connector only. - string false
static_client Configure one or more static clients, i.e. apps that use dex. Example: gangway - list(object) true
static_client.id Client ID used to identify the static client. - string true
static_client.secret Client secret used to identify the static client. - string true
static_client.name Name used when displaying this client to the end user. - string true
static_client.redirect_uris A registered set of redirect URIs. When redirecting from dex to the client, the URI requested to redirect to MUST match one of these values. - list(string) true

Applying

To apply the Dex component:

lokoctl component apply dex

G Suite specific instructions

You need to create a service account on your google suite account and authorize it to view groups on your domain.

Perform G Suite domain-wide delegation of authority

  • Follow instructions here to create a service account.

  • During Service Account creation a JSON file will be downloaded, give the path to this file in dex’s config for field gsuite_json_config_path.

  • While delegating domain-wide authority to your service account you will be asked to assign scope. In that field select scope https://www.googleapis.com/auth/admin.directory.group.readonly only.

Enable admin SDK

Admin SDK lets administrators of enterprise domains to view and manage resources like users, groups etc. To enable it click here .

Deleting

To destroy the component:

lokoctl component delete dex --delete-namespace