github.com/pusher/oauth2_proxy@v3.2.0+incompatible/README.md (about) 1 # oauth2_proxy 2 3 A reverse proxy and static file server that provides authentication using Providers (Google, GitHub, and others) 4 to validate accounts by email, domain or group. 5 6 **Note:** This repository was forked from [bitly/OAuth2_Proxy](https://github.com/bitly/oauth2_proxy) on 27/11/2018. 7 Versions v3.0.0 and up are from this fork and will have diverged from any changes in the original fork. 8 A list of changes can be seen in the [CHANGELOG](CHANGELOG.md). 9 10 [![Build Status](https://secure.travis-ci.org/pusher/oauth2_proxy.svg?branch=master)](http://travis-ci.org/pusher/oauth2_proxy) 11 12 ![Sign In Page](https://cloud.githubusercontent.com/assets/45028/4970624/7feb7dd8-6886-11e4-93e0-c9904af44ea8.png) 13 14 ## Architecture 15 16 ![OAuth2 Proxy Architecture](https://cloud.githubusercontent.com/assets/45028/8027702/bd040b7a-0d6a-11e5-85b9-f8d953d04f39.png) 17 18 ## Installation 19 20 1. Choose how to deploy: 21 22 a. Download [Prebuilt Binary](https://github.com/pusher/oauth2_proxy/releases) (current release is `v3.2.0`) 23 24 b. Build with `$ go get github.com/pusher/oauth2_proxy` which will put the binary in `$GOROOT/bin` 25 26 c. Using the prebuilt docker image [quay.io/pusher/oauth2_proxy](https://quay.io/pusher/oauth2_proxy) (AMD64, ARMv6 and ARM64 tags available) 27 28 Prebuilt binaries can be validated by extracting the file and verifying it against the `sha256sum.txt` checksum file provided for each release starting with version `v3.0.0`. 29 30 ``` 31 sha256sum -c sha256sum.txt 2>&1 | grep OK 32 oauth2_proxy-3.2.0.linux-amd64: OK 33 ``` 34 35 2. Select a Provider and Register an OAuth Application with a Provider 36 3. Configure OAuth2 Proxy using config file, command line options, or environment variables 37 4. Configure SSL or Deploy behind a SSL endpoint (example provided for Nginx) 38 39 ## OAuth Provider Configuration 40 41 You will need to register an OAuth application with a Provider (Google, GitHub or another provider), and configure it with Redirect URI(s) for the domain you intend to run `oauth2_proxy` on. 42 43 Valid providers are : 44 45 - [Google](#google-auth-provider) _default_ 46 - [Azure](#azure-auth-provider) 47 - [Facebook](#facebook-auth-provider) 48 - [GitHub](#github-auth-provider) 49 - [GitLab](#gitlab-auth-provider) 50 - [LinkedIn](#linkedin-auth-provider) 51 - [login.gov](#logingov-provider) 52 53 The provider can be selected using the `provider` configuration value. 54 55 ### Google Auth Provider 56 57 For Google, the registration steps are: 58 59 1. Create a new project: https://console.developers.google.com/project 60 2. Choose the new project from the top right project dropdown (only if another project is selected) 61 3. In the project Dashboard center pane, choose **"API Manager"** 62 4. In the left Nav pane, choose **"Credentials"** 63 5. In the center pane, choose **"OAuth consent screen"** tab. Fill in **"Product name shown to users"** and hit save. 64 6. In the center pane, choose **"Credentials"** tab. 65 - Open the **"New credentials"** drop down 66 - Choose **"OAuth client ID"** 67 - Choose **"Web application"** 68 - Application name is freeform, choose something appropriate 69 - Authorized JavaScript origins is your domain ex: `https://internal.yourcompany.com` 70 - Authorized redirect URIs is the location of oauth2/callback ex: `https://internal.yourcompany.com/oauth2/callback` 71 - Choose **"Create"** 72 7. Take note of the **Client ID** and **Client Secret** 73 74 It's recommended to refresh sessions on a short interval (1h) with `cookie-refresh` setting which validates that the account is still authorized. 75 76 #### Restrict auth to specific Google groups on your domain. (optional) 77 78 1. Create a service account: https://developers.google.com/identity/protocols/OAuth2ServiceAccount and make sure to download the json file. 79 2. Make note of the Client ID for a future step. 80 3. Under "APIs & Auth", choose APIs. 81 4. Click on Admin SDK and then Enable API. 82 5. Follow the steps on https://developers.google.com/admin-sdk/directory/v1/guides/delegation#delegate_domain-wide_authority_to_your_service_account and give the client id from step 2 the following oauth scopes: 83 84 ``` 85 https://www.googleapis.com/auth/admin.directory.group.readonly 86 https://www.googleapis.com/auth/admin.directory.user.readonly 87 ``` 88 89 6. Follow the steps on https://support.google.com/a/answer/60757 to enable Admin API access. 90 7. Create or choose an existing administrative email address on the Gmail domain to assign to the `google-admin-email` flag. This email will be impersonated by this client to make calls to the Admin SDK. See the note on the link from step 5 for the reason why. 91 8. Create or choose an existing email group and set that email to the `google-group` flag. You can pass multiple instances of this flag with different groups 92 and the user will be checked against all the provided groups. 93 9. Lock down the permissions on the json file downloaded from step 1 so only oauth2_proxy is able to read the file and set the path to the file in the `google-service-account-json` flag. 94 10. Restart oauth2_proxy. 95 96 Note: The user is checked against the group members list on initial authentication and every time the token is refreshed ( about once an hour ). 97 98 ### Azure Auth Provider 99 100 1. Add an application: go to [https://portal.azure.com](https://portal.azure.com), choose **"Azure Active Directory"** in the left menu, select **"App registrations"** and then click on **"New app registration"**. 101 2. Pick a name and choose **"Webapp / API"** as application type. Use `https://internal.yourcompany.com` as Sign-on URL. Click **"Create"**. 102 3. On the **"Settings"** / **"Properties"** page of the app, pick a logo and select **"Multi-tenanted"** if you want to allow users from multiple organizations to access your app. Note down the application ID. Click **"Save"**. 103 4. On the **"Settings"** / **"Required Permissions"** page of the app, click on **"Windows Azure Active Directory"** and then on **"Access the directory as the signed in user"**. Hit **"Save"** and then then on **"Grant permissions"** (you might need another admin to do this). 104 5. On the **"Settings"** / **"Reply URLs"** page of the app, add `https://internal.yourcompanycom/oauth2/callback` for each host that you want to protect by the oauth2 proxy. Click **"Save"**. 105 6. On the **"Settings"** / **"Keys"** page of the app, add a new key and note down the value after hitting **"Save"**. 106 7. Configure the proxy with 107 108 ``` 109 --provider=azure 110 --client-id=<application ID from step 3> 111 --client-secret=<value from step 6> 112 ``` 113 114 ### Facebook Auth Provider 115 116 1. Create a new FB App from <https://developers.facebook.com/> 117 2. Under FB Login, set your Valid OAuth redirect URIs to `https://internal.yourcompany.com/oauth2/callback` 118 119 ### GitHub Auth Provider 120 121 1. Create a new project: https://github.com/settings/developers 122 2. Under `Authorization callback URL` enter the correct url ie `https://internal.yourcompany.com/oauth2/callback` 123 124 The GitHub auth provider supports two additional parameters to restrict authentication to Organization or Team level access. Restricting by org and team is normally accompanied with `--email-domain=*` 125 126 -github-org="": restrict logins to members of this organisation 127 -github-team="": restrict logins to members of any of these teams (slug), separated by a comma 128 129 If you are using GitHub enterprise, make sure you set the following to the appropriate url: 130 131 -login-url="http(s)://<enterprise github host>/login/oauth/authorize" 132 -redeem-url="http(s)://<enterprise github host>/login/oauth/access_token" 133 -validate-url="http(s)://<enterprise github host>/api/v3" 134 135 ### GitLab Auth Provider 136 137 Whether you are using GitLab.com or self-hosting GitLab, follow [these steps to add an application](http://doc.gitlab.com/ce/integration/oauth_provider.html) 138 139 If you are using self-hosted GitLab, make sure you set the following to the appropriate URL: 140 141 -login-url="<your gitlab url>/oauth/authorize" 142 -redeem-url="<your gitlab url>/oauth/token" 143 -validate-url="<your gitlab url>/api/v4/user" 144 145 ### LinkedIn Auth Provider 146 147 For LinkedIn, the registration steps are: 148 149 1. Create a new project: https://www.linkedin.com/secure/developer 150 2. In the OAuth User Agreement section: 151 - In default scope, select r_basicprofile and r_emailaddress. 152 - In "OAuth 2.0 Redirect URLs", enter `https://internal.yourcompany.com/oauth2/callback` 153 3. Fill in the remaining required fields and Save. 154 4. Take note of the **Consumer Key / API Key** and **Consumer Secret / Secret Key** 155 156 ### Microsoft Azure AD Provider 157 158 For adding an application to the Microsoft Azure AD follow [these steps to add an application](https://azure.microsoft.com/en-us/documentation/articles/active-directory-integrating-applications/). 159 160 Take note of your `TenantId` if applicable for your situation. The `TenantId` can be used to override the default `common` authorization server with a tenant specific server. 161 162 ### OpenID Connect Provider 163 164 OpenID Connect is a spec for OAUTH 2.0 + identity that is implemented by many major providers and several open source projects. This provider was originally built against CoreOS Dex and we will use it as an example. 165 166 1. Launch a Dex instance using the [getting started guide](https://github.com/coreos/dex/blob/master/Documentation/getting-started.md). 167 2. Setup oauth2_proxy with the correct provider and using the default ports and callbacks. 168 3. Login with the fixture use in the dex guide and run the oauth2_proxy with the following args: 169 170 -provider oidc 171 -client-id oauth2_proxy 172 -client-secret proxy 173 -redirect-url http://127.0.0.1:4180/oauth2/callback 174 -oidc-issuer-url http://127.0.0.1:5556 175 -cookie-secure=false 176 -email-domain example.com 177 178 ### login.gov Provider 179 180 login.gov is an OIDC provider for the US Government. 181 If you are a US Government agency, you can contact the login.gov team through the contact information 182 that you can find on https://login.gov/developers/ and work with them to understand how to get login.gov 183 accounts for integration/test and production access. 184 185 A developer guide is available here: https://developers.login.gov/, though this proxy handles everything 186 but the data you need to create to register your application in the login.gov dashboard. 187 188 As a demo, we will assume that you are running your application that you want to secure locally on 189 http://localhost:3000/, that you will be starting your proxy up on http://localhost:4180/, and that 190 you have an agency integration account for testing. 191 192 First, register your application in the dashboard. The important bits are: 193 * Identity protocol: make this `Openid connect` 194 * Issuer: do what they say for OpenID Connect. We will refer to this string as `${LOGINGOV_ISSUER}`. 195 * Public key: This is a self-signed certificate in .pem format generated from a 2048 bit RSA private key. 196 A quick way to do this is `openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 3650 -nodes -subj '/C=US/ST=Washington/L=DC/O=GSA/OU=18F/CN=localhost'`, 197 The contents of the `key.pem` shall be referred to as `${OAUTH2_PROXY_JWT_KEY}`. 198 * Return to App URL: Make this be `http://localhost:4180/` 199 * Redirect URIs: Make this be `http://localhost:4180/oauth2/callback`. 200 * Attribute Bundle: Make sure that email is selected. 201 202 Now start the proxy up with the following options: 203 ``` 204 ./oauth2_proxy -provider login.gov \ 205 -client-id=${LOGINGOV_ISSUER} \ 206 -redirect-url=http://localhost:4180/oauth2/callback \ 207 -oidc-issuer-url=https://idp.int.identitysandbox.gov/ \ 208 -cookie-secure=false \ 209 -email-domain=gsa.gov \ 210 -upstream=http://localhost:3000/ \ 211 -cookie-secret=somerandomstring12341234567890AB \ 212 -cookie-domain=localhost \ 213 -skip-provider-button=true \ 214 -pubjwk-url=https://idp.int.identitysandbox.gov/api/openid_connect/certs \ 215 -profile-url=https://idp.int.identitysandbox.gov/api/openid_connect/userinfo \ 216 -jwt-key="${OAUTH2_PROXY_JWT_KEY}" 217 ``` 218 You can also set all these options with environment variables, for use in cloud/docker environments. 219 220 Once it is running, you should be able to go to `http://localhost:4180/` in your browser, 221 get authenticated by the login.gov integration server, and then get proxied on to your 222 application running on `http://localhost:3000/`. In a real deployment, you would secure 223 your application with a firewall or something so that it was only accessible from the 224 proxy, and you would use real hostnames everywhere. 225 226 #### Skip OIDC discovery 227 228 Some providers do not support OIDC discovery via their issuer URL, so oauth2_proxy cannot simply grab the authorization, token and jwks URI endpoints from the provider's metadata. 229 230 In this case, you can set the `-skip-oidc-discovery` option, and supply those required endpoints manually: 231 232 ``` 233 -provider oidc 234 -client-id oauth2_proxy 235 -client-secret proxy 236 -redirect-url http://127.0.0.1:4180/oauth2/callback 237 -oidc-issuer-url http://127.0.0.1:5556 238 -skip-oidc-discovery 239 -login-url http://127.0.0.1:5556/authorize 240 -redeem-url http://127.0.0.1:5556/token 241 -oidc-jwks-url http://127.0.0.1:5556/keys 242 -cookie-secure=false 243 -email-domain example.com 244 ``` 245 246 ## Email Authentication 247 248 To authorize by email domain use `--email-domain=yourcompany.com`. To authorize individual email addresses use `--authenticated-emails-file=/path/to/file` with one email per line. To authorize all email addresses use `--email-domain=*`. 249 250 ## Configuration 251 252 `oauth2_proxy` can be configured via [config file](#config-file), [command line options](#command-line-options) or [environment variables](#environment-variables). 253 254 To generate a strong cookie secret use `python -c 'import os,base64; print base64.urlsafe_b64encode(os.urandom(16))'` 255 256 ### Config File 257 258 An example [oauth2_proxy.cfg](contrib/oauth2_proxy.cfg.example) config file is in the contrib directory. It can be used by specifying `-config=/etc/oauth2_proxy.cfg` 259 260 ### Command Line Options 261 262 ``` 263 Usage of oauth2_proxy: 264 -approval-prompt string: OAuth approval_prompt (default "force") 265 -authenticated-emails-file string: authenticate against emails via file (one per line) 266 -azure-tenant string: go to a tenant-specific or common (tenant-independent) endpoint. (default "common") 267 -basic-auth-password string: the password to set when passing the HTTP Basic Auth header 268 -client-id string: the OAuth Client ID: ie: "123456.apps.googleusercontent.com" 269 -client-secret string: the OAuth Client Secret 270 -config string: path to config file 271 -cookie-domain string: an optional cookie domain to force cookies to (ie: .yourcompany.com) 272 -cookie-path string: an optional cookie path to force cookies to (ie: /foo) 273 -cookie-expire duration: expire timeframe for cookie (default 168h0m0s) 274 -cookie-httponly: set HttpOnly cookie flag (default true) 275 -cookie-name string: the name of the cookie that the oauth_proxy creates (default "_oauth2_proxy") 276 -cookie-refresh duration: refresh the cookie after this duration; 0 to disable 277 -cookie-secret string: the seed string for secure cookies (optionally base64 encoded) 278 -cookie-secure: set secure (HTTPS) cookie flag (default true) 279 -custom-templates-dir string: path to custom html templates 280 -display-htpasswd-form: display username / password login form if an htpasswd file is provided (default true) 281 -email-domain value: authenticate emails with the specified domain (may be given multiple times). Use * to authenticate any email 282 -flush-interval: period between flushing response buffers when streaming responses (default "1s") 283 -footer string: custom footer string. Use "-" to disable default footer. 284 -gcp-healthchecks: will enable /liveness_check, /readiness_check, and / (with the proper user-agent) endpoints that will make it work well with GCP App Engine and GKE Ingresses (default false) 285 -github-org string: restrict logins to members of this organisation 286 -github-team string: restrict logins to members of any of these teams (slug), separated by a comma 287 -google-admin-email string: the google admin to impersonate for api calls 288 -google-group value: restrict logins to members of this google group (may be given multiple times). 289 -google-service-account-json string: the path to the service account json credentials 290 -htpasswd-file string: additionally authenticate against a htpasswd file. Entries must be created with "htpasswd -s" for SHA encryption 291 -http-address string: [http://]<addr>:<port> or unix://<path> to listen on for HTTP clients (default "127.0.0.1:4180") 292 -https-address string: <addr>:<port> to listen on for HTTPS clients (default ":443") 293 -login-url string: Authentication endpoint 294 -oidc-issuer-url: the OpenID Connect issuer URL. ie: "https://accounts.google.com" 295 -oidc-jwks-url string: OIDC JWKS URI for token verification; required if OIDC discovery is disabled 296 -pass-access-token: pass OAuth access_token to upstream via X-Forwarded-Access-Token header 297 -pass-authorization-header: pass OIDC IDToken to upstream via Authorization Bearer header 298 -pass-basic-auth: pass HTTP Basic Auth, X-Forwarded-User and X-Forwarded-Email information to upstream (default true) 299 -pass-host-header: pass the request Host Header to upstream (default true) 300 -pass-user-headers: pass X-Forwarded-User and X-Forwarded-Email information to upstream (default true) 301 -profile-url string: Profile access endpoint 302 -provider string: OAuth provider (default "google") 303 -proxy-prefix string: the url root path that this proxy should be nested under (e.g. /<oauth2>/sign_in) (default "/oauth2") 304 -proxy-websockets: enables WebSocket proxying (default true) 305 -redeem-url string: Token redemption endpoint 306 -redirect-url string: the OAuth Redirect URL. ie: "https://internalapp.yourcompany.com/oauth2/callback" 307 -request-logging: Log requests to stdout (default true) 308 -request-logging-format: Template for request log lines (see "Logging Format" paragraph below) 309 -resource string: The resource that is protected (Azure AD only) 310 -scope string: OAuth scope specification 311 -set-xauthrequest: set X-Auth-Request-User and X-Auth-Request-Email response headers (useful in Nginx auth_request mode) 312 -set-authorization-header: set Authorization Bearer response header (useful in Nginx auth_request mode) 313 -signature-key string: GAP-Signature request signature key (algorithm:secretkey) 314 -skip-auth-preflight: will skip authentication for OPTIONS requests 315 -skip-auth-regex value: bypass authentication for requests path's that match (may be given multiple times) 316 -skip-oidc-discovery: bypass OIDC endpoint discovery. login-url, redeem-url and oidc-jwks-url must be configured in this case 317 -skip-provider-button: will skip sign-in-page to directly reach the next step: oauth/start 318 -ssl-insecure-skip-verify: skip validation of certificates presented when using HTTPS 319 -tls-cert string: path to certificate file 320 -tls-key string: path to private key file 321 -upstream value: the http url(s) of the upstream endpoint or file:// paths for static files. Routing is based on the path 322 -validate-url string: Access token validation endpoint 323 -version: print version string 324 -whitelist-domain: allowed domains for redirection after authentication. Prefix domain with a . to allow subdomains (eg .example.com) 325 ``` 326 327 Note, when using the `whitelist-domain` option, any domain prefixed with a `.` will allow any subdomain of the specified domain as a valid redirect URL. 328 329 See below for provider specific options 330 331 ### Upstreams Configuration 332 333 `oauth2_proxy` supports having multiple upstreams, and has the option to pass requests on to HTTP(S) servers or serve static files from the file system. HTTP and HTTPS upstreams are configured by providing a URL such as `http://127.0.0.1:8080/` for the upstream parameter, that will forward all authenticated requests to be forwarded to the upstream server. If you instead provide `http://127.0.0.1:8080/some/path/` then it will only be requests that start with `/some/path/` which are forwarded to the upstream. 334 335 Static file paths are configured as a file:// URL. `file:///var/www/static/` will serve the files from that directory at `http://[oauth2_proxy url]/var/www/static/`, which may not be what you want. You can provide the path to where the files should be available by adding a fragment to the configured URL. The value of the fragment will then be used to specify which path the files are available at. `file:///var/www/static/#/static/` will ie. make `/var/www/static/` available at `http://[oauth2_proxy url]/static/`. 336 337 Multiple upstreams can either be configured by supplying a comma separated list to the `-upstream` parameter, supplying the parameter multiple times or provinding a list in the [config file](#config-file). When multiple upstreams are used routing to them will be based on the path they are set up with. 338 339 ### Environment variables 340 341 The following environment variables can be used in place of the corresponding command-line arguments: 342 343 - `OAUTH2_PROXY_CLIENT_ID` 344 - `OAUTH2_PROXY_CLIENT_SECRET` 345 - `OAUTH2_PROXY_COOKIE_NAME` 346 - `OAUTH2_PROXY_COOKIE_SECRET` 347 - `OAUTH2_PROXY_COOKIE_DOMAIN` 348 - `OAUTH2_PROXY_COOKIE_PATH` 349 - `OAUTH2_PROXY_COOKIE_EXPIRE` 350 - `OAUTH2_PROXY_COOKIE_REFRESH` 351 - `OAUTH2_PROXY_SIGNATURE_KEY` 352 353 ## SSL Configuration 354 355 There are two recommended configurations. 356 357 1. Configure SSL Termination with OAuth2 Proxy by providing a `--tls-cert=/path/to/cert.pem` and `--tls-key=/path/to/cert.key`. 358 359 The command line to run `oauth2_proxy` in this configuration would look like this: 360 361 ```bash 362 ./oauth2_proxy \ 363 --email-domain="yourcompany.com" \ 364 --upstream=http://127.0.0.1:8080/ \ 365 --tls-cert=/path/to/cert.pem \ 366 --tls-key=/path/to/cert.key \ 367 --cookie-secret=... \ 368 --cookie-secure=true \ 369 --provider=... \ 370 --client-id=... \ 371 --client-secret=... 372 ``` 373 374 2. Configure SSL Termination with [Nginx](http://nginx.org/) (example config below), Amazon ELB, Google Cloud Platform Load Balancing, or .... 375 376 Because `oauth2_proxy` listens on `127.0.0.1:4180` by default, to listen on all interfaces (needed when using an 377 external load balancer like Amazon ELB or Google Platform Load Balancing) use `--http-address="0.0.0.0:4180"` or 378 `--http-address="http://:4180"`. 379 380 Nginx will listen on port `443` and handle SSL connections while proxying to `oauth2_proxy` on port `4180`. 381 `oauth2_proxy` will then authenticate requests for an upstream application. The external endpoint for this example 382 would be `https://internal.yourcompany.com/`. 383 384 An example Nginx config follows. Note the use of `Strict-Transport-Security` header to pin requests to SSL 385 via [HSTS](http://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security): 386 387 ``` 388 server { 389 listen 443 default ssl; 390 server_name internal.yourcompany.com; 391 ssl_certificate /path/to/cert.pem; 392 ssl_certificate_key /path/to/cert.key; 393 add_header Strict-Transport-Security max-age=2592000; 394 395 location / { 396 proxy_pass http://127.0.0.1:4180; 397 proxy_set_header Host $host; 398 proxy_set_header X-Real-IP $remote_addr; 399 proxy_set_header X-Scheme $scheme; 400 proxy_connect_timeout 1; 401 proxy_send_timeout 30; 402 proxy_read_timeout 30; 403 } 404 } 405 ``` 406 407 The command line to run `oauth2_proxy` in this configuration would look like this: 408 409 ```bash 410 ./oauth2_proxy \ 411 --email-domain="yourcompany.com" \ 412 --upstream=http://127.0.0.1:8080/ \ 413 --cookie-secret=... \ 414 --cookie-secure=true \ 415 --provider=... \ 416 --client-id=... \ 417 --client-secret=... 418 ``` 419 420 ## Endpoint Documentation 421 422 OAuth2 Proxy responds directly to the following endpoints. All other endpoints will be proxied upstream when authenticated. The `/oauth2` prefix can be changed with the `--proxy-prefix` config variable. 423 424 - /robots.txt - returns a 200 OK response that disallows all User-agents from all paths; see [robotstxt.org](http://www.robotstxt.org/) for more info 425 - /ping - returns a 200 OK response, which is intended for use with health checks 426 - /oauth2/sign_in - the login page, which also doubles as a sign out page (it clears cookies) 427 - /oauth2/start - a URL that will redirect to start the OAuth cycle 428 - /oauth2/callback - the URL used at the end of the OAuth cycle. The oauth app will be configured with this as the callback url. 429 - /oauth2/auth - only returns a 202 Accepted response or a 401 Unauthorized response; for use with the [Nginx `auth_request` directive](#nginx-auth-request) 430 431 ## Request signatures 432 433 If `signature_key` is defined, proxied requests will be signed with the 434 `GAP-Signature` header, which is a [Hash-based Message Authentication Code 435 (HMAC)](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code) 436 of selected request information and the request body [see `SIGNATURE_HEADERS` 437 in `oauthproxy.go`](./oauthproxy.go). 438 439 `signature_key` must be of the form `algorithm:secretkey`, (ie: `signature_key = "sha1:secret0"`) 440 441 For more information about HMAC request signature validation, read the 442 following: 443 444 - [Amazon Web Services: Signing and Authenticating REST 445 Requests](https://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html) 446 - [rc3.org: Using HMAC to authenticate Web service 447 requests](http://rc3.org/2011/12/02/using-hmac-to-authenticate-web-service-requests/) 448 449 ## Logging Format 450 451 By default, OAuth2 Proxy logs requests to stdout in a format similar to Apache Combined Log. 452 453 ``` 454 <REMOTE_ADDRESS> - <user@domain.com> [19/Mar/2015:17:20:19 -0400] <HOST_HEADER> GET <UPSTREAM_HOST> "/path/" HTTP/1.1 "<USER_AGENT>" <RESPONSE_CODE> <RESPONSE_BYTES> <REQUEST_DURATION> 455 ``` 456 457 If you require a different format than that, you can configure it with the `-request-logging-format` flag. 458 The default format is configured as follows: 459 460 ``` 461 {{.Client}} - {{.Username}} [{{.Timestamp}}] {{.Host}} {{.RequestMethod}} {{.Upstream}} {{.RequestURI}} {{.Protocol}} {{.UserAgent}} {{.StatusCode}} {{.ResponseSize}} {{.RequestDuration}} 462 ``` 463 464 [See `logMessageData` in `logging_handler.go`](./logging_handler.go) for all available variables. 465 466 ## Adding a new Provider 467 468 Follow the examples in the [`providers` package](providers/) to define a new 469 `Provider` instance. Add a new `case` to 470 [`providers.New()`](providers/providers.go) to allow `oauth2_proxy` to use the 471 new `Provider`. 472 473 ## <a name="nginx-auth-request"></a>Configuring for use with the Nginx `auth_request` directive 474 475 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: 476 477 ```nginx 478 server { 479 listen 443 ssl; 480 server_name ...; 481 include ssl/ssl.conf; 482 483 location /oauth2/ { 484 proxy_pass http://127.0.0.1:4180; 485 proxy_set_header Host $host; 486 proxy_set_header X-Real-IP $remote_addr; 487 proxy_set_header X-Scheme $scheme; 488 proxy_set_header X-Auth-Request-Redirect $request_uri; 489 } 490 location = /oauth2/auth { 491 proxy_pass http://127.0.0.1:4180; 492 proxy_set_header Host $host; 493 proxy_set_header X-Real-IP $remote_addr; 494 proxy_set_header X-Scheme $scheme; 495 # nginx auth_request includes headers but not body 496 proxy_set_header Content-Length ""; 497 proxy_pass_request_body off; 498 } 499 500 location / { 501 auth_request /oauth2/auth; 502 error_page 401 = /oauth2/sign_in; 503 504 # pass information via X-User and X-Email headers to backend, 505 # requires running with --set-xauthrequest flag 506 auth_request_set $user $upstream_http_x_auth_request_user; 507 auth_request_set $email $upstream_http_x_auth_request_email; 508 proxy_set_header X-User $user; 509 proxy_set_header X-Email $email; 510 511 # if you enabled --pass-access-token, this will pass the token to the backend 512 auth_request_set $token $upstream_http_x_auth_request_access_token; 513 proxy_set_header X-Access-Token $token; 514 515 # if you enabled --cookie-refresh, this is needed for it to work with auth_request 516 auth_request_set $auth_cookie $upstream_http_set_cookie; 517 add_header Set-Cookie $auth_cookie; 518 519 # When using the --set-authorization-header flag, some provider's cookies can exceed the 4kb 520 # limit and so the OAuth2 Proxy splits these into multiple parts. 521 # Nginx normally only copies the first `Set-Cookie` header from the auth_request to the response, 522 # so if your cookies are larger than 4kb, you will need to extract additional cookies manually. 523 auth_request_set $auth_cookie_name_upstream_1 $upstream_cookie_auth_cookie_name_1; 524 525 # Extract the Cookie attributes from the first Set-Cookie header and append them 526 # to the second part ($upstream_cookie_* variables only contain the raw cookie content) 527 if ($auth_cookie ~* "(; .*)") { 528 set $auth_cookie_name_0 $auth_cookie; 529 set $auth_cookie_name_1 "auth_cookie_name_1=$auth_cookie_name_upstream_1$1"; 530 } 531 532 # Send both Set-Cookie headers now if there was a second part 533 if ($auth_cookie_name_upstream_1) { 534 add_header Set-Cookie $auth_cookie_name_0; 535 add_header Set-Cookie $auth_cookie_name_1; 536 } 537 538 proxy_pass http://backend/; 539 # or "root /path/to/site;" or "fastcgi_pass ..." etc 540 } 541 } 542 ``` 543 544 If you use ingress-nginx in Kubernetes (which includes the Lua module), you also can use the following configuration snippet for your Ingress: 545 546 ```yaml 547 nginx.ingress.kubernetes.io/auth-response-headers: Authorization 548 nginx.ingress.kubernetes.io/auth-signin: https://$host/oauth2/start?rd=$request_uri 549 nginx.ingress.kubernetes.io/auth-url: https://$host/oauth2/auth 550 nginx.ingress.kubernetes.io/configuration-snippet: | 551 auth_request_set $name_upstream_1 $upstream_cookie_name_1; 552 553 access_by_lua_block { 554 if ngx.var.name_upstream_1 ~= "" then 555 ngx.header["Set-Cookie"] = "name_1=" .. ngx.var.name_upstream_1 .. ngx.var.auth_cookie:match("(; .*)") 556 end 557 } 558 ``` 559 560 ## Contributing 561 562 Please see our [Contributing](CONTRIBUTING.md) guidelines.