Migrate existing documentation to Docusaurus
This commit is contained in:
Joel Speed
parent
11bfd15566
commit
899c743afc
23
docs/.gitignore
vendored
23
docs/.gitignore
vendored
@ -1,3 +1,20 @@
|
||||
_site
|
||||
.sass-cache
|
||||
.jekyll-metadata
|
||||
# Dependencies
|
||||
/node_modules
|
||||
|
||||
# Production
|
||||
/build
|
||||
|
||||
# Generated files
|
||||
.docusaurus
|
||||
.cache-loader
|
||||
|
||||
# Misc
|
||||
.DS_Store
|
||||
.env.local
|
||||
.env.development.local
|
||||
.env.test.local
|
||||
.env.production.local
|
||||
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
|
||||
@ -1,32 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Home
|
||||
permalink: /
|
||||
nav_order: 0
|
||||
---
|
||||
|
||||
|
||||
|
||||
A reverse proxy and static file server that provides authentication using Providers (Google, GitHub, and others)
|
||||
to validate accounts by email, domain or group.
|
||||
|
||||
**Note:** This repository was forked from [bitly/OAuth2_Proxy](https://github.com/bitly/oauth2_proxy) on 27/11/2018.
|
||||
Versions v3.0.0 and up are from this fork and will have diverged from any changes in the original fork.
|
||||
A list of changes can be seen in the [CHANGELOG]({{ site.gitweb }}/CHANGELOG.md).
|
||||
|
||||
[](http://travis-ci.org/oauth2-proxy/oauth2-proxy)
|
||||
|
||||
|
||||
|
||||
## Architecture
|
||||
|
||||
|
||||
|
||||
## Behavior
|
||||
|
||||
1. Any request passing through the proxy (and not matched by `--skip-auth-regex`) is checked for the proxy's session cookie (`--cookie-name`) (or, if allowed, a JWT token - see `--skip-jwt-bearer-tokens`).
|
||||
2. If authentication is required but missing then the user is asked to log in and redirected to the authentication provider (unless it is an Ajax request, i.e. one with `Accept: application/json`, in which case 401 Unauthorized is returned)
|
||||
3. After returning from the authentication provider, the oauth tokens are stored in the configured session store (cookie, redis, ...) and a cookie is set
|
||||
4. The request is forwarded to the upstream server with added user info and authentication headers (depending on the configuration)
|
||||
|
||||
Notice that the proxy also provides a number of useful [endpoints](/oauth2-proxy/endpoints).
|
||||
@ -1,24 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
---
|
||||
|
||||
<style type="text/css" media="screen">
|
||||
.container {
|
||||
margin: 10px auto;
|
||||
max-width: 600px;
|
||||
text-align: center;
|
||||
}
|
||||
h1 {
|
||||
margin: 30px 0;
|
||||
font-size: 4em;
|
||||
line-height: 1;
|
||||
letter-spacing: -1px;
|
||||
}
|
||||
</style>
|
||||
|
||||
<div class="container">
|
||||
<h1>404</h1>
|
||||
|
||||
<p><strong>Page not found :(</strong></p>
|
||||
<p>The requested page could not be found.</p>
|
||||
</div>
|
||||
11
docs/Gemfile
11
docs/Gemfile
@ -1,11 +0,0 @@
|
||||
source "https://rubygems.org"
|
||||
gem "github-pages", group: :jekyll_plugins
|
||||
|
||||
# just-the-docs Jekyll theme
|
||||
gem "just-the-docs"
|
||||
|
||||
# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
|
||||
gem "tzinfo-data", platforms: [:mingw, :mswin, :x64_mingw, :jruby]
|
||||
|
||||
# Performance-booster for watching directories on Windows
|
||||
gem "wdm", "~> 0.1.0" if Gem.win_platform?
|
||||
@ -1,255 +0,0 @@
|
||||
GEM
|
||||
remote: https://rubygems.org/
|
||||
specs:
|
||||
activesupport (6.0.3.1)
|
||||
concurrent-ruby (~> 1.0, >= 1.0.2)
|
||||
i18n (>= 0.7, < 2)
|
||||
minitest (~> 5.1)
|
||||
tzinfo (~> 1.1)
|
||||
zeitwerk (~> 2.2, >= 2.2.2)
|
||||
addressable (2.7.0)
|
||||
public_suffix (>= 2.0.2, < 5.0)
|
||||
coffee-script (2.4.1)
|
||||
coffee-script-source
|
||||
execjs
|
||||
coffee-script-source (1.11.1)
|
||||
colorator (1.1.0)
|
||||
commonmarker (0.17.13)
|
||||
ruby-enum (~> 0.5)
|
||||
concurrent-ruby (1.1.6)
|
||||
dnsruby (1.61.3)
|
||||
addressable (~> 2.5)
|
||||
em-websocket (0.5.1)
|
||||
eventmachine (>= 0.12.9)
|
||||
http_parser.rb (~> 0.6.0)
|
||||
ethon (0.12.0)
|
||||
ffi (>= 1.3.0)
|
||||
eventmachine (1.2.7)
|
||||
execjs (2.7.0)
|
||||
faraday (1.0.0)
|
||||
multipart-post (>= 1.2, < 3)
|
||||
ffi (1.12.2)
|
||||
forwardable-extended (2.6.0)
|
||||
gemoji (3.0.1)
|
||||
github-pages (204)
|
||||
github-pages-health-check (= 1.16.1)
|
||||
jekyll (= 3.8.5)
|
||||
jekyll-avatar (= 0.7.0)
|
||||
jekyll-coffeescript (= 1.1.1)
|
||||
jekyll-commonmark-ghpages (= 0.1.6)
|
||||
jekyll-default-layout (= 0.1.4)
|
||||
jekyll-feed (= 0.13.0)
|
||||
jekyll-gist (= 1.5.0)
|
||||
jekyll-github-metadata (= 2.13.0)
|
||||
jekyll-mentions (= 1.5.1)
|
||||
jekyll-optional-front-matter (= 0.3.2)
|
||||
jekyll-paginate (= 1.1.0)
|
||||
jekyll-readme-index (= 0.3.0)
|
||||
jekyll-redirect-from (= 0.15.0)
|
||||
jekyll-relative-links (= 0.6.1)
|
||||
jekyll-remote-theme (= 0.4.1)
|
||||
jekyll-sass-converter (= 1.5.2)
|
||||
jekyll-seo-tag (= 2.6.1)
|
||||
jekyll-sitemap (= 1.4.0)
|
||||
jekyll-swiss (= 1.0.0)
|
||||
jekyll-theme-architect (= 0.1.1)
|
||||
jekyll-theme-cayman (= 0.1.1)
|
||||
jekyll-theme-dinky (= 0.1.1)
|
||||
jekyll-theme-hacker (= 0.1.1)
|
||||
jekyll-theme-leap-day (= 0.1.1)
|
||||
jekyll-theme-merlot (= 0.1.1)
|
||||
jekyll-theme-midnight (= 0.1.1)
|
||||
jekyll-theme-minimal (= 0.1.1)
|
||||
jekyll-theme-modernist (= 0.1.1)
|
||||
jekyll-theme-primer (= 0.5.4)
|
||||
jekyll-theme-slate (= 0.1.1)
|
||||
jekyll-theme-tactile (= 0.1.1)
|
||||
jekyll-theme-time-machine (= 0.1.1)
|
||||
jekyll-titles-from-headings (= 0.5.3)
|
||||
jemoji (= 0.11.1)
|
||||
kramdown (= 1.17.0)
|
||||
liquid (= 4.0.3)
|
||||
mercenary (~> 0.3)
|
||||
minima (= 2.5.1)
|
||||
nokogiri (>= 1.10.4, < 2.0)
|
||||
rouge (= 3.13.0)
|
||||
terminal-table (~> 1.4)
|
||||
github-pages-health-check (1.16.1)
|
||||
addressable (~> 2.3)
|
||||
dnsruby (~> 1.60)
|
||||
octokit (~> 4.0)
|
||||
public_suffix (~> 3.0)
|
||||
typhoeus (~> 1.3)
|
||||
html-pipeline (2.12.3)
|
||||
activesupport (>= 2)
|
||||
nokogiri (>= 1.4)
|
||||
http_parser.rb (0.6.0)
|
||||
i18n (0.9.5)
|
||||
concurrent-ruby (~> 1.0)
|
||||
jekyll (3.8.5)
|
||||
addressable (~> 2.4)
|
||||
colorator (~> 1.0)
|
||||
em-websocket (~> 0.5)
|
||||
i18n (~> 0.7)
|
||||
jekyll-sass-converter (~> 1.0)
|
||||
jekyll-watch (~> 2.0)
|
||||
kramdown (~> 1.14)
|
||||
liquid (~> 4.0)
|
||||
mercenary (~> 0.3.3)
|
||||
pathutil (~> 0.9)
|
||||
rouge (>= 1.7, < 4)
|
||||
safe_yaml (~> 1.0)
|
||||
jekyll-avatar (0.7.0)
|
||||
jekyll (>= 3.0, < 5.0)
|
||||
jekyll-coffeescript (1.1.1)
|
||||
coffee-script (~> 2.2)
|
||||
coffee-script-source (~> 1.11.1)
|
||||
jekyll-commonmark (1.3.1)
|
||||
commonmarker (~> 0.14)
|
||||
jekyll (>= 3.7, < 5.0)
|
||||
jekyll-commonmark-ghpages (0.1.6)
|
||||
commonmarker (~> 0.17.6)
|
||||
jekyll-commonmark (~> 1.2)
|
||||
rouge (>= 2.0, < 4.0)
|
||||
jekyll-default-layout (0.1.4)
|
||||
jekyll (~> 3.0)
|
||||
jekyll-feed (0.13.0)
|
||||
jekyll (>= 3.7, < 5.0)
|
||||
jekyll-gist (1.5.0)
|
||||
octokit (~> 4.2)
|
||||
jekyll-github-metadata (2.13.0)
|
||||
jekyll (>= 3.4, < 5.0)
|
||||
octokit (~> 4.0, != 4.4.0)
|
||||
jekyll-mentions (1.5.1)
|
||||
html-pipeline (~> 2.3)
|
||||
jekyll (>= 3.7, < 5.0)
|
||||
jekyll-optional-front-matter (0.3.2)
|
||||
jekyll (>= 3.0, < 5.0)
|
||||
jekyll-paginate (1.1.0)
|
||||
jekyll-readme-index (0.3.0)
|
||||
jekyll (>= 3.0, < 5.0)
|
||||
jekyll-redirect-from (0.15.0)
|
||||
jekyll (>= 3.3, < 5.0)
|
||||
jekyll-relative-links (0.6.1)
|
||||
jekyll (>= 3.3, < 5.0)
|
||||
jekyll-remote-theme (0.4.1)
|
||||
addressable (~> 2.0)
|
||||
jekyll (>= 3.5, < 5.0)
|
||||
rubyzip (>= 1.3.0)
|
||||
jekyll-sass-converter (1.5.2)
|
||||
sass (~> 3.4)
|
||||
jekyll-seo-tag (2.6.1)
|
||||
jekyll (>= 3.3, < 5.0)
|
||||
jekyll-sitemap (1.4.0)
|
||||
jekyll (>= 3.7, < 5.0)
|
||||
jekyll-swiss (1.0.0)
|
||||
jekyll-theme-architect (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-cayman (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-dinky (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-hacker (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-leap-day (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-merlot (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-midnight (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-minimal (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-modernist (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-primer (0.5.4)
|
||||
jekyll (> 3.5, < 5.0)
|
||||
jekyll-github-metadata (~> 2.9)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-slate (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-tactile (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-time-machine (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-titles-from-headings (0.5.3)
|
||||
jekyll (>= 3.3, < 5.0)
|
||||
jekyll-watch (2.2.1)
|
||||
listen (~> 3.0)
|
||||
jemoji (0.11.1)
|
||||
gemoji (~> 3.0)
|
||||
html-pipeline (~> 2.2)
|
||||
jekyll (>= 3.0, < 5.0)
|
||||
just-the-docs (0.2.7)
|
||||
jekyll (~> 3.8.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
rake (~> 12.3.1)
|
||||
kramdown (1.17.0)
|
||||
liquid (4.0.3)
|
||||
listen (3.2.1)
|
||||
rb-fsevent (~> 0.10, >= 0.10.3)
|
||||
rb-inotify (~> 0.9, >= 0.9.10)
|
||||
mercenary (0.3.6)
|
||||
mini_portile2 (2.4.0)
|
||||
minima (2.5.1)
|
||||
jekyll (>= 3.5, < 5.0)
|
||||
jekyll-feed (~> 0.9)
|
||||
jekyll-seo-tag (~> 2.1)
|
||||
minitest (5.14.1)
|
||||
multipart-post (2.1.1)
|
||||
nokogiri (1.10.9)
|
||||
mini_portile2 (~> 2.4.0)
|
||||
octokit (4.16.0)
|
||||
faraday (>= 0.9)
|
||||
sawyer (~> 0.8.0, >= 0.5.3)
|
||||
pathutil (0.16.2)
|
||||
forwardable-extended (~> 2.6)
|
||||
public_suffix (3.1.1)
|
||||
rake (12.3.3)
|
||||
rb-fsevent (0.10.3)
|
||||
rb-inotify (0.10.1)
|
||||
ffi (~> 1.0)
|
||||
rouge (3.13.0)
|
||||
ruby-enum (0.7.2)
|
||||
i18n
|
||||
rubyzip (2.2.0)
|
||||
safe_yaml (1.0.5)
|
||||
sass (3.7.4)
|
||||
sass-listen (~> 4.0.0)
|
||||
sass-listen (4.0.0)
|
||||
rb-fsevent (~> 0.9, >= 0.9.4)
|
||||
rb-inotify (~> 0.9, >= 0.9.7)
|
||||
sawyer (0.8.2)
|
||||
addressable (>= 2.3.5)
|
||||
faraday (> 0.8, < 2.0)
|
||||
terminal-table (1.8.0)
|
||||
unicode-display_width (~> 1.1, >= 1.1.1)
|
||||
thread_safe (0.3.6)
|
||||
typhoeus (1.3.1)
|
||||
ethon (>= 0.9.0)
|
||||
tzinfo (1.2.7)
|
||||
thread_safe (~> 0.1)
|
||||
unicode-display_width (1.6.1)
|
||||
zeitwerk (2.3.0)
|
||||
|
||||
PLATFORMS
|
||||
ruby
|
||||
|
||||
DEPENDENCIES
|
||||
github-pages
|
||||
just-the-docs
|
||||
tzinfo-data
|
||||
|
||||
BUNDLED WITH
|
||||
2.1.2
|
||||
@ -1,19 +0,0 @@
|
||||
.PHONY: ruby
|
||||
ruby:
|
||||
@ if [ ! $$(which ruby) ]; then \
|
||||
echo "Please install ruby version 2.5.0 or higher"; \
|
||||
fi
|
||||
|
||||
.PHONY: bundle
|
||||
bundle: ruby
|
||||
@ if [ ! $$(which bundle) ]; then \
|
||||
echo "Please install bundle: `gem install bundler`"; \
|
||||
fi
|
||||
|
||||
vendor/bundle: bundle
|
||||
bundle config set --local path 'vendor/bundle'
|
||||
bundle install
|
||||
|
||||
.PHONY: serve
|
||||
serve: vendor/bundle
|
||||
bundle exec jekyll serve
|
||||
@ -1,13 +1,33 @@
|
||||
# Docs
|
||||
# Website
|
||||
|
||||
This folder contains our Jekyll based docs site which is hosted at
|
||||
https://oauth2-proxy.github.io/oauth2-proxy.
|
||||
This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
|
||||
|
||||
When making changes to this docs site, please test your changes locally:
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
docs$ make serve
|
||||
```console
|
||||
yarn install
|
||||
```
|
||||
|
||||
To run the docs site locally you will need Ruby at version 2.5.0 or
|
||||
higher and `bundle` (`gem install bundler` if you already have Ruby).
|
||||
## Local Development
|
||||
|
||||
```console
|
||||
yarn start
|
||||
```
|
||||
|
||||
This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
|
||||
|
||||
## Build
|
||||
|
||||
```console
|
||||
yarn build
|
||||
```
|
||||
|
||||
This command generates static content into the `build` directory and can be served using any static contents hosting service.
|
||||
|
||||
## Deployment
|
||||
|
||||
```console
|
||||
GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
|
||||
```
|
||||
|
||||
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
|
||||
|
||||
@ -1,44 +0,0 @@
|
||||
# Welcome to Jekyll!
|
||||
#
|
||||
# This config file is meant for settings that affect your whole blog, values
|
||||
# which you are expected to set up once and rarely edit after that. If you find
|
||||
# yourself editing this file very often, consider using Jekyll's data files
|
||||
# feature for the data you need to update frequently.
|
||||
#
|
||||
# For technical reasons, this file is *NOT* reloaded automatically when you use
|
||||
# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
|
||||
|
||||
# Site settings
|
||||
# These are used to personalize your new site. If you look in the HTML files,
|
||||
# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
|
||||
# You can create any custom variable you would like, and they will be accessible
|
||||
# in the templates via {{ site.myvariable }}.
|
||||
title: OAuth2 Proxy
|
||||
logo: /logos/OAuth2_Proxy_horizontal.svg
|
||||
description: >- # this means to ignore newlines until "baseurl:"
|
||||
OAuth2-Proxy documentation site
|
||||
baseurl: "/oauth2-proxy" # the subpath of your site, e.g. /blog
|
||||
url: "https://oauth2-proxy.github.io" # the base hostname & protocol for your site, e.g. http://example.com
|
||||
gitweb: "https://github.com/oauth2-proxy/oauth2-proxy/blob/master"
|
||||
|
||||
# Build settings
|
||||
markdown: kramdown
|
||||
remote_theme: pmarsceill/just-the-docs
|
||||
search_enabled: true
|
||||
|
||||
# Aux links for the upper right navigation
|
||||
aux_links:
|
||||
"OAuth2 Proxy on GitHub":
|
||||
- "https://github.com/oauth2-proxy/oauth2-proxy"
|
||||
|
||||
# Exclude from processing.
|
||||
# The following items will not be processed, by default. Create a custom list
|
||||
# to override the default setting.
|
||||
# exclude:
|
||||
# - Gemfile
|
||||
# - Gemfile.lock
|
||||
# - node_modules
|
||||
# - vendor/bundle/
|
||||
# - vendor/cache/
|
||||
# - vendor/gems/
|
||||
# - vendor/ruby/
|
||||
@ -1,12 +0,0 @@
|
||||
---
|
||||
---
|
||||
{
|
||||
{% for page in site.html_pages %}"{{ forloop.index0 }}": {
|
||||
"id": "{{ forloop.index0 }}",
|
||||
"title": "{{ page.title | xml_escape }}",
|
||||
"content": "{{ page.content | markdownify | strip_html | xml_escape | remove: 'Table of contents' | strip_newlines | replace: '\', ' ' }}",
|
||||
"url": "{{ page.url | absolute_url | xml_escape }}",
|
||||
"relUrl": "{{ page.url | xml_escape }}"
|
||||
}{% if forloop.last %}{% else %},
|
||||
{% endif %}{% endfor %}
|
||||
}
|
||||
3
docs/babel.config.js
Normal file
3
docs/babel.config.js
Normal file
@ -0,0 +1,3 @@
|
||||
module.exports = {
|
||||
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
|
||||
};
|
||||
11
docs/docs/behaviour.md
Normal file
11
docs/docs/behaviour.md
Normal file
@ -0,0 +1,11 @@
|
||||
---
|
||||
id: behaviour
|
||||
title: Behaviour
|
||||
---
|
||||
|
||||
1. Any request passing through the proxy (and not matched by `--skip-auth-regex`) is checked for the proxy's session cookie (`--cookie-name`) (or, if allowed, a JWT token - see `--skip-jwt-bearer-tokens`).
|
||||
2. If authentication is required but missing then the user is asked to log in and redirected to the authentication provider (unless it is an Ajax request, i.e. one with `Accept: application/json`, in which case 401 Unauthorized is returned)
|
||||
3. After returning from the authentication provider, the oauth tokens are stored in the configured session store (cookie, redis, ...) and a cookie is set
|
||||
4. The request is forwarded to the upstream server with added user info and authentication headers (depending on the configuration)
|
||||
|
||||
Notice that the proxy also provides a number of useful [endpoints](features/endpoints.md).
|
||||
@ -1,12 +1,8 @@
|
||||
---
|
||||
layout: default
|
||||
title: Auth Configuration
|
||||
permalink: /auth-configuration
|
||||
nav_order: 2
|
||||
id: oauth_provider
|
||||
title: OAuth Provider Configuration
|
||||
---
|
||||
|
||||
## OAuth Provider Configuration
|
||||
|
||||
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.
|
||||
|
||||
Valid providers are :
|
||||
@ -89,7 +85,7 @@ Note: The user is checked against the group members list on initial authenticati
|
||||
--client-secret=<value from step 6>
|
||||
```
|
||||
|
||||
Note: When using the Azure Auth provider with nginx and the cookie session store you may find the cookie is too large and doesn't get passed through correctly. Increasing the proxy_buffer_size in nginx or implementing the [redis session storage](configuration/sessions#redis-storage) should resolve this.
|
||||
Note: When using the Azure Auth provider with nginx and the cookie session store you may find the cookie is too large and doesn't get passed through correctly. Increasing the proxy_buffer_size in nginx or implementing the [redis session storage](sessions.md#redis-storage) should resolve this.
|
||||
|
||||
### Facebook Auth Provider
|
||||
|
||||
@ -162,7 +158,7 @@ The following config should be set to ensure that the oauth will work properly.
|
||||
--client-secret=GITLAB_CLIENT_SECRET
|
||||
--cookie-secret=COOKIE_SECRET
|
||||
```
|
||||
|
||||
|
||||
Restricting by group membership is possible with the following option:
|
||||
|
||||
--gitlab-group="mygroup,myothergroup": restrict logins to members of any of these groups (slug), separated by a comma
|
||||
@ -454,7 +450,7 @@ To authorize by email domain use `--email-domain=yourcompany.com`. To authorize
|
||||
|
||||
## Adding a new Provider
|
||||
|
||||
Follow the examples in the [`providers` package]({{ site.gitweb }}/providers/) to define a new
|
||||
Follow the examples in the [`providers` package](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/providers/) to define a new
|
||||
`Provider` instance. Add a new `case` to
|
||||
[`providers.New()`]({{ site.gitweb }}/providers/providers.go) to allow `oauth2-proxy` to use the
|
||||
[`providers.New()`](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/providers/providers.go) to allow `oauth2-proxy` to use the
|
||||
new `Provider`.
|
||||
@ -1,13 +1,8 @@
|
||||
---
|
||||
layout: default
|
||||
title: Configuration
|
||||
permalink: /configuration
|
||||
has_children: true
|
||||
nav_order: 3
|
||||
id: overview
|
||||
title: Overview
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
`oauth2-proxy` can be configured via [config file](#config-file), [command line options](#command-line-options) or [environment variables](#environment-variables).
|
||||
|
||||
To generate a strong cookie secret use `python -c 'import os,base64; print(base64.urlsafe_b64encode(os.urandom(16)).decode())'`
|
||||
@ -16,7 +11,7 @@ To generate a strong cookie secret use `python -c 'import os,base64; print(base6
|
||||
|
||||
Every command line argument can be specified in a config file by replacing hyphens (-) with underscores (\_). If the argument can be specified multiple times, the config option should be plural (trailing s).
|
||||
|
||||
An example [oauth2-proxy.cfg]({{ site.gitweb }}/contrib/oauth2-proxy.cfg.example) config file is in the contrib directory. It can be used by specifying `--config=/etc/oauth2-proxy.cfg`
|
||||
An example [oauth2-proxy.cfg](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/contrib/oauth2-proxy.cfg.example) config file is in the contrib directory. It can be used by specifying `--config=/etc/oauth2-proxy.cfg`
|
||||
|
||||
### Command Line Options
|
||||
|
||||
@ -112,7 +107,7 @@ An example [oauth2-proxy.cfg]({{ site.gitweb }}/contrib/oauth2-proxy.cfg.example
|
||||
| `--reverse-proxy` | bool | are we running behind a reverse proxy, controls whether headers like X-Real-IP are accepted | false |
|
||||
| `--scope` | string | OAuth scope specification | |
|
||||
| `--session-cookie-minimal` | bool | strip OAuth tokens from cookie session stores if they aren't needed (cookie session store only) | false |
|
||||
| `--session-store-type` | string | [Session data storage backend](configuration/sessions); redis or cookie | cookie |
|
||||
| `--session-store-type` | string | [Session data storage backend](sessions.md); redis or cookie | cookie |
|
||||
| `--set-xauthrequest` | bool | set X-Auth-Request-User, X-Auth-Request-Groups, X-Auth-Request-Email and X-Auth-Request-Preferred-Username response headers (useful in Nginx auth_request mode). When used with `--pass-access-token`, X-Auth-Request-Access-Token is added to response headers. | false |
|
||||
| `--set-authorization-header` | bool | set Authorization Bearer response header (useful in Nginx auth_request mode) | false |
|
||||
| `--set-basic-auth` | bool | set HTTP Basic Auth information in response (useful in Nginx auth_request mode) | false |
|
||||
@ -195,7 +190,7 @@ If you require a different format than that, you can configure it with the `--au
|
||||
The default format is configured as follows:
|
||||
|
||||
```
|
||||
{% raw %}{{.Client}} - {{.Username}} [{{.Timestamp}}] [{{.Status}}] {{.Message}}{% endraw %}
|
||||
{{.Client}} - {{.Username}} [{{.Timestamp}}] [{{.Status}}] {{.Message}}
|
||||
```
|
||||
|
||||
Available variables for auth logging:
|
||||
@ -223,7 +218,7 @@ If you require a different format than that, you can configure it with the `--re
|
||||
The default format is configured as follows:
|
||||
|
||||
```
|
||||
{% raw %}{{.Client}} - {{.Username}} [{{.Timestamp}}] {{.Host}} {{.RequestMethod}} {{.Upstream}} {{.RequestURI}} {{.Protocol}} {{.UserAgent}} {{.StatusCode}} {{.ResponseSize}} {{.RequestDuration}}{% endraw %}
|
||||
{{.Client}} - {{.Username}} [{{.Timestamp}}] {{.Host}} {{.RequestMethod}} {{.Upstream}} {{.RequestURI}} {{.Protocol}} {{.UserAgent}} {{.StatusCode}} {{.ResponseSize}} {{.RequestDuration}}
|
||||
```
|
||||
|
||||
Available variables for request logging:
|
||||
@ -253,7 +248,7 @@ All other logging that is not covered by the above two types of logging will be
|
||||
If you require a different format than that, you can configure it with the `--standard-logging-format` flag. The default format is configured as follows:
|
||||
|
||||
```
|
||||
{% raw %}[{{.Timestamp}}] [{{.File}}] {{.Message}}{% endraw %}
|
||||
[{{.Timestamp}}] [{{.File}}] {{.Message}}
|
||||
```
|
||||
|
||||
Available variables for standard logging:
|
||||
@ -264,7 +259,7 @@ Available variables for standard logging:
|
||||
| File | main.go:40 | The file and line number of the logging statement. |
|
||||
| Message | HTTP: listening on 127.0.0.1:4180 | The details of the log statement. |
|
||||
|
||||
## <a name="nginx-auth-request"></a>Configuring for use with the Nginx `auth_request` directive
|
||||
## Configuring for use with the Nginx `auth_request` directive
|
||||
|
||||
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:
|
||||
|
||||
@ -358,5 +353,6 @@ It is recommended to use `--session-store-type=redis` when expecting large sessi
|
||||
|
||||
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=".
|
||||
|
||||
### Note on rotated Client Secret
|
||||
:::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.
|
||||
:::
|
||||
@ -1,13 +1,8 @@
|
||||
---
|
||||
layout: default
|
||||
title: Sessions
|
||||
permalink: /configuration/sessions
|
||||
parent: Configuration
|
||||
nav_order: 3
|
||||
id: session_storage
|
||||
title: Session Storage
|
||||
---
|
||||
|
||||
## Sessions
|
||||
|
||||
Sessions allow a user's authentication to be tracked between multiple HTTP
|
||||
requests to a service.
|
||||
|
||||
@ -38,7 +33,7 @@ users to re-authenticate
|
||||
### Redis Storage
|
||||
|
||||
The Redis Storage backend stores sessions, encrypted, in redis. Instead sending all the information
|
||||
back the the client for storage, as in the [Cookie storage](cookie-storage), a ticket is sent back
|
||||
back the the client for storage, as in the [Cookie storage](#cookie-storage), a ticket is sent back
|
||||
to the user as the cookie value instead.
|
||||
|
||||
A ticket is composed as the following:
|
||||
@ -66,7 +61,7 @@ You may also configure the store for Redis Sentinel. In this case, you will want
|
||||
`--redis-use-sentinel=true` flag, as well as configure the flags `--redis-sentinel-master-name`
|
||||
and `--redis-sentinel-connection-urls` appropriately.
|
||||
|
||||
Redis Cluster is available to be the backend store as well. To leverage it, you will need to set the
|
||||
Redis Cluster is available to be the backend store as well. To leverage it, you will need to set the
|
||||
`--redis-use-cluster=true` flag, and configure the flags `--redis-cluster-connection-urls` appropriately.
|
||||
|
||||
Note that flags `--redis-use-sentinel=true` and `--redis-use-cluster=true` are mutually exclusive.
|
||||
@ -1,12 +1,8 @@
|
||||
---
|
||||
layout: default
|
||||
id: tls
|
||||
title: TLS Configuration
|
||||
permalink: /tls-configuration
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
## SSL Configuration
|
||||
|
||||
There are two recommended configurations.
|
||||
|
||||
1. Configure SSL Termination with OAuth2 Proxy by providing a `--tls-cert-file=/path/to/cert.pem` and `--tls-key-file=/path/to/cert.key`.
|
||||
@ -1,12 +1,8 @@
|
||||
---
|
||||
layout: default
|
||||
id: endpoints
|
||||
title: Endpoints
|
||||
permalink: /endpoints
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
## Endpoint Documentation
|
||||
|
||||
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.
|
||||
|
||||
- /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
|
||||
@ -16,7 +12,7 @@ OAuth2 Proxy responds directly to the following endpoints. All other endpoints w
|
||||
- /oauth2/start - a URL that will redirect to start the OAuth cycle
|
||||
- /oauth2/callback - the URL used at the end of the OAuth cycle. The oauth app will be configured with this as the callback url.
|
||||
- /oauth2/userinfo - the URL is used to return user's email from the session in JSON format.
|
||||
- /oauth2/auth - only returns a 202 Accepted response or a 401 Unauthorized response; for use with the [Nginx `auth_request` directive](#nginx-auth-request)
|
||||
- /oauth2/auth - only returns a 202 Accepted response or a 401 Unauthorized response; for use with the [Nginx `auth_request` directive](../configuration/overview.md#configuring-for-use-with-the-nginx-auth_request-directive)
|
||||
|
||||
### Sign out
|
||||
|
||||
@ -36,4 +32,4 @@ X-Auth-Request-Redirect: https://my-oidc-provider/sign_out_page
|
||||
|
||||
(The "sign_out_page" should be the [`end_session_endpoint`](https://openid.net/specs/openid-connect-session-1_0.html#rfc.section.2.1) from [the metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig) if your OIDC provider supports Session Management and Discovery.)
|
||||
|
||||
BEWARE that the domain you want to redirect to (`my-oidc-provider.example.com` in the example) must be added to the [`--whitelist-domain`](configuration) configuration option otherwise the redirect will be ignored.
|
||||
BEWARE that the domain you want to redirect to (`my-oidc-provider.example.com` in the example) must be added to the [`--whitelist-domain`](../configuration/overview) configuration option otherwise the redirect will be ignored.
|
||||
@ -1,17 +1,13 @@
|
||||
---
|
||||
layout: default
|
||||
id: request_signatures
|
||||
title: Request Signatures
|
||||
permalink: /request-signatures
|
||||
nav_order: 6
|
||||
---
|
||||
|
||||
## Request signatures
|
||||
|
||||
If `signature_key` is defined, proxied requests will be signed with the
|
||||
`GAP-Signature` header, which is a [Hash-based Message Authentication Code
|
||||
(HMAC)](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code)
|
||||
of selected request information and the request body [see `SIGNATURE_HEADERS`
|
||||
in `oauthproxy.go`]({{ site.gitweb }}/oauthproxy.go).
|
||||
in `oauthproxy.go`](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/oauthproxy.go).
|
||||
|
||||
`signature_key` must be of the form `algorithm:secretkey`, (ie: `signature_key = "sha1:secret0"`)
|
||||
|
||||
@ -1,12 +1,9 @@
|
||||
---
|
||||
layout: default
|
||||
id: installation
|
||||
title: Installation
|
||||
permalink: /installation
|
||||
nav_order: 1
|
||||
slug: /
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
1. Choose how to deploy:
|
||||
|
||||
a. Download [Prebuilt Binary](https://github.com/oauth2-proxy/oauth2-proxy/releases) (current release is `v6.1.1`)
|
||||
@ -22,6 +19,6 @@ $ sha256sum -c sha256sum.txt 2>&1 | grep OK
|
||||
oauth2-proxy-x.y.z.linux-amd64: OK
|
||||
```
|
||||
|
||||
2. [Select a Provider and Register an OAuth Application with a Provider](auth-configuration)
|
||||
3. [Configure OAuth2 Proxy using config file, command line options, or environment variables](configuration)
|
||||
4. [Configure SSL or Deploy behind a SSL endpoint](tls-configuration) (example provided for Nginx)
|
||||
2. [Select a Provider and Register an OAuth Application with a Provider](configuration/auth.md)
|
||||
3. [Configure OAuth2 Proxy using config file, command line options, or environment variables](configuration/overview.md)
|
||||
4. [Configure SSL or Deploy behind a SSL endpoint](configuration/tls.md) (example provided for Nginx)
|
||||
52
docs/docusaurus.config.js
Normal file
52
docs/docusaurus.config.js
Normal file
@ -0,0 +1,52 @@
|
||||
module.exports = {
|
||||
title: 'OAuth2 Proxy',
|
||||
tagline: 'A lightweight authentication proxy written in Go',
|
||||
url: 'https://oauth2-proxy.github.io',
|
||||
baseUrl: '/oauth2-proxy/',
|
||||
onBrokenLinks: 'throw',
|
||||
favicon: 'img/logos/OAuth2_Proxy_icon.svg',
|
||||
organizationName: 'oauth2-proxy', // Usually your GitHub org/user name.
|
||||
projectName: 'oauth2-proxy', // Usually your repo name.
|
||||
themeConfig: {
|
||||
navbar: {
|
||||
title: 'OAuth2 Proxy',
|
||||
logo: {
|
||||
alt: 'OAuth2 Proxy',
|
||||
src: 'img/logos/OAuth2_Proxy_icon.svg',
|
||||
},
|
||||
items: [
|
||||
{
|
||||
to: 'docs/',
|
||||
activeBasePath: 'docs',
|
||||
label: 'Docs',
|
||||
position: 'left',
|
||||
},
|
||||
{
|
||||
href: 'https://github.com/oauth2-proxy/oauth2-proxy',
|
||||
label: 'GitHub',
|
||||
position: 'right',
|
||||
},
|
||||
],
|
||||
},
|
||||
footer: {
|
||||
style: 'dark',
|
||||
copyright: `Copyright © ${new Date().getFullYear()} OAuth2 Proxy.`,
|
||||
},
|
||||
},
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
sidebarPath: require.resolve('./sidebars.js'),
|
||||
// Please change this to your repo.
|
||||
editUrl:
|
||||
'https://github.com/oauth2-proxy/oauth2-proxy/edit/master/docs/',
|
||||
},
|
||||
theme: {
|
||||
customCss: require.resolve('./src/css/custom.css'),
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
14114
docs/package-lock.json
generated
Normal file
14114
docs/package-lock.json
generated
Normal file
File diff suppressed because it is too large
Load Diff
33
docs/package.json
Normal file
33
docs/package.json
Normal file
@ -0,0 +1,33 @@
|
||||
{
|
||||
"name": "docusaurus",
|
||||
"version": "0.0.0",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"docusaurus": "docusaurus",
|
||||
"start": "docusaurus start",
|
||||
"build": "docusaurus build",
|
||||
"swizzle": "docusaurus swizzle",
|
||||
"deploy": "docusaurus deploy",
|
||||
"serve": "docusaurus serve"
|
||||
},
|
||||
"dependencies": {
|
||||
"@docusaurus/core": "2.0.0-alpha.66",
|
||||
"@docusaurus/preset-classic": "2.0.0-alpha.66",
|
||||
"@mdx-js/react": "^1.5.8",
|
||||
"clsx": "^1.1.1",
|
||||
"react": "^16.8.4",
|
||||
"react-dom": "^16.8.4"
|
||||
},
|
||||
"browserslist": {
|
||||
"production": [
|
||||
">0.2%",
|
||||
"not dead",
|
||||
"not op_mini all"
|
||||
],
|
||||
"development": [
|
||||
"last 1 chrome version",
|
||||
"last 1 firefox version",
|
||||
"last 1 safari version"
|
||||
]
|
||||
}
|
||||
}
|
||||
24
docs/sidebars.js
Normal file
24
docs/sidebars.js
Normal file
@ -0,0 +1,24 @@
|
||||
module.exports = {
|
||||
docs: [
|
||||
{
|
||||
type: 'doc',
|
||||
id: 'installation',
|
||||
},
|
||||
{
|
||||
type: 'doc',
|
||||
id: 'behaviour',
|
||||
},
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Configuration',
|
||||
collapsed: false,
|
||||
items: ['configuration/overview', 'configuration/oauth_provider', 'configuration/session_storage', 'configuration/tls'],
|
||||
},
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Features',
|
||||
collapsed: false,
|
||||
items: ['features/endpoints', 'features/request_signatures'],
|
||||
},
|
||||
],
|
||||
};
|
||||
25
docs/src/css/custom.css
Normal file
25
docs/src/css/custom.css
Normal file
@ -0,0 +1,25 @@
|
||||
/* stylelint-disable docusaurus/copyright-header */
|
||||
/**
|
||||
* Any CSS included here will be global. The classic template
|
||||
* bundles Infima by default. Infima is a CSS framework designed to
|
||||
* work well for content-centric websites.
|
||||
*/
|
||||
|
||||
/* You can override the default Infima variables here. */
|
||||
:root {
|
||||
--ifm-color-primary: #25c2a0;
|
||||
--ifm-color-primary-dark: rgb(33, 175, 144);
|
||||
--ifm-color-primary-darker: rgb(31, 165, 136);
|
||||
--ifm-color-primary-darkest: rgb(26, 136, 112);
|
||||
--ifm-color-primary-light: rgb(70, 203, 174);
|
||||
--ifm-color-primary-lighter: rgb(102, 212, 189);
|
||||
--ifm-color-primary-lightest: rgb(146, 224, 208);
|
||||
--ifm-code-font-size: 95%;
|
||||
}
|
||||
|
||||
.docusaurus-highlight-code-line {
|
||||
background-color: rgb(72, 77, 91);
|
||||
display: block;
|
||||
margin: 0 calc(-1 * var(--ifm-pre-padding));
|
||||
padding: 0 var(--ifm-pre-padding);
|
||||
}
|
||||
21
docs/src/pages/index.md
Normal file
21
docs/src/pages/index.md
Normal file
@ -0,0 +1,21 @@
|
||||
---
|
||||
title: Welcome to OAuth2 Proxy
|
||||
hide_table_of_contents: true
|
||||
---
|
||||
|
||||
|
||||
|
||||
A reverse proxy and static file server that provides authentication using Providers (Google, GitHub, and others)
|
||||
to validate accounts by email, domain or group.
|
||||
|
||||
:::note
|
||||
This repository was forked from [bitly/OAuth2_Proxy](https://github.com/bitly/oauth2_proxy) on 27/11/2018.
|
||||
Versions v3.0.0 and up are from this fork and will have diverged from any changes in the original fork.
|
||||
A list of changes can be seen in the [CHANGELOG](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/CHANGELOG.md).
|
||||
:::
|
||||
|
||||
|
||||
|
||||
## Architecture
|
||||
|
||||
|
||||
37
docs/src/pages/styles.module.css
Normal file
37
docs/src/pages/styles.module.css
Normal file
@ -0,0 +1,37 @@
|
||||
/* stylelint-disable docusaurus/copyright-header */
|
||||
|
||||
/**
|
||||
* CSS files with the .module.css suffix will be treated as CSS modules
|
||||
* and scoped locally.
|
||||
*/
|
||||
|
||||
.heroBanner {
|
||||
padding: 4rem 0;
|
||||
text-align: center;
|
||||
position: relative;
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
@media screen and (max-width: 966px) {
|
||||
.heroBanner {
|
||||
padding: 2rem;
|
||||
}
|
||||
}
|
||||
|
||||
.buttons {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
}
|
||||
|
||||
.features {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
padding: 2rem 0;
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
.featureImage {
|
||||
height: 200px;
|
||||
width: 200px;
|
||||
}
|
||||
0
docs/static/.nojekyll
vendored
Normal file
0
docs/static/.nojekyll
vendored
Normal file
BIN
docs/static/img/architecture.png
vendored
Normal file
BIN
docs/static/img/architecture.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
|
Before Width: | Height: | Size: 108 KiB After Width: | Height: | Size: 108 KiB |
|
Before Width: | Height: | Size: 6.1 KiB After Width: | Height: | Size: 6.1 KiB |
|
Before Width: | Height: | Size: 47 KiB After Width: | Height: | Size: 47 KiB |
|
Before Width: | Height: | Size: 1.1 KiB After Width: | Height: | Size: 1.1 KiB |
|
Before Width: | Height: | Size: 55 KiB After Width: | Height: | Size: 55 KiB |
|
Before Width: | Height: | Size: 5.9 KiB After Width: | Height: | Size: 5.9 KiB |
BIN
docs/static/img/sign-in-page.png
vendored
Normal file
BIN
docs/static/img/sign-in-page.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
Loading…
x
Reference in New Issue
Block a user