contour-authserver

contour-authserver implements the Envoy external authorization GRPC protocol (both v2 and v3). It can be used for testing Envoy external authorization. contour-authserver has two authorization backends that are selected by subcommands.

testserver

Usage:

Run a testing authentication server

Usage:
  contour-authserver testserver [OPTIONS]

Flags:
      --address string         The address the authentication endpoint binds to. (default ":9090")
  -h, --help                   help for testserver
      --tls-ca-path string     Path to the TLS CA certificate bundle.
      --tls-cert-path string   Path to the TLS server certificate.
      --tls-key-path string    Path to the TLS server key.

testserver will authorize any path that contains the string allow, and will reject other requests with a 401 status code.

htpasswd

Usage:

Run a htpasswd basic authentication server

Usage:
  contour-authserver htpasswd [OPTIONS]

Flags:
      --address string             The address the authentication endpoint binds to. (default ":9090")
      --auth-realm string          Basic authentication realm. (default "default")
  -h, --help                       help for htpasswd
      --metrics-address string     The address the metrics endpoint binds to. (default ":8080")
      --selector string            Selector (label-query) to filter Secrets, supports '=', '==', and '!='.
      --tls-ca-path string         Path to the TLS CA certificate bundle.
      --tls-cert-path string       Path to the TLS server certificate.
      --tls-key-path string        Path to the TLS server key.
      --watch-namespaces strings   The list of namespaces to watch for Secrets.

htpasswd Secrets

The htpasswd backend implements HTTP basic authentication against a set of Secrets that contain htpasswd formatted data. The htpasswd data must be stored in the auth key, which is compatible with ingress-nginx auth-file Secrets.

The htpasswd backend only accesses Secrets that are annotated with projectcontour.io/auth-type: basic.

Secrets that are annotated with the projectcontour.io/auth-realm will only be used if the annotation value matches the value of the --auth-realm flag. The projectcontour.io/auth-realm: * annotation explicitly marks a Secret as being valid for all realms. This is equivalent to omitting the annotation.

When it authenticates a request, the htpasswd backend injects the Auth-Username and Auth-Realm headers, which contain the authenticated user name and the basic authentication realm respectively.

The --watch-namespaces flag specifies the namespaces where the htpasswd backend will discover Secrets. If this flag is empty, Secrets from all namespaces will be used.

The --selector flag accepts a label selector that can be used to further restrict which Secrets the htpasswd backend will consume.

bearer

Usage:

Run a bearer authentication server

Usage:
  contour-authserver bearer [OPTIONS]

Flags:
      --address string             The address the authentication endpoint binds to. (default ":9090")
      --auth-realm string          Bearer authentication realm. (default "default")
  -h, --help                       help for bearer
      --metrics-address string     The address the metrics endpoint binds to. (default ":8080")
      --selector string            Selector (label-query) to filter Secrets, supports '=', '==', and '!='.
      --tls-ca-path string         Path to the TLS CA certificate bundle.
      --tls-cert-path string       Path to the TLS server certificate.
      --tls-key-path string        Path to the TLS server key.
      --watch-namespaces strings   The list of namespaces to watch for Secrets.

bearer Secrets

The bearer backend implements bearer token authentication against a set of Secrets that contain bearer formatted data. The bearer token must be stored in the auth key.

The bearer backend only accesses Secrets that are annotated with projectcontour.io/auth-type: bearer.

Secrets that are annotated with the projectcontour.io/auth-realm will only be used if the annotation value matches the value of the --auth-realm flag. The projectcontour.io/auth-realm: * annotation explicitly marks a Secret as being valid for all realms. This is equivalent to omitting the annotation.

When it authenticates a request, the bearer backend injects the Auth-Realm headers, which contain the authentication realm respectively.

The --watch-namespaces flag specifies the namespaces where the bearer backend will discover Secrets. If this flag is empty, Secrets from all namespaces will be used.

The --selector flag accepts a label selector that can be used to further restrict which Secrets the bearer backend will consume.

oidc

Usage:

Run a oidc authentication server

Usage:
  contour-authserver oidc [OPTIONS]

Flags:
      --config string              Path to config file ( yaml format )
  -h, --help                       help for htpasswd
      --tls-ca-path string         Path to the TLS CA certificate bundle.
      --tls-cert-path string       Path to the TLS server certificate.
      --tls-key-path string        Path to the TLS server key.

Oidc configuration can be specified with configmaps. Please visit DexIDP for more detail.

## The following entries are the variables  accepted by the Contour OIDC module.
## server address and port 
address: ":9443"

## OIDC issuer URL 
issuerURL: "http://<path to your SSO server>"

## App redirect path ( usually point back to app url)
redirectURL: "https://<path to your applications>"
redirectPath: "/callback"
allowEmptyClientSecret: false
scopes:
- openid
- profile
- email
- offline_access
usernameClaim: "nickname"
emailClaim: ""
serveTLS: false
clientID: "<your client id>"
clientSecret: "<your client secret>"

Request Headers

Both authorization backends emit the Auth-Handler header, which publishes the name of the backend that approved or rejected the authorization.

The authorization context is also reflected into HTTP headers prefixed with Auth-Context-. Note that This can generate malformed HTTP headers. The testserver backend always creates the context headers, but the htpasswd backend only does so for authenticated requests (i.e. the origin server gets them bu the client never does.)

Deploying contour-authserver

The recommended way to deploy contour-authserver is to use the Kustomize deployment YAML. This will deploy services for testserver , htpasswd and oidc backends. For developer deployments, Skaffold seems to work reasonably well.

There are no versioned releases or container images yet.

Releasing contour-authserver

Maintainers who need to release a new version of contour-authserver can follow the following steps:

# Ensure that you have a Github token either in $GITHUB_TOKEN or in ~/.config/goreleaser/github_token.
# Ensure that goreleaser is installed.

# Tag the release.
$ ./hack/make-release-tag.sh $OLDVERS $NEWVERS

# Push the release tag to Github.
$ git push origin $NEWVERS

# Build and release binaries and Docker images.
$ make release

# Log in with your GitHub account and token to push the images.
$ docker login -u <GitHub username>
$ docker push ghcr.io/projectcontour/contour-authserver:$NEWVERS
$ docker push ghcr.io/projectcontour/contour-authserver:latest

# Log out.
$ docker logout