kubernetes/platform/components/oauth2-proxy/components/oauth2-proxy/README.md

   1 # oauth2-proxy
   2
   3 [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.
   4
   5 ## TL;DR;
   6
   7 ```console
   8 $ helm repo add oauth2-proxy https://oauth2-proxy.github.io/manifests
   9 $ helm install my-release oauth2-proxy/oauth2-proxy
  10 ```
  11
  12 ## Introduction
  13
  14 This chart bootstraps an oauth2-proxy deployment on a [Kubernetes](http://kubernetes.io) cluster using the [Helm](https://helm.sh) package manager.
  15
  16 ## Installing the Chart
  17
  18 To install the chart with the release name `my-release`:
  19
  20 ```console
  21 $ helm install my-release oauth2-proxy/oauth2-proxy
  22 ```
  23
  24 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.
  25
  26 ## Uninstalling the Chart
  27
  28 To uninstall/delete the `my-release` deployment:
  29
  30 ```console
  31 $ helm uninstall my-release
  32 ```
  33
  34 The command removes all the Kubernetes components associated with the chart and deletes the release.
  35
  36 ## Upgrading an existing Release to a new major version
  37
  38 A major chart version change (like v1.2.3 -> v2.0.0) indicates that there is an
  39 incompatible breaking change needing manual actions.
  40
  41 ### To 1.0.0
  42
  43 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.
  44
  45 ### To 2.0.0
  46
  47 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.
  48
  49 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.
  50
  51 ### To 3.0.0
  52
  53 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`
  54
  55 ### To 4.0.0
  56
  57 Version 4.0.0 adds support for the new Ingress apiVersion **networking.k8s.io/v1**.
  58 Therefore the `ingress.extraPaths` parameter needs to be updated to the new format.
  59 See the [v1.22 API deprecations guide](https://kubernetes.io/docs/reference/using-api/deprecation-guide/#ingress-v122) for more information.
  60
  61 For the same reason `service.port` was renamed to `service.portNumber`.
  62
  63 ### To 5.0.0
  64
  65 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.
  66
  67 In order to upgrade, delete the Deployment before upgrading:
  68
  69 ```bash
  70 kubectl delete deployment my-release-oauth2-proxy
  71 ```
  72
  73 This will introduce a slight downtime.
  74
  75 For users who don't want downtime, you can perform these actions:
  76
  77 - Perform a non-cascading removal of the deployment that keeps the pods running
  78 - Add new labels to pods
  79 - Perform `helm upgrade`
  80
  81 ### To 6.0.0
  82
  83 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.
  84
  85 ## Configuration
  86
  87 The following table lists the configurable parameters of the oauth2-proxy chart and their default values.
  88
  89 Parameter | Description | Default
  90 --- | --- | ---
  91 `affinity` | node/pod affinities | None
  92 `authenticatedEmailsFile.enabled` | Enables authorize individual email addresses | `false`
  93 `authenticatedEmailsFile.persistence` | Defines how the email addresses file will be projected, via a configmap or secret | `configmap`
  94 `authenticatedEmailsFile.template` | Name of the configmap or secret that is handled outside of that chart | `""`
  95 `authenticatedEmailsFile.restrictedUserAccessKey` | The key of the configmap or secret that holds the email addresses list | `""`
  96 `authenticatedEmailsFile.restricted_access` | [email addresses](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/oauth_provider#email-authentication) list config | `""`
  97 `authenticatedEmailsFile.annotations` | configmap or secret annotations | `nil`
  98 `config.clientID` | oauth client ID | `""`
  99 `config.clientSecret` | oauth client secret | `""`
 100 `config.cookieSecret` | server specific cookie for the secret; create a new one with `openssl rand -base64 32 \| head -c 32 \| base64` | `""`
 101 `config.existingSecret` | existing Kubernetes secret to use for OAuth2 credentials. See [secret template](https://github.com/oauth2-proxy/manifests/blob/master/helm/oauth2-proxy/templates/secret.yaml) for the required values | `nil`
 102 `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 | `""`
 103 `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`
 104 `config.cookieName` | The name of the cookie that oauth2-proxy will create. | `""`
 105 `alphaConfig.enabled` | Flag to toggle any alpha config related logic | `false`
 106 `alphaConfig.annotations` | Configmap annotations | `{}`
 107 `alphaConfig.serverConfigData` | Arbitrary configuration data to append to the server section | `{}`
 108 `alphaConfig.metricsConfigData` | Arbitrary configuration data to append to the metrics section | `{}`
 109 `alphaConfig.configData` | Arbitrary configuration data to append | `{}`
 110 `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/configmap-alpha.yaml) for the required values | `nil`
 111 `customLabels` | Custom labels to add into metadata | `{}` |
 112 `config.google.adminEmail` | user impersonated by the google service account | `""`
 113 `config.google.useApplicationDefaultCredentials` | use the application-default credentials (i.e. Workload Identity on GKE) instead of providing a service account json | `false`
 114 `config.google.targetPrincipal` | service account to use/impersonate | `""`
 115 `config.google.serviceAccountJson` | google service account json contents | `""`
 116 `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`
 117 `config.google.groups` | restrict logins to members of these google groups | `[]`
 118 `containerPort` | used to customise port on the deployment | `""`
 119 `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 `[]`
 120 `extraContainers` | List of extra containers to be added to the pod | `[]`
 121 `extraEnv` | key:value list of extra environment variables to give the binary | `[]`
 122 `extraVolumes` | list of extra volumes | `[]`
 123 `extraVolumeMounts` | list of extra volumeMounts | `[]`
 124 `hostAlias.enabled`  | provide extra ip:hostname alias for network name resolution.
 125 `hostAlias.ip`  | `ip` address `hostAliases.hostname` should resolve to.
 126 `hostAlias.hostname`  | `hostname` associated to `hostAliases.ip`.
 127 `htpasswdFile.enabled` | enable htpasswd-file option | `false`
 128 `htpasswdFile.entries` | list of [encrypted user:passwords](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/overview#command-line-options) | `{}`
 129 `htpasswdFile.existingSecret` | existing Kubernetes secret to use for OAuth2 htpasswd file | `""`
 130 `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`
 131 `image.pullPolicy` | Image pull policy | `IfNotPresent`
 132 `image.repository` | Image repository | `quay.io/oauth2-proxy/oauth2-proxy`
 133 `image.tag` | Image tag | `""` (defaults to appVersion)
 134 `imagePullSecrets` | Specify image pull secrets | `nil` (does not add image pull secrets to deployed pods)
 135 `ingress.enabled` | Enable Ingress | `false`
 136 `ingress.className` | name referencing IngressClass | `nil`
 137 `ingress.path` | Ingress accepted path | `/`
 138 `ingress.pathType` | Ingress [path type](https://kubernetes.io/docs/concepts/services-networking/ingress/#path-types) | `ImplementationSpecific`
 139 `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). | `[]`
 140 `ingress.annotations` | Ingress annotations | `nil`
 141 `ingress.hosts` | Ingress accepted hostnames | `nil`
 142 `ingress.tls` | Ingress TLS configuration | `nil`
 143 `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`
 144 `livenessProbe.initialDelaySeconds` | number of seconds | 0
 145 `livenessProbe.timeoutSeconds` | number of seconds | 1
 146 `nodeSelector` | node labels for pod assignment | `{}`
 147 `deploymentAnnotations` | annotations to add to the deployment | `{}`
 148 `podAnnotations` | annotations to add to each pod | `{}`
 149 `podLabels` | additional labesl to add to each pod | `{}`
 150 `podDisruptionBudget.enabled`| Enabled creation of PodDisruptionBudget (only if replicaCount > 1) | true
 151 `podDisruptionBudget.minAvailable`| minAvailable parameter for PodDisruptionBudget | 1
 152 `podSecurityContext` | Kubernetes security context to apply to pod | `{}`
 153 `priorityClassName` | priorityClassName | `nil`
 154 `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`
 155 `readinessProbe.initialDelaySeconds` | number of seconds | 0
 156 `readinessProbe.timeoutSeconds` | number of seconds | 5
 157 `readinessProbe.periodSeconds` | number of seconds | 10
 158 `readinessProbe.successThreshold` | number of successes | 1
 159 `replicaCount` | desired number of pods | `1`
 160 `resources` | pod resource requests & limits | `{}`
 161 `revisionHistoryLimit` | maximum number of revisions maintained | 10
 162 `service.portNumber` | port number for the service | `80`
 163 `service.appProtocol` | application protocol on the port of the service | `http`
 164 `service.type` | type of service | `ClusterIP`
 165 `service.clusterIP` | cluster ip address | `nil`
 166 `service.loadBalancerIP` | ip of load balancer | `nil`
 167 `service.loadBalancerSourceRanges` | allowed source ranges in load balancer | `nil`
 168 `service.nodePort` | external port number for the service when service.type is `NodePort` | `nil`
 169 `serviceAccount.enabled` | create a service account | `true`
 170 `serviceAccount.name` | the service account name | ``
 171 `serviceAccount.annotations` | (optional) annotations for the service account | `{}`
 172 `tolerations` | list of node taints to tolerate | `[]`
 173 `securityContext.enabled` | enable Kubernetes security context on container | `false`
 174 `securityContext.runAsNonRoot` | make sure that the container runs as a non-root user | `true`
 175 `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`
 176 `sessionStorage.type` | Session storage type which can be one of the following: cookie or redis | `cookie`
 177 `sessionStorage.redis.existingSecret` | Name of the Kubernetes secret containing the redis & redis sentinel password values (see also `sessionStorage.redis.passwordKey`) | `""`
 178 `sessionStorage.redis.password` | Redis password. Applicable for all Redis configurations. Taken from redis subchart secret if not set. sessionStorage.redis.existingSecret takes precedence | `nil`
 179 `sessionStorage.redis.passwordKey` | Key of the Kubernetes secret data containing the redis password value | `redis-password`
 180 `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`
 181 `sessionStorage.redis.standalone.connectionUrl` | URL of redis standalone server for redis session storage (e.g. `redis://HOST[:PORT]`). Automatically generated if not set. | `""`
 182 `sessionStorage.redis.cluster.connectionUrls` | List of Redis cluster connection URLs (e.g. `["redis://127.0.0.1:8000", "redis://127.0.0.1:8000"]`) | `[]`
 183 `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` | `""`
 184 `sessionStorage.redis.sentinel.password` | Redis sentinel password. Used only for sentinel connection; any redis node passwords need to use `sessionStorage.redis.password` | `nil`
 185 `sessionStorage.redis.sentinel.passwordKey` | Key of the Kubernetes secret data containing the redis sentinel password value | `redis-sentinel-password`
 186 `sessionStorage.redis.sentinel.masterName` | Redis sentinel master name | `nil`
 187 `sessionStorage.redis.sentinel.connectionUrls` | List of Redis sentinel connection URLs (e.g. `["redis://127.0.0.1:8000", "redis://127.0.0.1:8000"]`) | `[]`
 188 `topologySpreadConstraints` | List of pod topology spread constraints | `[]`
 189 `redis.enabled` | Enable the redis subchart deployment | `false`
 190 `checkDeprecation` | Enable deprecation checks | `true`
 191 `metrics.enabled` | Enable Prometheus metrics endpoint | `true`
 192 `metrics.port` | Serve Prometheus metrics on this port | `44180`
 193 `metrics.nodePort` | External port for the metrics when service.type is `NodePort` | `nil`
 194 `metrics.service.appProtocol` | application protocol of the metrics port in the service | `http`
 195 `metrics.servicemonitor.enabled` | Enable Prometheus Operator ServiceMonitor | `false`
 196 `metrics.servicemonitor.namespace` | Define the namespace where to deploy the ServiceMonitor resource | `""`
 197 `metrics.servicemonitor.prometheusInstance` | Prometheus Instance definition | `default`
 198 `metrics.servicemonitor.interval` | Prometheus scrape interval | `60s`
 199 `metrics.servicemonitor.scrapeTimeout` | Prometheus scrape timeout | `30s`
 200 `metrics.servicemonitor.labels` | Add custom labels to the ServiceMonitor resource| `{}`
 201 `extraObjects` | Extra K8s manifests to deploy | `[]`
 202
 203 Specify each parameter using the `--set key=value[,key=value]` argument to `helm install`. For example,
 204
 205 ```console
 206 $ helm install my-release oauth2-proxy/oauth2-proxy \
 207   --set=image.tag=v0.0.2,resources.limits.cpu=200m
 208 ```
 209
 210 Alternatively, a YAML file that specifies the values for the above parameters can be provided while installing the chart. For example,
 211
 212 ```console
 213 $ helm install my-release oauth2-proxy/oauth2-proxy -f values.yaml
 214 ```
 215
 216 > **Tip**: You can use the default [values.yaml](values.yaml)
 217
 218 ## TLS Configuration
 219
 220 See: [TLS Configuration](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/tls).
 221 Use ```values.yaml``` like:
 222
 223 ```yaml
 224 ...
 225 extraArgs:
 226   tls-cert-file: /path/to/cert.pem
 227   tls-key-file: /path/to/cert.key
 228
 229 extraVolumes:
 230   - name: ssl-cert
 231     secret:
 232       secretName: my-ssl-secret
 233
 234 extraVolumeMounts:
 235   - mountPath: /path/to/
 236     name: ssl-cert
 237 ...
 238 ```
 239
 240 With a secret called `my-ssl-secret`:
 241
 242 ```yaml
 243 ...
 244 data:
 245   cert.pem: AB..==
 246   cert.key: CD..==
 247 ```
 248
 249 ## Extra environment variable templating
 250 The extraEnv value supports the tpl function which evaluate strings as templates inside the deployment template.
 251 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
 252
 253
 254 ```yaml
 255 ...
 256 tplValue: "This is a test value for the tpl function"
 257 extraEnv:
 258   - name: TEST_ENV_VAR_1
 259     value: test_value_1
 260   - name: TEST_ENV_VAR_2
 261     value: '{{ .Values.tplValue }}'
 262 ```
 263
 264 ## Custom templates configuration
 265 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).
 266
 267 ```yaml
 268 config:
 269   configFile: |
 270     ...
 271     custom_templates_dir = "/data/custom-templates"
 272
 273 extraVolumes:
 274   - name: custom-templates
 275     configMap:
 276       name: oauth2-proxy-custom-templates
 277
 278 extraVolumeMounts:
 279   - name: custom-templates
 280     mountPath: "/data/custom-templates"
 281     readOnly: true
 282
 283 extraObjects:
 284   - apiVersion: v1
 285     kind: ConfigMap
 286     metadata:
 287       name: oauth2-proxy-custom-templates
 288     data:
 289       sign_in.html: |
 290         <!DOCTYPE html>
 291         <html>
 292         <body>sign_in</body>
 293         </html>
 294       error.html: |
 295         <!DOCTYPE html>
 296         <html>
 297         <body>
 298         <h1>error</h1>
 299         <p>{{.StatusCode}}</p>
 300         </body>
 301         </html>
 302 ```
 303 ## Multi whitelist-domain configuration
 304 For using multi whitelist-domain configuration for one Oauth2-proxy instance, you have to use the config.configFile section.
 305
 306 It will be overwriting the `/etc/oauth2_proxy/oauth2_proxy.cfg` configuration file.
 307 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/)
 308
 309 ```yaml
 310 config:
 311   ...
 312   clientID="$YOUR_GOOGLE_CLIENT_ID"
 313   clientSecret="$YOUR_GOOGLE_CLIENT_SECRET"
 314   cookieSecret="$YOUR_COOKIE_SECRET"
 315   configFile: |
 316     ...
 317     email_domains = [ "*" ]
 318     upstreams = [ "file:///dev/null" ]
 319     cookie_secure = "false"
 320     cookie_domains = [ ".domain.com", ".otherdomain.io" ]
 321     whitelist_domains = [ ".domain.com", ".otherdomain.io"]
 322     provider = "google"
 323 ```