Merge pull request #903 from oauth2-proxy/reference-generator

Add docs and generated reference for Alpha configuration

.github/workflows/ci.yaml

@@ -33,6 +33,10 @@ jobs:
         curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
         chmod +x ./cc-test-reporter
 
+    - name: Verify Code Generation
+      run: |
+        make verify-generate
+
     - name: Lint
       run: |
         make lint

CHANGELOG.md

@@ -66,6 +66,7 @@
 
 ## Changes since v6.1.1
 
+- [#903](https://github.com/oauth2-proxy/oauth2-proxy/pull/903) Add docs and generated reference for Alpha configuration (@JoelSpeed)
 - [#995](https://github.com/oauth2-proxy/oauth2-proxy/pull/995) Add Security Policy (@JoelSpeed)
 - [#964](https://github.com/oauth2-proxy/oauth2-proxy/pull/964) Require `--reverse-proxy` true to trust `X-Forwareded-*` type headers (@NickMeves)
 - [#970](https://github.com/oauth2-proxy/oauth2-proxy/pull/970) Fix joined cookie name for those containing underline in the suffix (@peppered)

Makefile

@@ -69,6 +69,14 @@ docker-push-all: docker-push
 	docker push $(REGISTRY)/oauth2-proxy:latest-armv6
 	docker push $(REGISTRY)/oauth2-proxy:${VERSION}-armv6
 
+.PHONY: generate
+generate:
+	go generate ./pkg/...
+
+.PHONY: verify-generate
+verify-generate: generate
+	git diff --exit-code
+
 .PHONY: test
 test: lint
 	GO111MODULE=on $(GO) test $(TESTCOVER) -v -race ./...

docs/docs/configuration/alpha_config.md

@@ -0,0 +1,212 @@
+---
+id: alpha-config
+title: Alpha Configuration
+---
+
+:::warning
+This page contains documentation for alpha features.
+We reserve the right to make breaking changes to the features detailed within this page with no notice.
+
+Options described in this page may be changed, removed, renamed or moved without prior warning.
+Please beware of this before you use alpha configuration options.
+:::
+
+This page details a set of **alpha** configuration options in a new format.
+Going forward we are intending to add structured configuration in YAML format to
+replace the existing TOML based configuration file and flags.
+
+Below is a reference for the structure of the configuration, with
+[AlphaOptions](#alphaoptions) as the root of the configuration.
+
+When using alpha configuration, your config file will look something like below:
+
+```yaml
+upstreams:
+  - id: ...
+    ...
+injectRequestHeaders:
+  - name: ...
+    ...
+injectResponseHeaders:
+  - name: ...
+    ...
+```
+
+Please browse the [reference](#configuration-reference) below for the structure
+of the new configuration format.
+
+## Using Alpha Configuration
+
+To use the new **alpha** configuration, generate a YAML file based on the format
+described in the [reference](#configuration-reference) below.
+
+Provide the path to this file using the `--alpha-config` flag.
+
+:::note
+When using the `--alpha-config` flag, some options are no longer available.
+See [removed options](#removed-options) below for more information.
+:::
+
+### Converting configuration to the new structure
+
+Before adding the new `--alpha-config` option, start OAuth2 Proxy using the
+`convert-config-to-alpha` flag to convert existing configuration to the new format.
+
+```bash
+oauth2-proxy --convert-config-to-alpha --config ./path/to/existing/config.cfg
+```
+
+This will convert any options supported by the new format to YAML and print the
+new configuration to `STDOUT`.
+
+Copy this to a new file, remove any options from your existing configuration
+noted in [removed options](#removed-options) and then start OAuth2 Proxy using
+the new config.
+
+```bash
+oauth2-proxy --alpha-config ./path/to/new/config.yaml --config ./path/to/existing/config.cfg
+```
+
+## Removed options
+
+The following flags/options and their respective environment variables are no
+longer available when using alpha configuration:
+
+<!-- Legacy Upstream FlagSet -->
+- `flush-interval`/`flush_interval`
+- `pass-host-header`/`pass_host_header`
+- `proxy-websockets`/`proxy_websockets`
+- `ssl-upstream-insecure-skip-verify`/`ssl_upstream_insecure_skip_verify`
+- `upstream`/`upstreams`
+
+<!-- Legacy Headers FlagSet -->
+- `pass-basic-auth`/`pass_basic_auth`
+- `pass-access-token`/`pass_access_token`
+- `pass-user-headers`/`pass_user_headers`
+- `pass-authorization-header`/`pass_authorization_header`
+- `set-basic-auth`/`set_basic_auth`
+- `set-xauthrequest`/`set_xauthrequest`
+- `set-authorization-header`/`set_authorization_header`
+- `prefer-email-to-user`/`prefer_email_to_user`
+- `basic-auth-password`/`basic_auth_password`
+- `skip-auth-strip-headers`/`skip_auth_strip_headers`
+
+Attempting to use these options via flags or via config when `--alpha-config`
+set will result in an error.
+
+:::important
+You must remove these options before starting OAuth2 Proxy with `--alpha-config`
+:::
+
+## Configuration Reference
+<!--- THIS FILE IS AUTOGENERATED!!! DO NOT EDIT!!! -->
+
+### AlphaOptions
+
+AlphaOptions contains alpha structured configuration options.
+Usage of these options allows users to access alpha features that are not
+available as part of the primary configuration structure for OAuth2 Proxy.
+
+:::warning
+The options within this structure are considered alpha.
+They may change between releases without notice.
+:::
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `upstreams` | _[Upstreams](#upstreams)_ | Upstreams is used to configure upstream servers.<br/>Once a user is authenticated, requests to the server will be proxied to<br/>these upstream servers based on the path mappings defined in this list. |
+| `injectRequestHeaders` | _[[]Header](#header)_ | InjectRequestHeaders is used to configure headers that should be added<br/>to requests to upstream servers.<br/>Headers may source values from either the authenticated user's session<br/>or from a static secret value. |
+| `injectResponseHeaders` | _[[]Header](#header)_ | InjectResponseHeaders is used to configure headers that should be added<br/>to responses from the proxy.<br/>This is typically used when using the proxy as an external authentication<br/>provider in conjunction with another proxy such as NGINX and its<br/>auth_request module.<br/>Headers may source values from either the authenticated user's session<br/>or from a static secret value. |
+
+### ClaimSource
+
+(**Appears on:** [HeaderValue](#headervalue))
+
+ClaimSource allows loading a header value from a claim within the session
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `claim` | _string_ | Claim is the name of the claim in the session that the value should be<br/>loaded from. |
+| `prefix` | _string_ | Prefix is an optional prefix that will be prepended to the value of the<br/>claim if it is non-empty. |
+| `basicAuthPassword` | _[SecretSource](#secretsource)_ | BasicAuthPassword converts this claim into a basic auth header.<br/>Note the value of claim will become the basic auth username and the<br/>basicAuthPassword will be used as the password value. |
+
+### Duration
+#### (`string` alias)
+
+(**Appears on:** [Upstream](#upstream))
+
+Duration is as string representation of a period of time.
+A duration string is a is a possibly signed sequence of decimal numbers,
+each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m".
+Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
+
+
+### Header
+
+(**Appears on:** [AlphaOptions](#alphaoptions))
+
+Header represents an individual header that will be added to a request or
+response header.
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `name` | _string_ | Name is the header name to be used for this set of values.<br/>Names should be unique within a list of Headers. |
+| `preserveRequestValue` | _bool_ | PreserveRequestValue determines whether any values for this header<br/>should be preserved for the request to the upstream server.<br/>This option only takes effet on injected request headers.<br/>Defaults to false (headers that match this header will be stripped). |
+| `values` | _[[]HeaderValue](#headervalue)_ | Values contains the desired values for this header |
+
+### HeaderValue
+
+(**Appears on:** [Header](#header))
+
+HeaderValue represents a single header value and the sources that can
+make up the header value
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `value` | _[]byte_ | Value expects a base64 encoded string value. |
+| `fromEnv` | _string_ | FromEnv expects the name of an environment variable. |
+| `fromFile` | _string_ | FromFile expects a path to a file containing the secret value. |
+| `claim` | _string_ | Claim is the name of the claim in the session that the value should be<br/>loaded from. |
+| `prefix` | _string_ | Prefix is an optional prefix that will be prepended to the value of the<br/>claim if it is non-empty. |
+| `basicAuthPassword` | _[SecretSource](#secretsource)_ | BasicAuthPassword converts this claim into a basic auth header.<br/>Note the value of claim will become the basic auth username and the<br/>basicAuthPassword will be used as the password value. |
+
+### SecretSource
+
+(**Appears on:** [ClaimSource](#claimsource), [HeaderValue](#headervalue))
+
+SecretSource references an individual secret value.
+Only one source within the struct should be defined at any time.
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `value` | _[]byte_ | Value expects a base64 encoded string value. |
+| `fromEnv` | _string_ | FromEnv expects the name of an environment variable. |
+| `fromFile` | _string_ | FromFile expects a path to a file containing the secret value. |
+
+### Upstream
+
+(**Appears on:** [Upstreams](#upstreams))
+
+Upstream represents the configuration for an upstream server.
+Requests will be proxied to this upstream if the path matches the request path.
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `id` | _string_ | ID should be a unique identifier for the upstream.<br/>This value is required for all upstreams. |
+| `path` | _string_ | Path is used to map requests to the upstream server.<br/>The closest match will take precedence and all Paths must be unique. |
+| `uri` | _string_ | The URI of the upstream server. This may be an HTTP(S) server of a File<br/>based URL. It may include a path, in which case all requests will be served<br/>under that path.<br/>Eg:<br/>- http://localhost:8080<br/>- https://service.localhost<br/>- https://service.localhost/path<br/>- file://host/path<br/>If the URI's path is "/base" and the incoming request was for "/dir",<br/>the upstream request will be for "/base/dir". |
+| `insecureSkipTLSVerify` | _bool_ | InsecureSkipTLSVerify will skip TLS verification of upstream HTTPS hosts.<br/>This option is insecure and will allow potential Man-In-The-Middle attacks<br/>betweem OAuth2 Proxy and the usptream server.<br/>Defaults to false. |
+| `static` | _bool_ | Static will make all requests to this upstream have a static response.<br/>The response will have a body of "Authenticated" and a response code<br/>matching StaticCode.<br/>If StaticCode is not set, the response will return a 200 response. |
+| `staticCode` | _int_ | StaticCode determines the response code for the Static response.<br/>This option can only be used with Static enabled. |
+| `flushInterval` | _[Duration](#duration)_ | FlushInterval is the period between flushing the response buffer when<br/>streaming response from the upstream.<br/>Defaults to 1 second. |
+| `passHostHeader` | _bool_ | PassHostHeader determines whether the request host header should be proxied<br/>to the upstream server.<br/>Defaults to true. |
+| `proxyWebSockets` | _bool_ | ProxyWebSockets enables proxying of websockets to upstream servers<br/>Defaults to true. |
+
+### Upstreams
+
+#### ([[]Upstream](#upstream) alias)
+
+(**Appears on:** [AlphaOptions](#alphaoptions))
+
+Upstreams is a collection of definitions for upstream servers.
+

docs/docs/configuration/alpha_config.md.tmpl

@@ -0,0 +1,101 @@
+---
+id: alpha-config
+title: Alpha Configuration
+---
+
+:::warning
+This page contains documentation for alpha features.
+We reserve the right to make breaking changes to the features detailed within this page with no notice.
+
+Options described in this page may be changed, removed, renamed or moved without prior warning.
+Please beware of this before you use alpha configuration options.
+:::
+
+This page details a set of **alpha** configuration options in a new format.
+Going forward we are intending to add structured configuration in YAML format to
+replace the existing TOML based configuration file and flags.
+
+Below is a reference for the structure of the configuration, with
+[AlphaOptions](#alphaoptions) as the root of the configuration.
+
+When using alpha configuration, your config file will look something like below:
+
+```yaml
+upstreams:
+  - id: ...
+    ...
+injectRequestHeaders:
+  - name: ...
+    ...
+injectResponseHeaders:
+  - name: ...
+    ...
+```
+
+Please browse the [reference](#configuration-reference) below for the structure
+of the new configuration format.
+
+## Using Alpha Configuration
+
+To use the new **alpha** configuration, generate a YAML file based on the format
+described in the [reference](#configuration-reference) below.
+
+Provide the path to this file using the `--alpha-config` flag.
+
+:::note
+When using the `--alpha-config` flag, some options are no longer available.
+See [removed options](#removed-options) below for more information.
+:::
+
+### Converting configuration to the new structure
+
+Before adding the new `--alpha-config` option, start OAuth2 Proxy using the
+`convert-config-to-alpha` flag to convert existing configuration to the new format.
+
+```bash
+oauth2-proxy --convert-config-to-alpha --config ./path/to/existing/config.cfg
+```
+
+This will convert any options supported by the new format to YAML and print the
+new configuration to `STDOUT`.
+
+Copy this to a new file, remove any options from your existing configuration
+noted in [removed options](#removed-options) and then start OAuth2 Proxy using
+the new config.
+
+```bash
+oauth2-proxy --alpha-config ./path/to/new/config.yaml --config ./path/to/existing/config.cfg
+```
+
+## Removed options
+
+The following flags/options and their respective environment variables are no
+longer available when using alpha configuration:
+
+<!-- Legacy Upstream FlagSet -->
+- `flush-interval`/`flush_interval`
+- `pass-host-header`/`pass_host_header`
+- `proxy-websockets`/`proxy_websockets`
+- `ssl-upstream-insecure-skip-verify`/`ssl_upstream_insecure_skip_verify`
+- `upstream`/`upstreams`
+
+<!-- Legacy Headers FlagSet -->
+- `pass-basic-auth`/`pass_basic_auth`
+- `pass-access-token`/`pass_access_token`
+- `pass-user-headers`/`pass_user_headers`
+- `pass-authorization-header`/`pass_authorization_header`
+- `set-basic-auth`/`set_basic_auth`
+- `set-xauthrequest`/`set_xauthrequest`
+- `set-authorization-header`/`set_authorization_header`
+- `prefer-email-to-user`/`prefer_email_to_user`
+- `basic-auth-password`/`basic_auth_password`
+- `skip-auth-strip-headers`/`skip_auth_strip_headers`
+
+Attempting to use these options via flags or via config when `--alpha-config`
+set will result in an error.
+
+:::important
+You must remove these options before starting OAuth2 Proxy with `--alpha-config`
+:::
+
+## Configuration Reference

docs/sidebars.js

@@ -12,7 +12,7 @@ module.exports = {
       type: 'category',
       label: 'Configuration',
       collapsed: false,
-      items: ['configuration/overview', 'configuration/oauth_provider', 'configuration/session_storage', 'configuration/tls'],
+      items: ['configuration/overview', 'configuration/oauth_provider', 'configuration/session_storage', 'configuration/tls', 'configuration/alpha-config'],
     },
     {
       type: 'category',

go.mod

@@ -16,6 +16,7 @@ require (
 	github.com/justinas/alice v1.2.0
 	github.com/mbland/hmacauth v0.0.0-20170912233209-44256dfd4bfa
 	github.com/mitchellh/mapstructure v1.1.2
+	github.com/oauth2-proxy/tools/reference-gen v0.0.0-20210118095127-56ffd7384404
 	github.com/onsi/ginkgo v1.14.1
 	github.com/onsi/gomega v1.10.2
 	github.com/pierrec/lz4 v2.5.2+incompatible

go.sum

@@ -72,6 +72,7 @@ github.com/go-kit/kit v0.8.0/go.mod h1:xBxKIO96dXMWWy0MnWVtmwkA9/13aqxPnvrjFYMA2
 github.com/go-logfmt/logfmt v0.3.0/go.mod h1:Qt1PoO58o5twSAckw1HlFXLmHsOX5/0LbT9GBnD5lWE=
 github.com/go-logfmt/logfmt v0.4.0/go.mod h1:3RMwSq7FuexP4Kalkev3ejPJsZTpXXBr9+V4qmtdjCk=
 github.com/go-logr/logr v0.1.0/go.mod h1:ixOQHD9gLJUVQQ2ZOR7zLEifBX6tGkNJF4QyIY7sIas=
+github.com/go-logr/logr v0.2.0 h1:QvGt2nLcHH0WK9orKa+ppBPAxREcH364nPUedEpK0TY=
 github.com/go-logr/logr v0.2.0/go.mod h1:z6/tIYblkpsD+a4lm/fGIIU9mZ+XfAiaFtq7xTgseGU=
 github.com/go-openapi/jsonpointer v0.0.0-20160704185906-46af16f9f7b1/go.mod h1:+35s3my2LFTysnkMfxsJBAMHj/DoqoB9knIWoYG/Vk0=
 github.com/go-openapi/jsonreference v0.0.0-20160704190145-13c6e3589ad9/go.mod h1:W3Z9FmVs9qj+KR4zFKmDPGiLdk1D9Rlm7cyMvf57TTg=
@@ -175,6 +176,8 @@ github.com/mwitkow/go-conntrack v0.0.0-20161129095857-cc309e4a2223/go.mod h1:qRW
 github.com/mxk/go-flowrate v0.0.0-20140419014527-cca7078d478f/go.mod h1:ZdcZmHo+o7JKHSa8/e818NopupXU1YMK5fe1lsApnBw=
 github.com/nxadm/tail v1.4.4 h1:DQuhQpB1tVlglWS2hLQ5OV6B5r8aGxSrPc5Qo6uTN78=
 github.com/nxadm/tail v1.4.4/go.mod h1:kenIhsEOeOJmVchQTgglprH7qJGnHDVpk1VPCcaMI8A=
+github.com/oauth2-proxy/tools/reference-gen v0.0.0-20210118095127-56ffd7384404 h1:ZpzR4Ou1nhldBG/vEzauoqyaUlofaUcLkv1C/gBK8ls=
+github.com/oauth2-proxy/tools/reference-gen v0.0.0-20210118095127-56ffd7384404/go.mod h1:YpORG8zs14vNlpXvuHYnnDvWazIRaDk02MaY8lafqdI=
 github.com/oklog/ulid v1.3.1/go.mod h1:CirwcVhetQ6Lv90oh/F+FBtV6XMibvdAFo93nm5qn4U=
 github.com/onsi/ginkgo v0.0.0-20170829012221-11459a886d9c/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
 github.com/onsi/ginkgo v1.6.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
@@ -248,6 +251,7 @@ github.com/xiang90/probing v0.0.0-20190116061207-43a291ad63a2/go.mod h1:UETIi67q
 github.com/xordataexchange/crypt v0.0.3-0.20170626215501-b2862e3d0a77/go.mod h1:aYKd//L2LvnjZzWKhF00oedf4jCCReLcmhLdhm1A27Q=
 github.com/yhat/wsutil v0.0.0-20170731153501-1d66fa95c997 h1:1+FQ4Ns+UZtUiQ4lP0sTCyKSQ0EXoiwAdHZB0Pd5t9Q=
 github.com/yhat/wsutil v0.0.0-20170731153501-1d66fa95c997/go.mod h1:DIGbh/f5XMAessMV/uaIik81gkDVjUeQ9ApdaU7wRKE=
+github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/gopher-lua v0.0.0-20190206043414-8bfc7677f583/go.mod h1:gqRgreBUhTSL0GeU64rtZ3Uq3wtjOa/TB2YfrtkCbVQ=
 github.com/yuin/gopher-lua v0.0.0-20191213034115-f46add6fdb5c/go.mod h1:gqRgreBUhTSL0GeU64rtZ3Uq3wtjOa/TB2YfrtkCbVQ=
 github.com/yuin/gopher-lua v0.0.0-20191220021717-ab39c6098bdb h1:ZkM6LRnq40pR1Ox0hTHlnpkcOTuFIDQpZ1IN8rKKhX0=
@@ -263,6 +267,7 @@ go.uber.org/zap v1.10.0/go.mod h1:vwi/ZaCAaUcBkycHslxD9B2zi4UTXhF60s6SWpuDF0Q=
 golang.org/x/crypto v0.0.0-20180904163835-0709b304e793/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2 h1:VklqNMn3ovrHsnt90PveolxSbWFaJdECFbxSq0Mqo2M=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9 h1:psW17arqaxU48Z5kZ0CQnkZWQJsqcURM6tKiBApRjXI=
 golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
 golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
@@ -271,6 +276,8 @@ golang.org/x/lint v0.0.0-20190227174305-5b3e6a55c961/go.mod h1:wehouNa3lNwaWXcvx
 golang.org/x/lint v0.0.0-20190301231843-5614ed5bae6f/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE=
 golang.org/x/lint v0.0.0-20190313153728-d0100b6bd8b3/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc=
 golang.org/x/lint v0.0.0-20190409202823-959b441ac422/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc=
+golang.org/x/mod v0.2.0 h1:KU7oHjnv3XNWfa5COkzUifxZmxp1TyI7ImMXqFxLwvQ=
+golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20180906233101-161cd47e91fd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
@@ -283,6 +290,8 @@ golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn
 golang.org/x/net v0.0.0-20190503192946-f4e77d36d62c/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
 golang.org/x/net v0.0.0-20190522155817-f3200d17e092/go.mod h1:HSz+uSET+XFnRR8LxR5pz3Of3rY3CfYBVs4xY44aLks=
 golang.org/x/net v0.0.0-20190603091049-60506f45cf65/go.mod h1:HSz+uSET+XFnRR8LxR5pz3Of3rY3CfYBVs4xY44aLks=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20200301022130-244492dfa37a/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20200324143707-d3edc9973b7e/go.mod h1:qpuaurCH72eLCgpAm/N6yyVIVM9cpaDIP3A8BGJEC5A=
 golang.org/x/net v0.0.0-20200520004742-59133d7f0dd7 h1:AeiKBIuRw3UomYXSbLy0Mc2dDLfdtbT/IVn4keq83P0=
@@ -299,6 +308,7 @@ golang.org/x/sync v0.0.0-20181108010431-42b317875d0f/go.mod h1:RxMgew5VJxzue5/jJ
 golang.org/x/sync v0.0.0-20181221193216-37e7f081c4d4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20190227155943-e225da77a7e6/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20180905080454-ebe1bf3edb33/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20180909124046-d0be0721c37e/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
@@ -334,6 +344,11 @@ golang.org/x/tools v0.0.0-20190311212946-11955173bddd/go.mod h1:LCzVGOaR6xXOjkQ3
 golang.org/x/tools v0.0.0-20190312170243-e65039ee4138/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
 golang.org/x/tools v0.0.0-20190328211700-ab21143f2384/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
 golang.org/x/tools v0.0.0-20190524140312-2c0ae7006135/go.mod h1:RgjU9mgBXZiqYHBnxXauZ1Gv1EHHAz9KjViQ78xBX0Q=
+golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.0.0-20200505023115-26f46d2f7ef8 h1:BMFHd4OFnFtWX46Xj4DN6vvT1btiBxyq+s0orYBqcQY=
+golang.org/x/tools v0.0.0-20200505023115-26f46d2f7ef8/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 google.golang.org/api v0.4.0/go.mod h1:8k5glujaEP+g9n7WNsDg8QP6cUVNI86fCNMcbazEtwE=
@@ -399,8 +414,12 @@ honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWh
 k8s.io/apimachinery v0.19.3 h1:bpIQXlKjB4cB/oNpnNnV+BybGPR7iP5oYpsOTEJ4hgc=
 k8s.io/apimachinery v0.19.3/go.mod h1:DnPGDnARWFvYa3pMHgSxtbZb7gpzzAZ1pTfaUNDVlmA=
 k8s.io/gengo v0.0.0-20200413195148-3a45101e95ac/go.mod h1:ezvh/TsK7cY6rbqRK0oQQ8IAqLxYwwyPxAX1Pzy0ii0=
+k8s.io/gengo v0.0.0-20201113003025-83324d819ded h1:JApXBKYyB7l9xx+DK7/+mFjC7A9Bt5A93FPvFD0HIFE=
+k8s.io/gengo v0.0.0-20201113003025-83324d819ded/go.mod h1:FiNAH4ZV3gBg2Kwh89tzAEV2be7d5xI0vBa/VySYy3E=
 k8s.io/klog/v2 v2.0.0/go.mod h1:PBfzABfn139FHAV07az/IF9Wp1bkk3vpT2XSJ76fSDE=
 k8s.io/klog/v2 v2.2.0/go.mod h1:Od+F08eJP+W3HUb4pSrPpgp9DGU4GzlpG/TmITuYh/Y=
+k8s.io/klog/v2 v2.4.0 h1:7+X0fUguPyrKEC4WjH8iGDg3laWgMo5tMnRTIGTTxGQ=
+k8s.io/klog/v2 v2.4.0/go.mod h1:Od+F08eJP+W3HUb4pSrPpgp9DGU4GzlpG/TmITuYh/Y=
 k8s.io/kube-openapi v0.0.0-20200805222855-6aeccd4b50c6/go.mod h1:UuqjUnNftUyPE5H64/qeyjQoUZhGpeFDVdxjTeEVN2o=
 sigs.k8s.io/structured-merge-diff/v4 v4.0.1/go.mod h1:bJZC9H9iH24zzfZ/41RGcq60oK1F7G282QMXDPYydCw=
 sigs.k8s.io/yaml v1.1.0/go.mod h1:UJmg0vDUVViEyp3mgSv9WPwZCDxu4rQW1olrI1uml+o=

pkg/apis/options/common.go

@@ -28,6 +28,7 @@ type SecretSource struct {
 // A duration string is a is a possibly signed sequence of decimal numbers,
 // each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m".
 // Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
+// +reference-gen:alias-name=string
 type Duration time.Duration
 
 // UnmarshalJSON parses the duration string and sets the value of duration

pkg/apis/options/doc.go

@@ -0,0 +1,2 @@
+//go:generate go run github.com/oauth2-proxy/tools/reference-gen/cmd/reference-gen --package github.com/oauth2-proxy/oauth2-proxy/v7/pkg/apis/options --types AlphaOptions --header-file ../../../docs/docs/configuration/alpha_config.md.tmpl --out-file ../../../docs/docs/configuration/alpha_config.md
+package options

tools/tools.go

@@ -0,0 +1,7 @@
+// +build tools
+
+package tools
+
+import (
+	_ "github.com/oauth2-proxy/tools/reference-gen/cmd/reference-gen"
+)