aboutsummaryrefslogtreecommitdiffstats
path: root/kubernetes/authentication/components/oauth2-proxy/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'kubernetes/authentication/components/oauth2-proxy/README.md')
-rw-r--r--kubernetes/authentication/components/oauth2-proxy/README.md338
1 files changed, 338 insertions, 0 deletions
diff --git a/kubernetes/authentication/components/oauth2-proxy/README.md b/kubernetes/authentication/components/oauth2-proxy/README.md
new file mode 100644
index 0000000000..55a5e44429
--- /dev/null
+++ b/kubernetes/authentication/components/oauth2-proxy/README.md
@@ -0,0 +1,338 @@
+# oauth2-proxy
+
+[oauth2-proxy](https://github.com/oauth2-proxy/oauth2-proxy) is a reverse proxy and static file server that provides authentication using Providers (Google, GitHub, and others) to validate accounts by email, domain or group.
+
+## TL;DR;
+
+```console
+$ helm repo add oauth2-proxy https://oauth2-proxy.github.io/manifests
+$ helm install my-release oauth2-proxy/oauth2-proxy
+```
+
+## Introduction
+
+This chart bootstraps an oauth2-proxy deployment on a [Kubernetes](http://kubernetes.io) cluster using the [Helm](https://helm.sh) package manager.
+
+## Installing the Chart
+
+To install the chart with the release name `my-release`:
+
+```console
+$ helm install my-release oauth2-proxy/oauth2-proxy
+```
+
+The command deploys oauth2-proxy on the Kubernetes cluster in the default configuration. The [configuration](#configuration) section lists the parameters that can be configured during installation.
+
+## Uninstalling the Chart
+
+To uninstall/delete the `my-release` deployment:
+
+```console
+$ helm uninstall my-release
+```
+
+The command removes all the Kubernetes components associated with the chart and deletes the release.
+
+## Upgrading an existing Release to a new major version
+
+A major chart version change (like v1.2.3 -> v2.0.0) indicates that there is an
+incompatible breaking change needing manual actions.
+
+### To 1.0.0
+
+This version upgrades oauth2-proxy to v4.0.0. Please see the [changelog](https://github.com/oauth2-proxy/oauth2-proxy/blob/v4.0.0/CHANGELOG.md#v400) in order to upgrade.
+
+### To 2.0.0
+
+Version 2.0.0 of this chart introduces support for Kubernetes v1.16.x by way of addressing the deprecation of the Deployment object apiVersion `apps/v1beta2`. See [the v1.16 API deprecations page](https://kubernetes.io/blog/2019/07/18/api-deprecations-in-1-16/) for more information.
+
+Due to [this issue](https://github.com/helm/helm/issues/6583) there may be errors performing a `helm upgrade` of this chart from versions earlier than 2.0.0.
+
+### To 3.0.0
+
+Version 3.0.0 introduces support for [EKS IAM roles for service accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) by adding a managed service account to the chart. This is a breaking change since the service account is enabled by default. To disable this behaviour set `serviceAccount.enabled` to `false`
+
+### To 4.0.0
+
+Version 4.0.0 adds support for the new Ingress apiVersion **networking.k8s.io/v1**.
+Therefore the `ingress.extraPaths` parameter needs to be updated to the new format.
+See the [v1.22 API deprecations guide](https://kubernetes.io/docs/reference/using-api/deprecation-guide/#ingress-v122) for more information.
+
+For the same reason `service.port` was renamed to `service.portNumber`.
+
+### To 5.0.0
+
+Version 5.0.0 introduces support for custom labels and refactor [Kubernetes recommended labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/). This is a breaking change because many labels of all resources need to be updated to stay consistent.
+
+In order to upgrade, delete the Deployment before upgrading:
+
+```bash
+kubectl delete deployment my-release-oauth2-proxy
+```
+
+This will introduce a slight downtime.
+
+For users who don't want downtime, you can perform these actions:
+
+- Perform a non-cascading removal of the deployment that keeps the pods running
+- Add new labels to pods
+- Perform `helm upgrade`
+
+### To 6.0.0
+
+Version 6.0.0 bumps the version of the redis subchart from ~10.6.0 to ~16.4.0. You probably need to adjust your redis config. See [here](https://github.com/bitnami/charts/tree/master/bitnami/redis#upgrading) for detailed upgrade instructions.
+
+## Configuration
+
+The following table lists the configurable parameters of the oauth2-proxy chart and their default values.
+
+Parameter | Description | Default
+--- | --- | ---
+`affinity` | node/pod affinities | None
+`authenticatedEmailsFile.enabled` | Enables authorize individual email addresses | `false`
+`authenticatedEmailsFile.persistence` | Defines how the email addresses file will be projected, via a configmap or secret | `configmap`
+`authenticatedEmailsFile.template` | Name of the configmap or secret that is handled outside of that chart | `""`
+`authenticatedEmailsFile.restrictedUserAccessKey` | The key of the configmap or secret that holds the email addresses list | `""`
+`authenticatedEmailsFile.restricted_access` | [email addresses](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/oauth_provider#email-authentication) list config | `""`
+`authenticatedEmailsFile.annotations` | configmap or secret annotations | `nil`
+`config.clientID` | oauth client ID | `""`
+`config.clientSecret` | oauth client secret | `""`
+`config.cookieSecret` | server specific cookie for the secret; create a new one with `openssl rand -base64 32 \| head -c 32 \| base64` | `""`
+`config.existingSecret` | existing Kubernetes secret to use for OAuth2 credentials. See [oauth2-proxy.secrets helper](https://github.com/oauth2-proxy/manifests/blob/main/helm/oauth2-proxy/templates/_helpers.tpl#L157C13-L157C33) for the required values | `nil`
+`config.configFile` | custom [oauth2_proxy.cfg](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/contrib/oauth2-proxy.cfg.example) contents for settings not overridable via environment nor command line | `""`
+`config.existingConfig` | existing Kubernetes configmap to use for the configuration file. See [config template](https://github.com/oauth2-proxy/manifests/blob/master/helm/oauth2-proxy/templates/configmap.yaml) for the required values | `nil`
+`config.cookieName` | The name of the cookie that oauth2-proxy will create. | `""`
+`alphaConfig.enabled` | Flag to toggle any alpha config related logic | `false`
+`alphaConfig.annotations` | Configmap annotations | `{}`
+`alphaConfig.serverConfigData` | Arbitrary configuration data to append to the server section | `{}`
+`alphaConfig.metricsConfigData` | Arbitrary configuration data to append to the metrics section | `{}`
+`alphaConfig.configData` | Arbitrary configuration data to append | `{}`
+`alphaConfig.configFile` | Arbitrary configuration to append, treated as a Go template and rendered with the root context | `""`
+`alphaConfig.existingConfig` | existing Kubernetes configmap to use for the alpha configuration file. See [config template](https://github.com/oauth2-proxy/manifests/blob/master/helm/oauth2-proxy/templates/secret-alpha.yaml) for the required values | `nil`
+`alphaConfig.existingSecret` | existing Kubernetes secret to use for the alpha configuration file. See [config template](https://github.com/oauth2-proxy/manifests/blob/master/helm/oauth2-proxy/templates/secret-alpha.yaml) for the required values | `nil`
+`customLabels` | Custom labels to add into metadata | `{}` |
+`config.google.adminEmail` | user impersonated by the google service account | `""`
+`config.google.useApplicationDefaultCredentials` | use the application-default credentials (i.e. Workload Identity on GKE) instead of providing a service account json | `false`
+`config.google.targetPrincipal` | service account to use/impersonate | `""`
+`config.google.serviceAccountJson` | google service account json contents | `""`
+`config.google.existingConfig` | existing Kubernetes configmap to use for the service account file. See [google secret template](https://github.com/oauth2-proxy/manifests/blob/master/helm/oauth2-proxy/templates/google-secret.yaml) for the required values | `nil`
+`config.google.groups` | restrict logins to members of these google groups | `[]`
+`containerPort` | used to customise port on the deployment | `""`
+`extraArgs` | Extra arguments to give the binary. Either as a map with key:value pairs or as a list type, which allows to configure the same flag multiple times. (e.g. `["--allowed-role=CLIENT_ID:CLIENT_ROLE_NAME_A", "--allowed-role=CLIENT_ID:CLIENT_ROLE_NAME_B"]`). | `{}` or `[]`
+`extraContainers` | List of extra containers to be added to the pod | `[]`
+`extraEnv` | key:value list of extra environment variables to give the binary | `[]`
+`extraVolumes` | list of extra volumes | `[]`
+`extraVolumeMounts` | list of extra volumeMounts | `[]`
+`hostAliases` | hostAliases is a list of aliases to be added to /etc/hosts for network name resolution.
+`htpasswdFile.enabled` | enable htpasswd-file option | `false`
+`htpasswdFile.entries` | list of [encrypted user:passwords](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/overview#command-line-options) | `{}`
+`htpasswdFile.existingSecret` | existing Kubernetes secret to use for OAuth2 htpasswd file | `""`
+`httpScheme` | `http` or `https`. `name` used for port on the deployment. `httpGet` port `name` and `scheme` used for `liveness`- and `readinessProbes`. `name` and `targetPort` used for the service. | `http`
+`image.pullPolicy` | Image pull policy | `IfNotPresent`
+`image.repository` | Image repository | `quay.io/oauth2-proxy/oauth2-proxy`
+`image.tag` | Image tag | `""` (defaults to appVersion)
+`imagePullSecrets` | Specify image pull secrets | `nil` (does not add image pull secrets to deployed pods)
+`ingress.enabled` | Enable Ingress | `false`
+`ingress.className` | name referencing IngressClass | `nil`
+`ingress.path` | Ingress accepted path | `/`
+`ingress.pathType` | Ingress [path type](https://kubernetes.io/docs/concepts/services-networking/ingress/#path-types) | `ImplementationSpecific`
+`ingress.extraPaths` | Ingress extra paths to prepend to every host configuration. Useful when configuring [custom actions with AWS ALB Ingress Controller](https://kubernetes-sigs.github.io/aws-alb-ingress-controller/guide/ingress/annotation/#actions). | `[]`
+`ingress.labels` | Ingress extra labels | `{}`
+`ingress.annotations` | Ingress annotations | `nil`
+`ingress.hosts` | Ingress accepted hostnames | `nil`
+`ingress.tls` | Ingress TLS configuration | `nil`
+`initContainers.waitForRedis.enabled` | if `redis.enabled` is true, use an init container to wait for the redis master pod to be ready. If `serviceAccount.enabled` is true, create additionally a role/binding to get, list and watch the redis master pod | `true`
+`initContainers.waitForRedis.image.pullPolicy` | kubectl image pull policy | `IfNotPresent`
+`initContainers.waitForRedis.image.repository` | kubectl image repository | `docker.io/bitnami/kubectl`
+`initContainers.waitForRedis.kubectlVersion` | kubectl version to use for the init container | `printf "%s.%s" .Capabilities.KubeVersion.Major (.Capabilities.KubeVersion.Minor | replace "+" "")`
+`initContainers.waitForRedis.securityContext.enabled` | enable Kubernetes security context on container | `true`
+`initContainers.waitForRedis.timeout` | number of seconds | 180
+`initContainers.waitForRedis.resources` | pod resource requests & limits | `{}`
+`livenessProbe.enabled` | enable Kubernetes livenessProbe. Disable to use oauth2-proxy with Istio mTLS. See [Istio FAQ](https://istio.io/help/faq/security/#k8s-health-checks) | `true`
+`livenessProbe.initialDelaySeconds` | number of seconds | 0
+`livenessProbe.timeoutSeconds` | number of seconds | 1
+`namespaceOverride` | Override the deployment namespace | `""`
+`nodeSelector` | node labels for pod assignment | `{}`
+`deploymentAnnotations` | annotations to add to the deployment | `{}`
+`podAnnotations` | annotations to add to each pod | `{}`
+`podLabels` | additional labesl to add to each pod | `{}`
+`podDisruptionBudget.enabled`| Enabled creation of PodDisruptionBudget (only if replicaCount > 1) | true
+`podDisruptionBudget.minAvailable`| minAvailable parameter for PodDisruptionBudget | 1
+`podSecurityContext` | Kubernetes security context to apply to pod | `{}`
+`priorityClassName` | priorityClassName | `nil`
+`readinessProbe.enabled` | enable Kubernetes readinessProbe. Disable to use oauth2-proxy with Istio mTLS. See [Istio FAQ](https://istio.io/help/faq/security/#k8s-health-checks) | `true`
+`readinessProbe.initialDelaySeconds` | number of seconds | 0
+`readinessProbe.timeoutSeconds` | number of seconds | 5
+`readinessProbe.periodSeconds` | number of seconds | 10
+`readinessProbe.successThreshold` | number of successes | 1
+`replicaCount` | desired number of pods | `1`
+`resources` | pod resource requests & limits | `{}`
+`revisionHistoryLimit` | maximum number of revisions maintained | 10
+`service.portNumber` | port number for the service | `80`
+`service.appProtocol` | application protocol on the port of the service | `http`
+`service.type` | type of service | `ClusterIP`
+`service.clusterIP` | cluster ip address | `nil`
+`service.loadBalancerIP` | ip of load balancer | `nil`
+`service.loadBalancerSourceRanges` | allowed source ranges in load balancer | `nil`
+`service.nodePort` | external port number for the service when service.type is `NodePort` | `nil`
+`serviceAccount.enabled` | create a service account | `true`
+`serviceAccount.name` | the service account name | ``
+`serviceAccount.annotations` | (optional) annotations for the service account | `{}`
+`strategy` | configure deployment strategy | `{}`
+`tolerations` | list of node taints to tolerate | `[]`
+`securityContext.enabled` | enable Kubernetes security context on container | `true`
+`proxyVarsAsSecrets` | choose between environment values or secrets for setting up OAUTH2_PROXY variables. When set to false, remember to add the variables OAUTH2_PROXY_CLIENT_ID, OAUTH2_PROXY_CLIENT_SECRET, OAUTH2_PROXY_COOKIE_SECRET in extraEnv | `true`
+`sessionStorage.type` | Session storage type which can be one of the following: cookie or redis | `cookie`
+`sessionStorage.redis.existingSecret` | Name of the Kubernetes secret containing the redis & redis sentinel password values (see also `sessionStorage.redis.passwordKey`) | `""`
+`sessionStorage.redis.password` | Redis password. Applicable for all Redis configurations. Taken from redis subchart secret if not set. sessionStorage.redis.existingSecret takes precedence | `nil`
+`sessionStorage.redis.passwordKey` | Key of the Kubernetes secret data containing the redis password value | `redis-password`
+`sessionStorage.redis.clientType` | Allows the user to select which type of client will be used for redis instance. Possible options are: `sentinel`, `cluster` or `standalone` | `standalone`
+`sessionStorage.redis.standalone.connectionUrl` | URL of redis standalone server for redis session storage (e.g. `redis://HOST[:PORT]`). Automatically generated if not set. | `""`
+`sessionStorage.redis.cluster.connectionUrls` | List of Redis cluster connection URLs (e.g. `["redis://127.0.0.1:8000", "redis://127.0.0.1:8000"]`) | `[]`
+`sessionStorage.redis.sentinel.existingSecret` | Name of the Kubernetes secret containing the redis sentinel password value (see also `sessionStorage.redis.sentinel.passwordKey`). Default: `sessionStorage.redis.existingSecret` | `""`
+`sessionStorage.redis.sentinel.password` | Redis sentinel password. Used only for sentinel connection; any redis node passwords need to use `sessionStorage.redis.password` | `nil`
+`sessionStorage.redis.sentinel.passwordKey` | Key of the Kubernetes secret data containing the redis sentinel password value | `redis-sentinel-password`
+`sessionStorage.redis.sentinel.masterName` | Redis sentinel master name | `nil`
+`sessionStorage.redis.sentinel.connectionUrls` | List of Redis sentinel connection URLs (e.g. `["redis://127.0.0.1:8000", "redis://127.0.0.1:8000"]`) | `[]`
+`topologySpreadConstraints` | List of pod topology spread constraints | `[]`
+`redis.enabled` | Enable the redis subchart deployment | `false`
+`checkDeprecation` | Enable deprecation checks | `true`
+`metrics.enabled` | Enable Prometheus metrics endpoint | `true`
+`metrics.port` | Serve Prometheus metrics on this port | `44180`
+`metrics.nodePort` | External port for the metrics when service.type is `NodePort` | `nil`
+`metrics.service.appProtocol` | application protocol of the metrics port in the service | `http`
+`metrics.serviceMonitor.enabled` | Enable Prometheus Operator ServiceMonitor | `false`
+`metrics.serviceMonitor.namespace` | Define the namespace where to deploy the ServiceMonitor resource | `""`
+`metrics.serviceMonitor.prometheusInstance` | Prometheus Instance definition | `default`
+`metrics.serviceMonitor.interval` | Prometheus scrape interval | `60s`
+`metrics.serviceMonitor.scrapeTimeout` | Prometheus scrape timeout | `30s`
+`metrics.serviceMonitor.labels` | Add custom labels to the ServiceMonitor resource| `{}`
+`metrics.serviceMonitor.scheme` | HTTP scheme to use for scraping. Can be used with `tlsConfig` for example if using istio mTLS.| `""`
+`metrics.serviceMonitor.tlsConfig` | TLS configuration to use when scraping the endpoint. For example if using istio mTLS.| `{}`
+`metrics.serviceMonitor.bearerTokenFile` | Path to bearer token file.| `""`
+`metrics.serviceMonitor.annotations` | Used to pass annotations that are used by the Prometheus installed in your cluster| `{}`
+`metrics.serviceMonitor.metricRelabelings` | Metric relabel configs to apply to samples before ingestion.| `[]`
+`metrics.serviceMonitor.relabelings` | Relabel configs to apply to samples before ingestion.| `[]`
+`extraObjects` | Extra K8s manifests to deploy | `[]`
+
+Specify each parameter using the `--set key=value[,key=value]` argument to `helm install`. For example,
+
+```console
+$ helm install my-release oauth2-proxy/oauth2-proxy \
+ --set=image.tag=v0.0.2,resources.limits.cpu=200m
+```
+
+Alternatively, a YAML file that specifies the values for the above parameters can be provided while installing the chart. For example,
+
+```console
+$ helm install my-release oauth2-proxy/oauth2-proxy -f values.yaml
+```
+
+> **Tip**: You can use the default [values.yaml](values.yaml)
+
+## TLS Configuration
+
+See: [TLS Configuration](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/tls).
+Use ```values.yaml``` like:
+
+```yaml
+...
+extraArgs:
+ tls-cert-file: /path/to/cert.pem
+ tls-key-file: /path/to/cert.key
+
+extraVolumes:
+ - name: ssl-cert
+ secret:
+ secretName: my-ssl-secret
+
+extraVolumeMounts:
+ - mountPath: /path/to/
+ name: ssl-cert
+...
+```
+
+With a secret called `my-ssl-secret`:
+
+```yaml
+...
+data:
+ cert.pem: AB..==
+ cert.key: CD..==
+```
+
+## Extra environment variable templating
+The extraEnv value supports the tpl function which evaluate strings as templates inside the deployment template.
+This is useful to pass a template string as a value to the chart's extra environment variables and to render external configuration environment values
+
+
+```yaml
+...
+tplValue: "This is a test value for the tpl function"
+extraEnv:
+ - name: TEST_ENV_VAR_1
+ value: test_value_1
+ - name: TEST_ENV_VAR_2
+ value: '{{ .Values.tplValue }}'
+```
+
+## Custom templates configuration
+You can replace the default template files using a Kubernetes `configMap` volume. The default templates are the two files [sign_in.html](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/pkg/app/pagewriter/sign_in.html) and [error.html](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/pkg/app/pagewriter/error.html).
+
+```yaml
+config:
+ configFile: |
+ ...
+ custom_templates_dir = "/data/custom-templates"
+
+extraVolumes:
+ - name: custom-templates
+ configMap:
+ name: oauth2-proxy-custom-templates
+
+extraVolumeMounts:
+ - name: custom-templates
+ mountPath: "/data/custom-templates"
+ readOnly: true
+
+extraObjects:
+ - apiVersion: v1
+ kind: ConfigMap
+ metadata:
+ name: oauth2-proxy-custom-templates
+ data:
+ sign_in.html: |
+ <!DOCTYPE html>
+ <html>
+ <body>sign_in</body>
+ </html>
+ error.html: |
+ <!DOCTYPE html>
+ <html>
+ <body>
+ <h1>error</h1>
+ <p>{{.StatusCode}}</p>
+ </body>
+ </html>
+```
+## Multi whitelist-domain configuration
+For using multi whitelist-domain configuration for one Oauth2-proxy instance, you have to use the config.configFile section.
+
+It will be overwriting the `/etc/oauth2_proxy/oauth2_proxy.cfg` configuration file.
+In this example, Google provider is used, but you can find all other provider configuration here [oauth_provider](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/oauth_provider/)
+
+```yaml
+config:
+ ...
+ clientID="$YOUR_GOOGLE_CLIENT_ID"
+ clientSecret="$YOUR_GOOGLE_CLIENT_SECRET"
+ cookieSecret="$YOUR_COOKIE_SECRET"
+ configFile: |
+ ...
+ email_domains = [ "*" ]
+ upstreams = [ "file:///dev/null" ]
+ cookie_secure = "false"
+ cookie_domains = [ ".domain.com", ".otherdomain.io" ]
+ whitelist_domains = [ ".domain.com", ".otherdomain.io"]
+ provider = "google"
+```