--- id: integration title: Integration --- ## Configuring for use with the Nginx `auth_request` directive **This option requires `--reverse-proxy` option to be set.** The [Nginx `auth_request` directive](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) allows Nginx to authenticate requests via the oauth2-proxy's `/auth` endpoint, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the request through. For example: ```nginx server { listen 443 ssl; server_name ...; include ssl/ssl.conf; location /oauth2/ { proxy_pass http://127.0.0.1:4180; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Auth-Request-Redirect $request_uri; # or, if you are handling multiple domains: # proxy_set_header X-Auth-Request-Redirect $scheme://$host$request_uri; } location = /oauth2/auth { proxy_pass http://127.0.0.1:4180; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-Uri $request_uri; # nginx auth_request includes headers but not body proxy_set_header Content-Length ""; proxy_pass_request_body off; } location / { auth_request /oauth2/auth; error_page 401 =403 /oauth2/sign_in; # pass information via X-User and X-Email headers to backend, # requires running with --set-xauthrequest flag auth_request_set $user $upstream_http_x_auth_request_user; auth_request_set $email $upstream_http_x_auth_request_email; proxy_set_header X-User $user; proxy_set_header X-Email $email; # if you enabled --pass-access-token, this will pass the token to the backend auth_request_set $token $upstream_http_x_auth_request_access_token; proxy_set_header X-Access-Token $token; # if you enabled --cookie-refresh, this is needed for it to work with auth_request auth_request_set $auth_cookie $upstream_http_set_cookie; add_header Set-Cookie $auth_cookie; # When using the --set-authorization-header flag, some provider's cookies can exceed the 4kb # limit and so the OAuth2 Proxy splits these into multiple parts. # Nginx normally only copies the first `Set-Cookie` header from the auth_request to the response, # so if your cookies are larger than 4kb, you will need to extract additional cookies manually. auth_request_set $auth_cookie_name_upstream_1 $upstream_cookie_auth_cookie_name_1; # Extract the Cookie attributes from the first Set-Cookie header and append them # to the second part ($upstream_cookie_* variables only contain the raw cookie content) if ($auth_cookie ~* "(; .*)") { set $auth_cookie_name_0 $auth_cookie; set $auth_cookie_name_1 "auth_cookie_name_1=$auth_cookie_name_upstream_1$1"; } # Send both Set-Cookie headers now if there was a second part if ($auth_cookie_name_upstream_1) { add_header Set-Cookie $auth_cookie_name_0; add_header Set-Cookie $auth_cookie_name_1; } proxy_pass http://backend/; # or "root /path/to/site;" or "fastcgi_pass ..." etc } } ``` When you use ingress-nginx in Kubernetes, you MUST use `kubernetes/ingress-nginx` (which includes the Lua module) and the following configuration snippet for your `Ingress`. Variables set with `auth_request_set` are not `set`-able in plain nginx config when the location is processed via `proxy_pass` and then may only be processed by Lua. Note that `nginxinc/kubernetes-ingress` does not include the Lua module. ```yaml nginx.ingress.kubernetes.io/auth-response-headers: Authorization nginx.ingress.kubernetes.io/auth-signin: https://$host/oauth2/start?rd=$escaped_request_uri nginx.ingress.kubernetes.io/auth-url: https://$host/oauth2/auth nginx.ingress.kubernetes.io/configuration-snippet: | auth_request_set $name_upstream_1 $upstream_cookie_name_1; access_by_lua_block { if ngx.var.name_upstream_1 ~= "" then ngx.header["Set-Cookie"] = "name_1=" .. ngx.var.name_upstream_1 .. ngx.var.auth_cookie:match("(; .*)") end } ``` It is recommended to use `--session-store-type=redis` when expecting large sessions/OIDC tokens (_e.g._ with MS Azure). You have to substitute *name* with the actual cookie name you configured via --cookie-name parameter. If you don't set a custom cookie name the variable should be "$upstream_cookie__oauth2_proxy_1" instead of "$upstream_cookie_name_1" and the new cookie-name should be "_oauth2_proxy_1=" instead of "name_1=". ## Configuring for use with the Traefik (v2) `ForwardAuth` middleware **This option requires `--reverse-proxy` option to be set.** ## ForwardAuth with 401 errors middleware The [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) allows Traefik to authenticate requests via the oauth2-proxy's `/oauth2/auth` endpoint on every request, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the whole request through. For example, on Dynamic File (YAML) Configuration: ```yaml http: routers: a-service: rule: "Host(`a-service.example.com`)" service: a-service-backend middlewares: - oauth-errors - oauth-auth tls: certResolver: default domains: - main: "example.com" sans: - "*.example.com" oauth: rule: "Host(`a-service.example.com`, `oauth.example.com`) && PathPrefix(`/oauth2/`)" middlewares: - auth-headers service: oauth-backend tls: certResolver: default domains: - main: "example.com" sans: - "*.example.com" services: a-service-backend: loadBalancer: servers: - url: http://172.16.0.2:7555 oauth-backend: loadBalancer: servers: - url: http://172.16.0.1:4180 middlewares: auth-headers: headers: sslRedirect: true stsSeconds: 315360000 browserXssFilter: true contentTypeNosniff: true forceSTSHeader: true sslHost: example.com stsIncludeSubdomains: true stsPreload: true frameDeny: true oauth-auth: forwardAuth: address: https://oauth.example.com/oauth2/auth trustForwardHeader: true oauth-errors: errors: status: - "401-403" service: oauth-backend query: "/oauth2/sign_in?rd={url}" ``` ## ForwardAuth with static upstreams configuration Redirect to sign_in functionality provided without the use of `errors` middleware with [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) pointing to oauth2-proxy service's `/` endpoint **Following options need to be set on `oauth2-proxy`:** - `--upstream=static://202`: Configures a static response for authenticated sessions - `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly ```yaml http: routers: a-service-route-1: rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/`)" service: a-service-backend middlewares: - oauth-auth-redirect # redirects all unauthenticated to oauth2 signin tls: certResolver: default domains: - main: "example.com" sans: - "*.example.com" a-service-route-2: rule: "Host(`a-service.example.com`) && PathPrefix(`/no-auto-redirect`)" service: a-service-backend middlewares: - oauth-auth-wo-redirect # unauthenticated session will return a 401 tls: certResolver: default domains: - main: "example.com" sans: - "*.example.com" services-oauth2-route: rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/oauth2/`)" middlewares: - auth-headers service: oauth-backend tls: certResolver: default domains: - main: "example.com" sans: - "*.example.com" oauth2-proxy-route: rule: "Host(`oauth.example.com`) && PathPrefix(`/`)" middlewares: - auth-headers service: oauth-backend tls: certResolver: default domains: - main: "example.com" sans: - "*.example.com" services: a-service-backend: loadBalancer: servers: - url: http://172.16.0.2:7555 b-service-backend: loadBalancer: servers: - url: http://172.16.0.3:7555 oauth-backend: loadBalancer: servers: - url: http://172.16.0.1:4180 middlewares: auth-headers: headers: sslRedirect: true stsSeconds: 315360000 browserXssFilter: true contentTypeNosniff: true forceSTSHeader: true sslHost: example.com stsIncludeSubdomains: true stsPreload: true frameDeny: true oauth-auth-redirect: forwardAuth: address: https://oauth.example.com/ trustForwardHeader: true authResponseHeaders: - X-Auth-Request-Access-Token - Authorization oauth-auth-wo-redirect: forwardAuth: address: https://oauth.example.com/oauth2/auth trustForwardHeader: true authResponseHeaders: - X-Auth-Request-Access-Token - Authorization ``` :::note If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated. :::