public_git
/
oauth2-proxy
mirror of https://github.com/oauth2-proxy/oauth2-proxy.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

doc: improved clarity and correctness of proxy behaviour (#3305) 

* doc: adjust regarding description of behaviour

Signed-off-by: NirronCD <nirron@rietto.com>

* doc:changed style, added suggested

Signed-off-by: NirronCD <nirron@rietto.com>

* doc: minor fix to docusaurus metadata syntax

Signed-off-by: NirronCD <nirron@rietto.com>

* docs: improved clarity for how the proxy behaves in different scenarios

Signed-off-by: Jan Larwig <jan@larwig.com>

---------

Signed-off-by: NirronCD <nirron@rietto.com>
Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: Jan Larwig <jan@larwig.com>
This commit is contained in:
NirronCD 2026-01-14 17:26:50 -03:00 committed by GitHub
parent 0100ca9403
commit a2f2223d2b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
15 changed files with 262 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
docs/docs/behaviour.md
View File

@ -3,9 +3,24 @@ 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)
1. Authentication Requirement: All requests passing through the proxy to upstream applications require authentication, excluding default proxy endpoints.
- Exception: If the request matches a skipped route (configured via `--skip-auth-route`):
- Authentication is not enforced, but the proxy will opportunistically attempt to validate a session cookie (`--cookie-name`) or JWT (`--skip-jwt-bearer-tokens`) if present in the request.
- Configured user info and authentication headers (e.g., `--pass-access-token`) are injected to upstream routes when validation succeeds.
Notice that the proxy also provides a number of useful [endpoints](features/endpoints.md).
2. Unauthenticated Requests: When authentication is missing but required, the user is redirected to the configured Identity Provider (IdP) login page by default.
- Ajax Requests: If the request has `Accept: application/json` header:
- Returns `401 Unauthorized`.
- Invalid JWT Tokens: If `--skip-jwt-bearer-tokens` is set and the request includes an invalid JWT:
- Redirects to the login page by default.
- Returns `403 Forbidden` if `--bearer-token-login-fallback` is set to `false`.
3. Post-Authentication: After successful authentication with the IdP, OAuth tokens are stored in the configured session store (cookie or Redis), and a cookie is set.
4. Request Forwarding: The authenticated request is processed based on configuration:
- Forwarded to the configured upstream application with added user info and authentication headers, or
- Returns a valid status code for downstream processing by another proxy or load balancer (e.g., Nginx or Traefik).
---
Note: The proxy also provides a number of useful [endpoints](features/endpoints.md) for monitoring and management.

2
docs/versioned_docs/version-7.0.x/behaviour.md
View File

@ -3,7 +3,7 @@ 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`).
1. Any request passing through the proxy (and not matched by `--skip-auth-route`) 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)

2
docs/versioned_docs/version-7.1.x/behaviour.md
View File

@ -3,7 +3,7 @@ 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`).
1. Any request passing through the proxy (and not matched by `--skip-auth-route`) 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)

25
docs/versioned_docs/version-7.10.x/behaviour.md
View File

@ -3,9 +3,24 @@ 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)
1. Authentication Requirement: All requests passing through the proxy to upstream applications require authentication, excluding default proxy endpoints.
- Exception: If the request matches a skipped route (configured via `--skip-auth-route`):
- Authentication is not enforced, but the proxy will opportunistically attempt to validate a session cookie (`--cookie-name`) or JWT (`--skip-jwt-bearer-tokens`) if present in the request.
- Configured user info and authentication headers (e.g., `--pass-access-token`) are injected to upstream routes when validation succeeds.
Notice that the proxy also provides a number of useful [endpoints](features/endpoints.md).
2. Unauthenticated Requests: When authentication is missing but required, the user is redirected to the configured Identity Provider (IdP) login page by default.
- Ajax Requests: If the request has `Accept: application/json` header:
- Returns `401 Unauthorized`.
- Invalid JWT Tokens: If `--skip-jwt-bearer-tokens` is set and the request includes an invalid JWT:
- Redirects to the login page by default.
- Returns `403 Forbidden` if `--bearer-token-login-fallback` is set to `false`.
3. Post-Authentication: After successful authentication with the IdP, OAuth tokens are stored in the configured session store (cookie or Redis), and a cookie is set.
4. Request Forwarding: The authenticated request is processed based on configuration:
- Forwarded to the configured upstream application with added user info and authentication headers, or
- Returns a valid status code for downstream processing by another proxy or load balancer (e.g., Nginx or Traefik).
---
Note: The proxy also provides a number of useful [endpoints](features/endpoints.md) for monitoring and management.

25
docs/versioned_docs/version-7.11.x/behaviour.md
View File

@ -3,9 +3,24 @@ 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)
1. Authentication Requirement: All requests passing through the proxy to upstream applications require authentication, excluding default proxy endpoints.
- Exception: If the request matches a skipped route (configured via `--skip-auth-route`):
- Authentication is not enforced, but the proxy will opportunistically attempt to validate a session cookie (`--cookie-name`) or JWT (`--skip-jwt-bearer-tokens`) if present in the request.
- Configured user info and authentication headers (e.g., `--pass-access-token`) are injected to upstream routes when validation succeeds.
Notice that the proxy also provides a number of useful [endpoints](features/endpoints.md).
2. Unauthenticated Requests: When authentication is missing but required, the user is redirected to the configured Identity Provider (IdP) login page by default.
- Ajax Requests: If the request has `Accept: application/json` header:
- Returns `401 Unauthorized`.
- Invalid JWT Tokens: If `--skip-jwt-bearer-tokens` is set and the request includes an invalid JWT:
- Redirects to the login page by default.
- Returns `403 Forbidden` if `--bearer-token-login-fallback` is set to `false`.
3. Post-Authentication: After successful authentication with the IdP, OAuth tokens are stored in the configured session store (cookie or Redis), and a cookie is set.
4. Request Forwarding: The authenticated request is processed based on configuration:
- Forwarded to the configured upstream application with added user info and authentication headers, or
- Returns a valid status code for downstream processing by another proxy or load balancer (e.g., Nginx or Traefik).
---
Note: The proxy also provides a number of useful [endpoints](features/endpoints.md) for monitoring and management.

25
docs/versioned_docs/version-7.12.x/behaviour.md
View File

@ -3,9 +3,24 @@ 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)
1. Authentication Requirement: All requests passing through the proxy to upstream applications require authentication, excluding default proxy endpoints.
- Exception: If the request matches a skipped route (configured via `--skip-auth-route`):
- Authentication is not enforced, but the proxy will opportunistically attempt to validate a session cookie (`--cookie-name`) or JWT (`--skip-jwt-bearer-tokens`) if present in the request.
- Configured user info and authentication headers (e.g., `--pass-access-token`) are injected to upstream routes when validation succeeds.
Notice that the proxy also provides a number of useful [endpoints](features/endpoints.md).
2. Unauthenticated Requests: When authentication is missing but required, the user is redirected to the configured Identity Provider (IdP) login page by default.
- Ajax Requests: If the request has `Accept: application/json` header:
- Returns `401 Unauthorized`.
- Invalid JWT Tokens: If `--skip-jwt-bearer-tokens` is set and the request includes an invalid JWT:
- Redirects to the login page by default.
- Returns `403 Forbidden` if `--bearer-token-login-fallback` is set to `false`.
3. Post-Authentication: After successful authentication with the IdP, OAuth tokens are stored in the configured session store (cookie or Redis), and a cookie is set.
4. Request Forwarding: The authenticated request is processed based on configuration:
- Forwarded to the configured upstream application with added user info and authentication headers, or
- Returns a valid status code for downstream processing by another proxy or load balancer (e.g., Nginx or Traefik).
---
Note: The proxy also provides a number of useful [endpoints](features/endpoints.md) for monitoring and management.

25
docs/versioned_docs/version-7.13.x/behaviour.md
View File

@ -3,9 +3,24 @@ 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)
1. Authentication Requirement: All requests passing through the proxy to upstream applications require authentication, excluding default proxy endpoints.
- Exception: If the request matches a skipped route (configured via `--skip-auth-route`):
- Authentication is not enforced, but the proxy will opportunistically attempt to validate a session cookie (`--cookie-name`) or JWT (`--skip-jwt-bearer-tokens`) if present in the request.
- Configured user info and authentication headers (e.g., `--pass-access-token`) are injected to upstream routes when validation succeeds.
Notice that the proxy also provides a number of useful [endpoints](features/endpoints.md).
2. Unauthenticated Requests: When authentication is missing but required, the user is redirected to the configured Identity Provider (IdP) login page by default.
- Ajax Requests: If the request has `Accept: application/json` header:
- Returns `401 Unauthorized`.
- Invalid JWT Tokens: If `--skip-jwt-bearer-tokens` is set and the request includes an invalid JWT:
- Redirects to the login page by default.
- Returns `403 Forbidden` if `--bearer-token-login-fallback` is set to `false`.
3. Post-Authentication: After successful authentication with the IdP, OAuth tokens are stored in the configured session store (cookie or Redis), and a cookie is set.
4. Request Forwarding: The authenticated request is processed based on configuration:
- Forwarded to the configured upstream application with added user info and authentication headers, or
- Returns a valid status code for downstream processing by another proxy or load balancer (e.g., Nginx or Traefik).
---
Note: The proxy also provides a number of useful [endpoints](features/endpoints.md) for monitoring and management.

25
docs/versioned_docs/version-7.2.x/behaviour.md
View File

@ -3,9 +3,24 @@ 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)
1. Authentication Requirement: All requests passing through the proxy to upstream applications require authentication, excluding default proxy endpoints.
- Exception: If the request matches a skipped route (configured via `--skip-auth-route`):
- Authentication is not enforced, but the proxy will opportunistically attempt to validate a session cookie (`--cookie-name`) or JWT (`--skip-jwt-bearer-tokens`) if present in the request.
- Configured user info and authentication headers (e.g., `--pass-access-token`) are injected to upstream routes when validation succeeds.
Notice that the proxy also provides a number of useful [endpoints](features/endpoints.md).
2. Unauthenticated Requests: When authentication is missing but required, the user is redirected to the configured Identity Provider (IdP) login page by default.
- Ajax Requests: If the request has `Accept: application/json` header:
- Returns `401 Unauthorized`.
- Invalid JWT Tokens: If `--skip-jwt-bearer-tokens` is set and the request includes an invalid JWT:
- Redirects to the login page by default.
- Returns `403 Forbidden` if `--bearer-token-login-fallback` is set to `false`.
3. Post-Authentication: After successful authentication with the IdP, OAuth tokens are stored in the configured session store (cookie or Redis), and a cookie is set.
4. Request Forwarding: The authenticated request is processed based on configuration:
- Forwarded to the configured upstream application with added user info and authentication headers, or
- Returns a valid status code for downstream processing by another proxy or load balancer (e.g., Nginx or Traefik).
---
Note: The proxy also provides a number of useful [endpoints](features/endpoints.md) for monitoring and management.

25
docs/versioned_docs/version-7.3.x/behaviour.md
View File

@ -3,9 +3,24 @@ 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)
1. Authentication Requirement: All requests passing through the proxy to upstream applications require authentication, excluding default proxy endpoints.
- Exception: If the request matches a skipped route (configured via `--skip-auth-route`):
- Authentication is not enforced, but the proxy will opportunistically attempt to validate a session cookie (`--cookie-name`) or JWT (`--skip-jwt-bearer-tokens`) if present in the request.
- Configured user info and authentication headers (e.g., `--pass-access-token`) are injected to upstream routes when validation succeeds.
Notice that the proxy also provides a number of useful [endpoints](features/endpoints.md).
2. Unauthenticated Requests: When authentication is missing but required, the user is redirected to the configured Identity Provider (IdP) login page by default.
- Ajax Requests: If the request has `Accept: application/json` header:
- Returns `401 Unauthorized`.
- Invalid JWT Tokens: If `--skip-jwt-bearer-tokens` is set and the request includes an invalid JWT:
- Redirects to the login page by default.
- Returns `403 Forbidden` if `--bearer-token-login-fallback` is set to `false`.
3. Post-Authentication: After successful authentication with the IdP, OAuth tokens are stored in the configured session store (cookie or Redis), and a cookie is set.
4. Request Forwarding: The authenticated request is processed based on configuration:
- Forwarded to the configured upstream application with added user info and authentication headers, or
- Returns a valid status code for downstream processing by another proxy or load balancer (e.g., Nginx or Traefik).
---
Note: The proxy also provides a number of useful [endpoints](features/endpoints.md) for monitoring and management.

25
docs/versioned_docs/version-7.4.x/behaviour.md
View File

@ -3,9 +3,24 @@ 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)
1. Authentication Requirement: All requests passing through the proxy to upstream applications require authentication, excluding default proxy endpoints.
- Exception: If the request matches a skipped route (configured via `--skip-auth-route`):
- Authentication is not enforced, but the proxy will opportunistically attempt to validate a session cookie (`--cookie-name`) or JWT (`--skip-jwt-bearer-tokens`) if present in the request.
- Configured user info and authentication headers (e.g., `--pass-access-token`) are injected to upstream routes when validation succeeds.
Notice that the proxy also provides a number of useful [endpoints](features/endpoints.md).
2. Unauthenticated Requests: When authentication is missing but required, the user is redirected to the configured Identity Provider (IdP) login page by default.
- Ajax Requests: If the request has `Accept: application/json` header:
- Returns `401 Unauthorized`.
- Invalid JWT Tokens: If `--skip-jwt-bearer-tokens` is set and the request includes an invalid JWT:
- Redirects to the login page by default.
- Returns `403 Forbidden` if `--bearer-token-login-fallback` is set to `false`.
3. Post-Authentication: After successful authentication with the IdP, OAuth tokens are stored in the configured session store (cookie or Redis), and a cookie is set.
4. Request Forwarding: The authenticated request is processed based on configuration:
- Forwarded to the configured upstream application with added user info and authentication headers, or
- Returns a valid status code for downstream processing by another proxy or load balancer (e.g., Nginx or Traefik).
---
Note: The proxy also provides a number of useful [endpoints](features/endpoints.md) for monitoring and management.

25
docs/versioned_docs/version-7.5.x/behaviour.md
View File

@ -3,9 +3,24 @@ 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)
1. Authentication Requirement: All requests passing through the proxy to upstream applications require authentication, excluding default proxy endpoints.
- Exception: If the request matches a skipped route (configured via `--skip-auth-route`):
- Authentication is not enforced, but the proxy will opportunistically attempt to validate a session cookie (`--cookie-name`) or JWT (`--skip-jwt-bearer-tokens`) if present in the request.
- Configured user info and authentication headers (e.g., `--pass-access-token`) are injected to upstream routes when validation succeeds.
Notice that the proxy also provides a number of useful [endpoints](features/endpoints.md).
2. Unauthenticated Requests: When authentication is missing but required, the user is redirected to the configured Identity Provider (IdP) login page by default.
- Ajax Requests: If the request has `Accept: application/json` header:
- Returns `401 Unauthorized`.
- Invalid JWT Tokens: If `--skip-jwt-bearer-tokens` is set and the request includes an invalid JWT:
- Redirects to the login page by default.
- Returns `403 Forbidden` if `--bearer-token-login-fallback` is set to `false`.
3. Post-Authentication: After successful authentication with the IdP, OAuth tokens are stored in the configured session store (cookie or Redis), and a cookie is set.
4. Request Forwarding: The authenticated request is processed based on configuration:
- Forwarded to the configured upstream application with added user info and authentication headers, or
- Returns a valid status code for downstream processing by another proxy or load balancer (e.g., Nginx or Traefik).
---
Note: The proxy also provides a number of useful [endpoints](features/endpoints.md) for monitoring and management.

25
docs/versioned_docs/version-7.6.x/behaviour.md
View File

@ -3,9 +3,24 @@ 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)
1. Authentication Requirement: All requests passing through the proxy to upstream applications require authentication, excluding default proxy endpoints.
- Exception: If the request matches a skipped route (configured via `--skip-auth-route`):
- Authentication is not enforced, but the proxy will opportunistically attempt to validate a session cookie (`--cookie-name`) or JWT (`--skip-jwt-bearer-tokens`) if present in the request.
- Configured user info and authentication headers (e.g., `--pass-access-token`) are injected to upstream routes when validation succeeds.
Notice that the proxy also provides a number of useful [endpoints](features/endpoints.md).
2. Unauthenticated Requests: When authentication is missing but required, the user is redirected to the configured Identity Provider (IdP) login page by default.
- Ajax Requests: If the request has `Accept: application/json` header:
- Returns `401 Unauthorized`.
- Invalid JWT Tokens: If `--skip-jwt-bearer-tokens` is set and the request includes an invalid JWT:
- Redirects to the login page by default.
- Returns `403 Forbidden` if `--bearer-token-login-fallback` is set to `false`.
3. Post-Authentication: After successful authentication with the IdP, OAuth tokens are stored in the configured session store (cookie or Redis), and a cookie is set.
4. Request Forwarding: The authenticated request is processed based on configuration:
- Forwarded to the configured upstream application with added user info and authentication headers, or
- Returns a valid status code for downstream processing by another proxy or load balancer (e.g., Nginx or Traefik).
---
Note: The proxy also provides a number of useful [endpoints](features/endpoints.md) for monitoring and management.

25
docs/versioned_docs/version-7.7.x/behaviour.md
View File

@ -3,9 +3,24 @@ 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)
1. Authentication Requirement: All requests passing through the proxy to upstream applications require authentication, excluding default proxy endpoints.
- Exception: If the request matches a skipped route (configured via `--skip-auth-route`):
- Authentication is not enforced, but the proxy will opportunistically attempt to validate a session cookie (`--cookie-name`) or JWT (`--skip-jwt-bearer-tokens`) if present in the request.
- Configured user info and authentication headers (e.g., `--pass-access-token`) are injected to upstream routes when validation succeeds.
Notice that the proxy also provides a number of useful [endpoints](features/endpoints.md).
2. Unauthenticated Requests: When authentication is missing but required, the user is redirected to the configured Identity Provider (IdP) login page by default.
- Ajax Requests: If the request has `Accept: application/json` header:
- Returns `401 Unauthorized`.
- Invalid JWT Tokens: If `--skip-jwt-bearer-tokens` is set and the request includes an invalid JWT:
- Redirects to the login page by default.
- Returns `403 Forbidden` if `--bearer-token-login-fallback` is set to `false`.
3. Post-Authentication: After successful authentication with the IdP, OAuth tokens are stored in the configured session store (cookie or Redis), and a cookie is set.
4. Request Forwarding: The authenticated request is processed based on configuration:
- Forwarded to the configured upstream application with added user info and authentication headers, or
- Returns a valid status code for downstream processing by another proxy or load balancer (e.g., Nginx or Traefik).
---
Note: The proxy also provides a number of useful [endpoints](features/endpoints.md) for monitoring and management.

25
docs/versioned_docs/version-7.8.x/behaviour.md
View File

@ -3,9 +3,24 @@ 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)
1. Authentication Requirement: All requests passing through the proxy to upstream applications require authentication, excluding default proxy endpoints.
- Exception: If the request matches a skipped route (configured via `--skip-auth-route`):
- Authentication is not enforced, but the proxy will opportunistically attempt to validate a session cookie (`--cookie-name`) or JWT (`--skip-jwt-bearer-tokens`) if present in the request.
- Configured user info and authentication headers (e.g., `--pass-access-token`) are injected to upstream routes when validation succeeds.
Notice that the proxy also provides a number of useful [endpoints](features/endpoints.md).
2. Unauthenticated Requests: When authentication is missing but required, the user is redirected to the configured Identity Provider (IdP) login page by default.
- Ajax Requests: If the request has `Accept: application/json` header:
- Returns `401 Unauthorized`.
- Invalid JWT Tokens: If `--skip-jwt-bearer-tokens` is set and the request includes an invalid JWT:
- Redirects to the login page by default.
- Returns `403 Forbidden` if `--bearer-token-login-fallback` is set to `false`.
3. Post-Authentication: After successful authentication with the IdP, OAuth tokens are stored in the configured session store (cookie or Redis), and a cookie is set.
4. Request Forwarding: The authenticated request is processed based on configuration:
- Forwarded to the configured upstream application with added user info and authentication headers, or
- Returns a valid status code for downstream processing by another proxy or load balancer (e.g., Nginx or Traefik).
---
Note: The proxy also provides a number of useful [endpoints](features/endpoints.md) for monitoring and management.

25
docs/versioned_docs/version-7.9.x/behaviour.md
View File

@ -3,9 +3,24 @@ 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)
1. Authentication Requirement: All requests passing through the proxy to upstream applications require authentication, excluding default proxy endpoints.
- Exception: If the request matches a skipped route (configured via `--skip-auth-route`):
- Authentication is not enforced, but the proxy will opportunistically attempt to validate a session cookie (`--cookie-name`) or JWT (`--skip-jwt-bearer-tokens`) if present in the request.
- Configured user info and authentication headers (e.g., `--pass-access-token`) are injected to upstream routes when validation succeeds.
Notice that the proxy also provides a number of useful [endpoints](features/endpoints.md).
2. Unauthenticated Requests: When authentication is missing but required, the user is redirected to the configured Identity Provider (IdP) login page by default.
- Ajax Requests: If the request has `Accept: application/json` header:
- Returns `401 Unauthorized`.
- Invalid JWT Tokens: If `--skip-jwt-bearer-tokens` is set and the request includes an invalid JWT:
- Redirects to the login page by default.
- Returns `403 Forbidden` if `--bearer-token-login-fallback` is set to `false`.
3. Post-Authentication: After successful authentication with the IdP, OAuth tokens are stored in the configured session store (cookie or Redis), and a cookie is set.
4. Request Forwarding: The authenticated request is processed based on configuration:
- Forwarded to the configured upstream application with added user info and authentication headers, or
- Returns a valid status code for downstream processing by another proxy or load balancer (e.g., Nginx or Traefik).
---
Note: The proxy also provides a number of useful [endpoints](features/endpoints.md) for monitoring and management.