mirror of
https://github.com/openziti/zrok.git
synced 2025-08-16 10:57:55 +02:00
docs (#968)
This commit is contained in:
Michael Quigley
@ -4,157 +4,89 @@ sidebar_position: 10
|
||||
|
||||
# OAuth Public Frontend Configuration
|
||||
|
||||
As of `v0.4.7`, `zrok` includes OAuth integration for both Google and GitHub for `zrok access public` public frontends.
|
||||
|
||||
This integration allows you to create public shares and request that the public frontend authenticate your users against either the Google or GitHub OAuth endpoints (using the user's Google or GitHub accounts). Additionally, you can restrict the email address domain associated with the count to a list of domains that you provide when you create the share.
|
||||
|
||||
This is a first step towards a more comprehensive portfolio of user authentication strategies in future `zrok` releases.
|
||||
`zrok` includes OAuth integration for public frontends, allowing you to authenticate users through various OAuth providers before they can access your shared resources. You can configure multiple OAuth providers and restrict access based on email address patterns.
|
||||
|
||||
## Planning for the OAuth Frontend
|
||||
|
||||
The current implementation of the OAuth public frontend uses a HTTP listener to handle redirects from OAuth providers. You'll need to configure a DNS name and a port for this listener that is accessible by your end users. We'll refer to this listener as the "OAuth frontend" in this guide.
|
||||
The OAuth public frontend uses an HTTP listener with a stable name to handle redirects from OAuth providers. You'll need to configure a DNS name and port for this listener that is accessible by your end users.
|
||||
|
||||
We'll use the public DNS address of the OAuth frontend when creating the Google and GitHub OAuth clients below. This address is typically configured into these clients as the "redirect URL" where these clients will send the authenticated users after authentication.
|
||||
|
||||
The `zrok` OAuth frontend will capture the successful authentication and forward the user back to their original destination.
|
||||
|
||||
## Configuring a Google OAuth Client ID
|
||||
|
||||
### OAuth Content Screen
|
||||
|
||||
Before you can configure an OAuth Client ID in Google Cloud, you have to configure the "OAuth content screen".
|
||||
|
||||
In the Google Cloud console, navigate to: `APIs & Services > Credentials > OAuth content screen`
|
||||
|
||||
|
||||
|
||||
Here you can give your `zrok` public frontend an identity and branding to match your deployment.
|
||||
|
||||
|
||||
|
||||
Describe what domains are authorized to access your public frontend and establish contact information.
|
||||
|
||||
|
||||
|
||||
Add a non-sensitive scope for `../auth/userinfo.email`. This is important as it allows the `zrok` OAuth frontend to receive the email address of the authenticated user.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Now your OAuth content screen is configured.
|
||||
|
||||
### Create the OAuth 2.0 Client ID
|
||||
|
||||
Next we create the OAuth Client ID for your public frontend.
|
||||
|
||||
In the Google Cloud Console, navigate to: `APIs & Services > Credentials > + Create Credentials`
|
||||
|
||||
|
||||
|
||||
Select `OAuth client ID` from the `+ Create Credentials` dropdown.
|
||||
|
||||
|
||||
|
||||
Application type is `Web Application`.
|
||||
|
||||
|
||||
|
||||
The most important bit here is the "Authorized redirect URIs". You're going to want to put a URL here that matches the `zrok` OAuth frontend address that you configured at the start of this guide, but at the end of the URL you're going to append `/google/oauth` to the URL.
|
||||
|
||||
|
||||
|
||||
Save the client ID and the client secret. You'll configure these into your `frontend.yml`.
|
||||
|
||||
With this your Google OAuth client should be configured and ready.
|
||||
|
||||
## Configuring a GitHub Client ID
|
||||
|
||||
Register a new OAuth application through the GitHub settings for the account that owns the application.
|
||||
|
||||
Navigate to:`Settings > Developer Settings > OAuth Apps > Register a new application`
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
The "Authorized callback URL" should be configured to match the OAuth frontend address you configured at the start of this guide, with `/github/oauth` appended to the end.
|
||||
|
||||
|
||||
|
||||
Create a new client secret.
|
||||
|
||||
|
||||
|
||||
Save the client ID and the client secret. You'll configure these into your `frontend.yml`.
|
||||
The OAuth frontend address will be used as the "redirect URL" when configuring OAuth clients with your providers. Each provider will redirect authenticated users back to this address, which then forwards them to their original destination.
|
||||
|
||||
## Configuring your Public Frontend
|
||||
|
||||
The public frontend configuration includes a new `oauth` section:
|
||||
Add an `oauth` section to your frontend configuration:
|
||||
|
||||
```yaml
|
||||
oauth:
|
||||
bind_address: 0.0.0.0:8181
|
||||
redirect_url: https://oauth.zrok.io
|
||||
cookie_domain: zrok.io
|
||||
hash_key: "the quick brown fox jumped over the lazy dog"
|
||||
bind_address: "127.0.0.1:8181"
|
||||
endpoint_url: "https://oauth.your-domain.com:8181"
|
||||
cookie_name: "zrok-auth-session"
|
||||
cookie_domain: "your-domain.com"
|
||||
session_lifetime: "6h"
|
||||
intermediate_lifetime: "5m"
|
||||
signing_key: "your-unique-signing-key-32-chars"
|
||||
encryption_key: "your-unique-encryption-key-24-chars"
|
||||
|
||||
providers:
|
||||
- name: google
|
||||
client_id: "<client id from google>"
|
||||
client_secret: "<client secret from google>"
|
||||
- name: github
|
||||
client_id: "<client id from github>"
|
||||
client_secret: "<client secret from github>"
|
||||
- name: "google"
|
||||
type: "google"
|
||||
client_id: "<google-client-id>"
|
||||
client_secret: "<google-client-secret>"
|
||||
|
||||
- name: "github"
|
||||
type: "github"
|
||||
client_id: "<github-client-id>"
|
||||
client_secret: "<github-client-secret>"
|
||||
|
||||
- name: "custom-oidc"
|
||||
type: "oidc"
|
||||
client_id: "<oidc-client-id>"
|
||||
client_secret: "<oidc-client-secret>"
|
||||
scopes: ["openid", "email", "profile"]
|
||||
issuer: "https://your-oidc-provider.com"
|
||||
supports_pkce: true
|
||||
```
|
||||
|
||||
The `bind_address` parameter determines where the OAuth frontend will bind. Should be in `ip:port` format.
|
||||
### Configuration Parameters
|
||||
|
||||
The `redirect_url` parameter determines the base URL where OAuth frontend requests will be redirected.
|
||||
- **`bind_address`**: IP and port where the OAuth frontend will listen (format: `ip:port`)
|
||||
- **`endpoint_url`**: Public base URL where OAuth redirects will be handled
|
||||
- **`cookie_name`**: Name for authentication cookies (optional, defaults to `zrok-auth-session`)
|
||||
- **`cookie_domain`**: Domain where authentication cookies should be stored
|
||||
- **`session_lifetime`**: How long authentication sessions remain valid (e.g., `6h`, `24h`)
|
||||
- **`intermediate_lifetime`**: Lifetime for intermediate OAuth tokens (e.g., `5m`)
|
||||
- **`signing_key`**: Unique 32+ character string for securing authentication payloads
|
||||
- **`encryption_key`**: Unique 24+ character string for encrypting session data
|
||||
|
||||
`cookie_domain` is the domain where authentication cookies should be stored.
|
||||
### OAuth Providers
|
||||
|
||||
`hash_key` is a unique string for your installation that is used to secure the authentication payloads for your public frontend.
|
||||
The `providers` array supports multiple OAuth configurations. Each provider requires:
|
||||
|
||||
`providers` is a list of configured providers for this public frontend. The current implementation supports `google` and `github` as options.
|
||||
- **`name`**: Unique identifier for this provider configuration; the `name` becomes part of the OAuth URLs for this provider, for example the callback URL becomes `/<name>/auth/callback`
|
||||
- **`type`**: Provider type (`google`, `github`, or `oidc`)
|
||||
- **`client_id`** and **`client_secret`**: OAuth client credentials
|
||||
|
||||
Both the `google` and `github` providers accept a `client_id` and `client_secret` parameter. These values are provided when you configure the OAuth clients at Google or GitHub.
|
||||
For detailed setup instructions for each provider type, see:
|
||||
- [Google OAuth Setup](integrations/google.md)
|
||||
- [GitHub OAuth Setup](integrations/github.md)
|
||||
- [Generic OIDC Setup](integrations/oidc.md)
|
||||
|
||||
## Enabling OAuth on a Public Share
|
||||
## Using OAuth with Public Shares
|
||||
|
||||
With your public frontend configured to support OAuth, you can test this by creating a public share. There are new command line options to support this:
|
||||
Once your public frontend is configured with OAuth providers, you can enable authentication on public shares using these command line options:
|
||||
|
||||
```text
|
||||
$ zrok share public --help
|
||||
Share a target resource publicly
|
||||
- **`--oauth-provider <name>`**: Enable OAuth using the specified provider name from your configuration
|
||||
- **`--oauth-email-address-patterns <pattern>`**: Restrict access to email addresses matching the glob pattern (use multiple times for multiple patterns)
|
||||
- **`--oauth-check-interval <duration>`**: How often to re-verify authentication (default: 3h)
|
||||
|
||||
Usage:
|
||||
zrok share public <target> [flags]
|
||||
### Example
|
||||
|
||||
Flags:
|
||||
-b, --backend-mode string The backend mode {proxy, web, caddy, drive} (default "proxy")
|
||||
--basic-auth stringArray Basic authentication users (<username:password>,...)
|
||||
--frontends stringArray Selected frontends to use for the share (default [public])
|
||||
--headless Disable TUI and run headless
|
||||
-h, --help help for public
|
||||
--insecure Enable insecure TLS certificate validation for <target>
|
||||
--oauth-check-interval duration Maximum lifetime for OAuth authentication; reauthenticate after expiry (default 3h0m0s)
|
||||
--oauth-email-address-patterns stringArray Allow only these email domain globs to authenticate via OAuth
|
||||
--oauth-provider string Enable OAuth provider [google, github]
|
||||
|
||||
Global Flags:
|
||||
-p, --panic Panic instead of showing pretty errors
|
||||
-v, --verbose Enable verbose logging
|
||||
```bash
|
||||
zrok share public --backend-mode web \
|
||||
--oauth-provider google \
|
||||
--oauth-email-address-patterns '*@example.com' \
|
||||
--oauth-email-address-patterns 'admin@*' \
|
||||
~/public
|
||||
```
|
||||
|
||||
The `--oauth-provider` flag enables OAuth for the share using the specified provider.
|
||||
|
||||
The `--oauth-email-address-patterns` flag accepts a single glob pattern that matches an authenticated email address that is allowed to access the share. Use this flag multiple times to allow different patterns.
|
||||
|
||||
The `--oauth-check-interval` flag specifies how frequently the authentication must be checked.
|
||||
|
||||
An example public share:
|
||||
|
||||
```text
|
||||
zrok share public --backend-mode web --oauth-provider github --oauth-email-address-patterns '*@zrok.io' ~/public
|
||||
```
|
||||
This creates a public share that requires Google OAuth authentication and only allows users with `@example.com` email addresses or any `admin@*` email address.
|
||||
|
||||
@ -1 +1,45 @@
|
||||
# Github
|
||||
---
|
||||
sidebar_position: 20
|
||||
---
|
||||
|
||||
# GitHub OAuth Setup
|
||||
|
||||
This guide covers setting up GitHub OAuth for your zrok public frontend.
|
||||
|
||||
## Register OAuth Application
|
||||
|
||||
Navigate to your GitHub account settings: **Settings > Developer Settings > OAuth Apps > Register a new application**
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Configure the **Authorization callback URL** to match your OAuth frontend address with `/github/oauth` appended:
|
||||
|
||||
|
||||
|
||||
Create a new client secret:
|
||||
|
||||
|
||||
|
||||
Save the client ID and client secret for your frontend configuration.
|
||||
|
||||
## Frontend Configuration
|
||||
|
||||
Add the GitHub provider to your `frontend.yml`:
|
||||
|
||||
```yaml
|
||||
oauth:
|
||||
providers:
|
||||
- name: "github"
|
||||
type: "github"
|
||||
client_id: "<your-github-client-id>"
|
||||
client_secret: "<your-github-client-secret>"
|
||||
```
|
||||
|
||||
## Redirect URL Format
|
||||
|
||||
For GitHub OAuth, the redirect URL should be:
|
||||
```
|
||||
https://your-oauth-frontend-domain:port/github/oauth
|
||||
```
|
||||
|
||||
@ -1 +1,69 @@
|
||||
# Google
|
||||
---
|
||||
sidebar_position: 10
|
||||
---
|
||||
|
||||
# Google OAuth Setup
|
||||
|
||||
This guide covers setting up Google OAuth for your zrok public frontend.
|
||||
|
||||
## OAuth Consent Screen
|
||||
|
||||
Before configuring an OAuth Client ID, you must configure the "OAuth consent screen" in the Google Cloud Console.
|
||||
|
||||
Navigate to: **APIs & Services > Credentials > OAuth consent screen**
|
||||
|
||||
|
||||
|
||||
Configure your zrok public frontend's identity and branding:
|
||||
|
||||
|
||||
|
||||
Add authorized domains and contact information:
|
||||
|
||||
|
||||
|
||||
Add the `../auth/userinfo.email` scope (required for zrok to receive user email addresses):
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Create OAuth 2.0 Client ID
|
||||
|
||||
Navigate to: **APIs & Services > Credentials > + Create Credentials**
|
||||
|
||||
|
||||
|
||||
Select **OAuth client ID**:
|
||||
|
||||
|
||||
|
||||
Choose **Web Application**:
|
||||
|
||||
|
||||
|
||||
Configure the **Authorized redirect URIs** to match your OAuth frontend address with `/google/oauth` appended:
|
||||
|
||||
|
||||
|
||||
Save the client ID and client secret for your frontend configuration.
|
||||
|
||||
## Frontend Configuration
|
||||
|
||||
Add the Google provider to your `frontend.yml`:
|
||||
|
||||
```yaml
|
||||
oauth:
|
||||
providers:
|
||||
- name: "google"
|
||||
type: "google"
|
||||
client_id: "<your-google-client-id>"
|
||||
client_secret: "<your-google-client-secret>"
|
||||
```
|
||||
|
||||
## Redirect URL Format
|
||||
|
||||
For Google OAuth, the redirect URL should be:
|
||||
```
|
||||
https://your-oauth-frontend-domain:port/google/oauth
|
||||
```
|
||||
|
||||
@ -1 +1,76 @@
|
||||
# Generic OIDC
|
||||
---
|
||||
sidebar_position: 30
|
||||
---
|
||||
|
||||
# Generic OIDC Setup
|
||||
|
||||
This guide covers setting up OpenID Connect (OIDC) providers for your zrok public frontend. OIDC is supported by many identity providers including Keycloak, Auth0, Okta, Azure AD, and others.
|
||||
|
||||
## Provider Requirements
|
||||
|
||||
Your OIDC provider must support:
|
||||
- Authorization Code flow
|
||||
- Discovery endpoint (optional but recommended)
|
||||
- PKCE (Proof Key for Code Exchange) - optional but recommended for security
|
||||
|
||||
## Configure OIDC Provider
|
||||
|
||||
1. Create a new OAuth/OIDC client in your provider's admin interface
|
||||
2. Set the **redirect URI** to: `https://your-oauth-frontend-domain:port/oidc/oauth`
|
||||
3. Configure required scopes: `openid`, `email`, `profile`
|
||||
4. Note the **client ID**, **client secret**, and **issuer URL**
|
||||
|
||||
## Frontend Configuration
|
||||
|
||||
Add the OIDC provider to your `frontend.yml`:
|
||||
|
||||
```yaml
|
||||
oauth:
|
||||
providers:
|
||||
- name: "my-oidc-provider"
|
||||
type: "oidc"
|
||||
client_id: "<your-oidc-client-id>"
|
||||
client_secret: "<your-oidc-client-secret>"
|
||||
scopes: ["openid", "email", "profile"]
|
||||
issuer: "https://your-oidc-provider.com"
|
||||
supports_pkce: true # recommended for security
|
||||
```
|
||||
|
||||
### Configuration Options
|
||||
|
||||
- **`name`**: Unique identifier for this provider (used in share commands)
|
||||
- **`type`**: Must be `"oidc"` for OpenID Connect providers
|
||||
- **`client_id`** and **`client_secret`**: OAuth client credentials from your provider
|
||||
- **`scopes`**: OAuth scopes to request (typically `["openid", "email", "profile"]`)
|
||||
- **`issuer`**: The OIDC issuer URL (used for auto-discovery)
|
||||
- **`discovery_url`**: Optional explicit discovery endpoint URL (if not using issuer auto-discovery)
|
||||
- **`supports_pkce`**: Whether the provider supports PKCE (recommended: `true`)
|
||||
|
||||
## Common OIDC Providers
|
||||
|
||||
### Keycloak
|
||||
```yaml
|
||||
issuer: "https://your-keycloak.com/realms/your-realm"
|
||||
```
|
||||
|
||||
### Auth0
|
||||
```yaml
|
||||
issuer: "https://your-domain.auth0.com/"
|
||||
```
|
||||
|
||||
### Azure AD
|
||||
```yaml
|
||||
issuer: "https://login.microsoftonline.com/<tenant-id>/v2.0"
|
||||
```
|
||||
|
||||
### Okta
|
||||
```yaml
|
||||
issuer: "https://your-domain.okta.com/oauth2/default"
|
||||
```
|
||||
|
||||
## Redirect URL Format
|
||||
|
||||
For OIDC providers, the redirect URL should be:
|
||||
```
|
||||
https://your-oauth-frontend-domain:port/oidc/oauth
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user