Skip to content

Commit 44084f7

Browse files
josecsotomoralesjosecsotomorales
committed
Refactor deployment option docs
1 parent 6025910 commit 44084f7

8 files changed

Lines changed: 1043 additions & 310 deletions

File tree

‎docs/deployments/auth0-setup.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# Auth0 Authentication Setup
2+
3+
!!! warning "Self-Hosted Deployments Only"
4+
This guide is for **customer-managed (self-hosted) deployments** where you manage your own Kubernetes infrastructure. If your Qualytics instance is managed by Qualytics (PaaS/SaaS), see the [SSO Setup Guide](sso.md) instead — your account manager handles authentication configuration for you.
5+
6+
This guide explains how to configure Auth0 authentication for a self-hosted Qualytics deployment. Auth0 is an **alternative authentication method** managed by Qualytics. While [OIDC](oidc-configuration.md) is recommended for most self-hosted deployments, Auth0 is a simpler option for organizations that have internet access from their cluster and prefer a managed authentication service.
7+
8+
## When to Use Auth0 vs OIDC
9+
10+
| Consideration | Auth0 | OIDC |
11+
|---------------|-------|------|
12+
| **Internet access** | Requires egress to `auth.qualytics.io` | No internet access required |
13+
| **Air-gapped support** | Not supported | Fully supported |
14+
| **Setup complexity** | Simpler — Qualytics manages the IdP | Requires IdP configuration by the customer |
15+
| **IdP management** | Managed by Qualytics | Managed by the customer |
16+
| **SSO federation** | Supports SSO through Auth0's integration network | Direct integration with your enterprise IdP |
17+
| **CLI authentication** | Browser-based PKCE flow | Manual token paste |
18+
19+
!!! tip "Recommendation"
20+
**OIDC is recommended** for self-hosted deployments because it provides direct integration with your enterprise Identity Provider, supports air-gapped environments, and keeps authentication entirely within your network. Use Auth0 if you prefer a managed solution and your cluster has internet access.
21+
22+
## How Auth0 Works for Self-Hosted Deployments
23+
24+
Unlike OIDC (where you configure your own Identity Provider), Auth0 is a managed service where Qualytics handles the authentication infrastructure:
25+
26+
1. **You request** Auth0 resources from Qualytics
27+
2. **Qualytics provisions** an Auth0 organization, client credentials, and SSO connections
28+
3. **You configure** the provided values in your Helm deployment
29+
4. **Qualytics manages** ongoing Auth0 maintenance and updates
30+
31+
## Step 1: Request Auth0 Resources from Qualytics
32+
33+
Contact your [Qualytics account manager](mailto:hello@qualytics.ai) to request Auth0 authentication for your self-hosted deployment. Include the following information in your request:
34+
35+
| Information | Description |
36+
|-------------|-------------|
37+
| **Company name** | Your organization's name |
38+
| **Deployment domain** | The domain where Qualytics will be accessible (e.g., `qualytics.example.com`) |
39+
| **SSO requirements** (optional) | If you want to federate Auth0 with your enterprise IdP (e.g., Azure AD, Okta), specify the IdP and protocol (SAML, OIDC) |
40+
| **User count estimate** | Approximate number of users who will access Qualytics |
41+
42+
### What You Will Receive
43+
44+
After Qualytics provisions your Auth0 resources, your account manager will provide:
45+
46+
| Value | Description |
47+
|-------|-------------|
48+
| `AUTH0_DOMAIN` | Your Auth0 tenant domain (typically `auth.qualytics.io`) |
49+
| `AUTH0_AUDIENCE` | Your API audience identifier |
50+
| `AUTH0_ORGANIZATION` | Your Auth0 organization ID (e.g., `org_abc123`) |
51+
| `AUTH0_CLIENT_ID` | Your SPA client ID (required for UI and CLI authentication) |
52+
53+
## Step 2: Configure Qualytics
54+
55+
Add the Auth0 values provided by Qualytics to your Helm `values.yaml` file:
56+
57+
### Required Settings
58+
59+
| Helm Value | Description |
60+
|------------|-------------|
61+
| `secrets.auth0.auth0_audience` | API audience identifier (provided by Qualytics) |
62+
| `secrets.auth0.auth0_organization` | Auth0 organization ID (provided by Qualytics) |
63+
| `secrets.auth0.auth0_spa_client_id` | SPA client ID (provided by Qualytics) |
64+
| `secrets.auth.jwt_signing_secret` | Secret for signing JWTs (minimum 32 characters — you generate this) |
65+
66+
!!! note
67+
Auth0 is the default authentication mode (`global.authType: "AUTH0"`), so you do not need to set it explicitly. The Auth0 domain defaults to `auth.qualytics.io`.
68+
69+
### Example `values.yaml` Configuration
70+
71+
```yaml
72+
global:
73+
dnsRecord: "qualytics.example.com"
74+
authType: "AUTH0" # default — can be omitted
75+
76+
secrets:
77+
auth0:
78+
auth0_audience: "your-api-audience"
79+
auth0_organization: "org_your-org-id"
80+
auth0_spa_client_id: "your-spa-client-id"
81+
auth:
82+
jwt_signing_secret: "your-secure-random-string-min-32-chars"
83+
postgres:
84+
secrets_passphrase: "your-secure-passphrase"
85+
rabbitmq:
86+
rabbitmq_password: "your-secure-password"
87+
```
88+
89+
!!! tip "Generating Secure Secrets"
90+
Use `openssl rand -base64 32` to generate the `jwt_signing_secret` and other security secrets.
91+
92+
## Step 3: Deploy or Restart
93+
94+
If this is a new deployment, follow the [Self-Hosted Deployment Guide](self-hosted-deployment.md) to deploy Qualytics.
95+
96+
If you are updating an existing deployment:
97+
98+
```bash
99+
helm upgrade qualytics qualytics/qualytics \
100+
--namespace qualytics \
101+
-f values.yaml \
102+
--timeout=20m
103+
```
104+
105+
## Step 4: Verify Authentication
106+
107+
1. Navigate to your Qualytics instance in a browser (e.g., `https://qualytics.example.com`)
108+
2. You should be redirected to the Auth0 login page
109+
3. Authenticate using your credentials (or your enterprise SSO if configured)
110+
4. After successful authentication, you should be redirected back to the Qualytics UI
111+
112+
## Network Requirements
113+
114+
Auth0 authentication requires your cluster to have outbound (egress) access to:
115+
116+
| Endpoint | Purpose |
117+
|----------|---------|
118+
| `https://auth.qualytics.io` | Auth0 authentication service |
119+
120+
!!! warning "Air-Gapped Environments"
121+
Auth0 is **not compatible** with fully air-gapped deployments. If your environment has no internet access, use [OIDC authentication](oidc-configuration.md) instead.
122+
123+
## SSO Federation Through Auth0
124+
125+
Auth0 supports federating authentication with your enterprise Identity Provider. This means your users can log in to Qualytics using their existing corporate credentials through Auth0.
126+
127+
Supported federation protocols through Auth0:
128+
129+
- OpenID Connect (OIDC)
130+
- SAML 2.0
131+
- Active Directory / LDAP
132+
- Azure Active Directory (Entra ID)
133+
- Google Workspace
134+
- Okta
135+
- PingFederate
136+
137+
To set up SSO federation, include your IdP details when [requesting Auth0 resources](#step-1-request-auth0-resources-from-qualytics) from Qualytics. Your account manager will configure the appropriate connection.
138+
139+
## CLI Authentication
140+
141+
With Auth0, the Qualytics CLI supports **browser-based authentication** using the PKCE (Proof Key for Code Exchange) flow:
142+
143+
1. Run the CLI authentication command
144+
2. A browser window opens automatically
145+
3. Authenticate with Auth0 (or your federated IdP)
146+
4. The CLI receives the token automatically
147+
148+
This provides a smoother CLI experience compared to the manual token paste required with OIDC.
149+
150+
## Troubleshooting
151+
152+
| Symptom | Likely Cause | Solution |
153+
|---------|-------------|----------|
154+
| Cannot reach Auth0 login page | Network egress blocked | Ensure your cluster allows outbound access to `https://auth.qualytics.io` |
155+
| Invalid audience or organization error | Incorrect Auth0 configuration | Verify `secrets.auth0.auth0_audience` and `secrets.auth0.auth0_organization` match what Qualytics provided |
156+
| CLI authentication fails | Missing client ID | Ensure `secrets.auth0.auth0_spa_client_id` is set in your `values.yaml` |
157+
| SSO redirect loop | Misconfigured SSO connection | Contact your [Qualytics account manager](mailto:hello@qualytics.ai) to verify the SSO connection |
158+
159+
!!! info "Need Help?"
160+
Contact your [Qualytics account manager](mailto:hello@qualytics.ai) for assistance with Auth0 configuration or to request changes to your Auth0 setup.

0 commit comments

Comments
 (0)