mirror of
https://github.com/mother-of-all-self-hosting/mash-playbook
synced 2024-11-10 06:14:17 +00:00
Add OAuth2-Proxy support
This commit is contained in:
Slavi Pantaleev
parent
9b7128265b
commit
74c52bec2d
8 changed files with 215 additions and 1 deletions
|
|
@ -196,3 +196,4 @@ If a dedicated variable is not available for you to use or if you wish to overri
|
|||
|
||||
- [authentik](authentik.md) - An open-source Identity Provider focused on flexibility and versatility.
|
||||
- [Keycloak](keycloak.md) - An open source identity and access management solution
|
||||
- [OAuth2-Proxy](oauth2-proxy.md) - A reverse proxy and static file server that provides authentication using OpenID Connect Providers (Google, GitHub, [Authentik](authentik.md), [Keycloak](keycloak.md), and others) to SSO-protect services which do not support SSO natively
|
||||
|
|
|
|||
|
|
@ -36,3 +36,6 @@ hubsite_subtitle: "Just click on a service to use it"
|
|||
# /hubsite #
|
||||
# #
|
||||
########################################################################
|
||||
```
|
||||
|
||||
You can SSO-protect this website with the help of [Authelia](authelia.md) or [OAuth2-Proxy](oauth2-proxy.md) (connected to any OIDC provider).
|
||||
|
|
|
|||
|
|
@ -54,8 +54,14 @@ On each start after that, Keycloak will attempt to create the user again and rep
|
|||
|
||||
Subsequent changes to the password will not affect an existing user's password.
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
After installation, you can go to the Keycloak URL, as defined in `keycloak_hostname` and `keycloak_path_prefix` and log in as described in [Authentication](#authentication).
|
||||
|
||||
Follow the [Keycloak documentation](https://www.keycloak.org/documentation) or other guides for learning how to use Keycloak.
|
||||
|
||||
|
||||
## Related services
|
||||
|
||||
- [OAuth2-Proxy](oauth2-proxy.md) - A reverse proxy and static file server that provides authentication using OpenID Connect Providers (Google, GitHub, [Authentik](authentik.md), [Keycloak](keycloak.md), and others) to SSO-protect services which do not support SSO natively
|
||||
|
|
|
|||
158
docs/services/oauth2-proxy.md
Normal file
158
docs/services/oauth2-proxy.md
Normal file
|
|
@ -0,0 +1,158 @@
|
|||
# OAuth2-Proxy
|
||||
|
||||
[OAuth2-Proxy](https://oauth2-proxy.github.io/oauth2-proxy/) is a reverse proxy and static file server that provides authentication using OpenID Connect Providers (Google, GitHub, [Authentik](authentik.md), [Keycloak](keycloak.md), and others) to SSO-protect services which do not support SSO natively.
|
||||
|
||||
|
||||
## Modes of operation
|
||||
|
||||
OAuth2-Proxy can be used in 2 different modes:
|
||||
|
||||
1. Capturing incoming traffic for the app (e.g. https://app.example.com/), and then proxying it to the application container if the user is authenticated
|
||||
|
||||
2. Letting the application itself capture incoming traffic for itself (on https://app.example.com/) and use Traefik's [ForwardAuth](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) middleware to authenticate the request via OAuth2-Proxy. In this case, OAuth2-Proxy will only handle the `/oauth2/` prefix on the application domain (e.g. https://app.example.com/oauth/).
|
||||
|
||||
The 1st one is a bit invasive, as it requires moving all custom reverse-proxying configuration for the handled domain to the OAuth2-Proxy side.
|
||||
|
||||
The 2nd one lets you keep the existing application configuration. However, it needs all URLs to go to one service (the application) with the exception of `/oauth2/` (which should go to OAuth2-Proxy). As such, it it requires that both services (the application and OAuth2-Proxy) run on the same machine.
|
||||
|
||||
Our [Sample configuration](#sample-configuration) below uses [ForwardAuth](https://doc.traefik.io/traefik/middlewares/http/forwardauth/).
|
||||
|
||||
The [OAuth2-Proxy Ansible role](https://github.com/mother-of-all-self-hosting/ansible-role-oauth2-proxy) should be flexible enough to let you reconfigure it for both modes of operation. However, if feasible, we recommend using the 2nd (ForwardAuth) method.
|
||||
|
||||
## Dependencies
|
||||
|
||||
This service requires the following other services:
|
||||
|
||||
- a [Traefik](traefik.md) reverse-proxy server
|
||||
- an OIDC provider running anywhere. See [Choosing a provider](#choosing-a-provider).
|
||||
|
||||
|
||||
## Choosing a provider
|
||||
|
||||
To use OAuth2-Proxy, you need to choose an [OIDC provider](https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/).
|
||||
|
||||
This can be any of the supported providers. If hosting your own (via this playbook or via other means), the OIDC provider may be hosted anywhere (not necessarily on the same server as OAuth2-Proxy or the service you're SSO-protecting).
|
||||
|
||||
|
||||
## Sample configuration
|
||||
|
||||
The configuration is [provider](https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/)-specific and also depends on the the service you're SSO-protecting, on which server it runs (in relation to OAuth-Proxy), etc.
|
||||
|
||||
Below is a **sample** configuration for protecting a static website (in this case powered by the [Hubsite](hubsite.md)) service via [Keycloak](keycloak.md).
|
||||
|
||||
For this to work as described here, both OAuth2-Proxy and the protected service (e.g. [Hubsite](hubsite.md)) need to run on the same machine.
|
||||
|
||||
Keycloak may run anywhere.
|
||||
|
||||
You also need to have prepared Keycloak and a "Client app" for it, according to the [Keycloak OIDC](https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/keycloak_oidc) documentation of OAuth2-Proxy.
|
||||
|
||||
|
||||
#### OAuth2-Proxy configuration
|
||||
|
||||
```yaml
|
||||
########################################################################
|
||||
# #
|
||||
# oauth2_proxy #
|
||||
# #
|
||||
########################################################################
|
||||
|
||||
oauth2_proxy_enabled: true
|
||||
|
||||
oauth2_proxy_environment_variable_provider: keycloak-oidc
|
||||
oauth2_proxy_environment_variable_provider_display_name: SSO
|
||||
|
||||
oauth2_proxy_environment_variable_client_id: hubsite
|
||||
oauth2_proxy_environment_variable_client_secret: ''
|
||||
oauth2_proxy_environment_variable_oidc_issuer_url: https://keycloak.example.com/realms/my-realm
|
||||
oauth2_proxy_environment_variable_redirect_url: "https://{{ hubsite_hostname }}/oauth2/callback"
|
||||
|
||||
oauth2_proxy_environment_variable_code_challenge_method: S256
|
||||
|
||||
# Generate this with: `python -c 'import os,base64; print(base64.urlsafe_b64encode(os.urandom(32)).decode())'`
|
||||
oauth2_proxy_environment_variable_cookie_secret: ''
|
||||
|
||||
oauth2_proxy_container_labels_additional_labels: |
|
||||
traefik.http.routers.{{ oauth2_proxy_identifier }}-hubsite.rule=Host(`{{ hubsite_hostname }}`) && PathPrefix(`/oauth2/`)
|
||||
traefik.http.routers.{{ oauth2_proxy_identifier }}-hubsite.service={{ oauth2_proxy_identifier }}
|
||||
traefik.http.routers.{{ oauth2_proxy_identifier }}-hubsite.entrypoints={{ oauth2_proxy_container_labels_traefik_entrypoints }}
|
||||
traefik.http.routers.{{ oauth2_proxy_identifier }}-hubsite.tls={{ oauth2_proxy_container_labels_traefik_tls }}
|
||||
traefik.http.routers.{{ oauth2_proxy_identifier }}-hubsite.tls.certResolver={{ oauth2_proxy_container_labels_traefik_tls_certResolver }}
|
||||
|
||||
########################################################################
|
||||
# #
|
||||
# /oauth2_proxy #
|
||||
# #
|
||||
########################################################################
|
||||
```
|
||||
|
||||
After adding this to your `vars.yml` file, [re-run the playbook](../installing.md): `just install-service oauth-2proxy`.
|
||||
|
||||
This merely configures OAuth2-Proxy to handle the `/oauth2/` paths for Hubsite's domain.
|
||||
|
||||
[Hubsite configuration adjustments](#hubsite-configuration-adjustments) are also necessary, so proceed to do those as well.
|
||||
|
||||
|
||||
### Hubsite configuration adjustments
|
||||
|
||||
Now that OAuth2-Proxy is ready and handling the `/oauth2/` paths on the domain Hubsite is running, we need to set up Traefik's [ForwardAuth](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) middlware, so that all Hubsite requests would consult OAuth2-Proxy.
|
||||
|
||||
The configuration described below is based on the official [Configuring for use with the Traefik (v2) ForwardAuth middleware](https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview#configuring-for-use-with-the-traefik-v2-forwardauth-middleware) documentation of OAuth2-Proxy.
|
||||
|
||||
```yml
|
||||
########################################################################
|
||||
# #
|
||||
# hubsite #
|
||||
# #
|
||||
########################################################################
|
||||
|
||||
# Your other Hubsite configuration goes here.
|
||||
# See the documentation in hubsite.md.
|
||||
|
||||
hubsite_container_labels_additional_labels: |
|
||||
# Create a middleware which catches "unauthenticated" errors and serves the OAuth-Proxy sign in page.
|
||||
traefik.http.middlewares.{{ hubsite_identifier }}-oauth-errors.errors.status=401-403
|
||||
traefik.http.middlewares.{{ hubsite_identifier }}-oauth-errors.errors.service={{ oauth2_proxy_identifier }}
|
||||
traefik.http.middlewares.{{ hubsite_identifier }}-oauth-errors.errors.query=/oauth2/sign_in?rd={url}
|
||||
|
||||
# Create a middlware which passes each incoming request to OAuth2-Proxy,
|
||||
# so it can decide whether it should be let through (to Hubsite) or should blocked (serving the OAuth2-Proxy sign in page).
|
||||
traefik.http.middlewares.{{ hubsite_identifier }}-oauth-auth.forwardAuth.address=http://{{ oauth2_proxy_identifier }}:{{ oauth2_proxy_container_process_http_port }}/oauth2/auth
|
||||
|
||||
traefik.http.middlewares.{{ hubsite_identifier }}-oauth-auth.forwardAuth.trustForwardHeader=true
|
||||
|
||||
# Let a few HTTP headers set by OAuth2-Proxy get passed to Hubsite.
|
||||
# Hubsite is a static website, so it cannot make use of them.
|
||||
# Nevertheless, this is here as an example of how you can whitelist headers,
|
||||
# so that applications which can make use of these headers can benefit from it.
|
||||
# See more information about this in the comments for `oauth2_proxy_environment_variable_set_xauthrequest`.
|
||||
traefik.http.middlewares.{{ hubsite_identifier }}-oauth-auth.forwardAuth.authResponseHeaders=X-Auth-Request-Preferred-Username, X-Auth-Request-Groups
|
||||
|
||||
# Inject the 2 middlewares defined above into the router of the Hubsite service
|
||||
traefik.http.routers.{{ hubsite_identifier }}.middlewares={{ hubsite_identifier }}-oauth-errors,{{ hubsite_identifier }}-oauth-auth
|
||||
|
||||
########################################################################
|
||||
# #
|
||||
# /hubsite #
|
||||
# #
|
||||
########################################################################
|
||||
```
|
||||
|
||||
After adding this to your `vars.yml` file, [re-run the playbook](../installing.md): `just install-service hubsite`.
|
||||
|
||||
Some [services](../supported-services.md) already define their own `middlewares` in their Traefik `labels` file, so you may not be able to inject new ones the same way as done for Hubsite above.
|
||||
|
||||
Specific services (e.g. [Nextcloud](./nextcloud.md)) provide Ansible variables (`nextcloud_container_labels_traefik_http_middlewares_custom`) for injecting new middlewares at a specific position (priority) in the list. Others services (Ansible roles) do not support this yet, which would prevent you from using them this way. Consider submitting an issue or better yet opening a PR to improve these services.
|
||||
|
||||
|
||||
## Further reading
|
||||
|
||||
If you'd like to do something more advanced, the [`ansible-role-oauth2-proxy` Ansible role](https://github.com/mother-of-all-self-hosting/ansible-role-oauth2-proxy) is very configurable and should let you do what you need.
|
||||
|
||||
Take a look at [its `default/main.yml` file](https://github.com/mother-of-all-self-hosting/ansible-role-oauth2-proxy/blob/main/defaults/main.yml) for available Ansible variables you can use in your own `vars.yml` configuration file.
|
||||
|
||||
|
||||
## Related services
|
||||
|
||||
- [authentik](authentik.md) - An open-source Identity Provider focused on flexibility and versatility.
|
||||
- [Keycloak](keycloak.md) - An open source identity and access management solution
|
||||
- [Authelia](authelia.md) - An open-source authentication and authorization server that can work as a companion to [common reverse proxies](https://www.authelia.com/overview/prologue/supported-proxies/) (like [Traefik](traefik.md) frequently used by this playbook)
|
||||
|
|
@ -51,6 +51,7 @@
|
|||
| [NetBox](https://docs.netbox.dev/en/stable/) | Web application that provides [IP address management (IPAM)](https://en.wikipedia.org/wiki/IP_address_management) and [data center infrastructure management (DCIM)](https://en.wikipedia.org/wiki/Data_center_management#Data_center_infrastructure_management) functionality | [Link](services/netbox.md) |
|
||||
| [Nextcloud](https://nextcloud.com/) | The most popular self-hosted collaboration solution for tens of millions of users at thousands of organizations across the globe. | [Link](services/nextcloud.md) |
|
||||
| [Outline](https://www.getoutline.com/) | An open-source knowledge base for growing teams. | [Link](services/outline.md) |
|
||||
| [OAuth2-Proxy](https://oauth2-proxy.github.io/oauth2-proxy/) | A reverse proxy and static file server that provides authentication using OpenID Connect Providers (Google, GitHub, [Keycloak](services/keycloak.md), and others) to SSO-protect services which do not support SSO natively. | [Link](services/oauth2-proxy.md) |
|
||||
| [Owncast](https://owncast.online/) | Owncast is a free and open source live video and web chat server for use with existing popular broadcasting software. | [Link](services/owncast.md) |
|
||||
| [OxiTraffic](https://codeberg.org/mo8it/oxitraffic) | [OxiTraffic](https://codeberg.org/mo8it/oxitraffic) is a self-hosted, simple and privacy respecting website traffic tracker. | [Link](services/oxitraffic.md) |
|
||||
| [PeerTube](https://joinpeertube.org/) | A tool for sharing online videos | [Link](services/peertube.md) |
|
||||
|
|
|
|||
|
|
@ -443,6 +443,11 @@ mash_playbook_devture_systemd_service_manager_services_list_auto_itemized:
|
|||
{{ ({'name': (mariadb_identifier + '.service'), 'priority': 500, 'groups': ['mash', 'mariadb']} if mariadb_enabled else omit) }}
|
||||
# /role-specific:mariadb
|
||||
|
||||
# role-specific:oauth2_proxy
|
||||
- |-
|
||||
{{ ({'name': (oauth2_proxy_identifier + '.service'), 'priority': 1900, 'groups': ['mash', 'oauth2-proxy']} if oauth2_proxy_enabled else omit) }}
|
||||
# /role-specific:oauth2_proxy
|
||||
|
||||
# role-specific:outline
|
||||
- |-
|
||||
{{ ({'name': (outline_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'outline']} if outline_enabled else omit) }}
|
||||
|
|
@ -3836,6 +3841,38 @@ outline_database_sslmode: "{{ 'disable' if devture_postgres_enabled and outline_
|
|||
|
||||
|
||||
|
||||
# role-specific:oauth2_proxy
|
||||
########################################################################
|
||||
# #
|
||||
# oauth2_proxy #
|
||||
# #
|
||||
########################################################################
|
||||
|
||||
oauth2_proxy_enabled: false
|
||||
|
||||
oauth2_proxy_identifier: "{{ mash_playbook_service_identifier_prefix }}oauth2-proxy"
|
||||
|
||||
oauth2_proxy_uid: "{{ mash_playbook_uid }}"
|
||||
oauth2_proxy_gid: "{{ mash_playbook_gid }}"
|
||||
|
||||
oauth2_proxy_base_path: "{{ mash_playbook_base_path }}/{{ mash_playbook_service_base_directory_name_prefix }}oauth2-proxy"
|
||||
|
||||
oauth2_proxy_container_network: "{{ (mash_playbook_reverse_proxyable_services_additional_network if mash_playbook_traefik_labels_enabled else '') | default(oauth2_proxy_identifier) }}"
|
||||
|
||||
oauth2_proxy_container_labels_traefik_enabled: "{{ mash_playbook_traefik_labels_enabled }}"
|
||||
oauth2_proxy_container_labels_traefik_docker_network: "{{ mash_playbook_reverse_proxyable_services_additional_network }}"
|
||||
oauth2_proxy_container_labels_traefik_entrypoints: "{{ devture_traefik_entrypoint_primary }}"
|
||||
oauth2_proxy_container_labels_traefik_tls_certResolver: "{{ devture_traefik_certResolver_primary }}"
|
||||
|
||||
########################################################################
|
||||
# #
|
||||
# /oauth2_proxy #
|
||||
# #
|
||||
########################################################################
|
||||
# /role-specific:oauth2_proxy
|
||||
|
||||
|
||||
|
||||
# role-specific:owncast
|
||||
########################################################################
|
||||
# #
|
||||
|
|
|
|||
|
|
@ -212,6 +212,10 @@
|
|||
version: v28.0.2-1
|
||||
name: nextcloud
|
||||
activation_prefix: nextcloud_
|
||||
- src: git+https://github.com/mother-of-all-self-hosting/ansible-role-oauth2-proxy.git
|
||||
version: v7.6.0-1
|
||||
name: oauth2_proxy
|
||||
activation_prefix: oauth2_proxy_
|
||||
- src: git+https://github.com/mother-of-all-self-hosting/ansible-role-outline.git
|
||||
version: v0.74.0-0-0
|
||||
name: outline
|
||||
|
|
|
|||
|
|
@ -274,6 +274,10 @@
|
|||
- role: galaxy/nextcloud
|
||||
# /role-specific:nextcloud
|
||||
|
||||
# role-specific:oauth2_proxy
|
||||
- role: galaxy/oauth2_proxy
|
||||
# /role-specific:oauth2_proxy
|
||||
|
||||
# role-specific:owncast
|
||||
- role: galaxy/owncast
|
||||
# /role-specific:owncast
|
||||
|
|
|
|||
Loading…
Reference in a new issue