Skip to content

Commit e1f3ad6

Browse files
jsiebensjsiebens
committed
chore: updates docs
1 parent a2fd56b commit e1f3ad6

File tree

13 files changed

+1245
-223
lines changed

13 files changed

+1245
-223
lines changed

‎mkdocs/docs/configuration/auth-oidc.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# Configuring authentication with OIDC
2+
3+
While ionscale can operate without an OIDC (OpenID Connect) provider using only static keys, configuring an OIDC provider is highly recommended for enhanced security, user management, and a smoother administrative experience.
4+
5+
## Why configure an OIDC provider?
6+
7+
Without an OIDC provider, ionscale operates in a key-only mode:
8+
9+
- System administrators can only use the system admin key for administrative tasks
10+
- Tailscale devices can only connect using [tags](https://tailscale.com/kb/1068/tags) and [pre-authentication keys](https://tailscale.com/kb/1085/auth-keys)
11+
- No user accounts or user-specific permissions are available
12+
13+
With an OIDC provider configured:
14+
15+
- Users can authenticate using their existing identity provider credentials
16+
- Administrators can assign specific permissions to users
17+
- System administration can be delegated to specific users
18+
- Fine-grained access control based on user identity becomes possible
19+
- More seamless user experience with browser-based authentication
20+
21+
## Supported OIDC providers
22+
23+
ionscale supports any standard OIDC provider, including:
24+
25+
- Google Workspace
26+
- Auth0
27+
- Okta
28+
- Azure AD / Microsoft Entra ID
29+
- Keycloak
30+
- GitLab
31+
- GitHub (OAuth 2.0 with OIDC extensions)
32+
- And many others
33+
34+
## Basic OIDC configuration
35+
36+
To configure an OIDC provider, update your ionscale configuration file (`config.yaml`) with the following settings:
37+
38+
```yaml
39+
auth:
40+
provider:
41+
# OIDC issuer URL where ionscale can find the OpenID Provider Configuration Document
42+
issuer: "https://your-oidc-provider.com"
43+
# OIDC client ID and secret
44+
client_id: "your-client-id"
45+
client_secret: "your-client-secret"
46+
# Optional: additional OIDC scopes used in the OIDC flow
47+
additional_scopes: "groups"
48+
```
49+
50+
### Required configuration fields
51+
52+
- `issuer`: The URL to your OIDC provider's issuer. This URL is used to discover your provider's endpoints.
53+
- `client_id`: The client ID from your OIDC provider application registration.
54+
- `client_secret`: The client secret from your OIDC provider application registration.
55+
56+
### Optional configuration
57+
58+
- `additional_scopes`: A space-separated list of additional OAuth scopes to request during authentication.
59+
By default, ionscale requests the `openid`, `email`, and `profile` scopes.
60+
61+
## Configuring your OIDC provider
62+
63+
When registering ionscale with your OIDC provider, you'll need to configure the following:
64+
65+
**Redirect URI**: Set to `https://your-ionscale-domain.com/auth/callback`
66+
67+
## System administrator access
68+
69+
With OIDC configured, you'll want to specify which users have system administrator privileges.
70+
This is done in the `auth.system_admins` section of your configuration:
71+
72+
```yaml
73+
auth:
74+
# Configuration from previous section...
75+
76+
system_admins:
77+
# By email address
78+
emails:
79+
- "admin@example.com"
80+
- "secadmin@example.com"
81+
82+
# By subject identifier (sub claim from OIDC)
83+
subs:
84+
- "user|123456"
85+
86+
# By attribute expression (using BEXPR syntax)
87+
filters:
88+
- "token.groups contains \"admin\""
89+
- "domain == \"admin.example.com\""
90+
```
91+
92+
You can use one or more of these methods to designate system administrators:
93+
94+
1. **By Email**: List specific email addresses that should have admin privileges.
95+
2. **By Subject ID**: List specific user IDs (the `sub` claim from your OIDC provider).
96+
3. **By Expression**: Use BEXPR filters to determine admin status based on token claims.
97+
98+
## OIDC authentication flow
99+
100+
When a user attempts to authenticate with ionscale:
101+
102+
1. The user is redirected to the OIDC provider's login page.
103+
2. After successful authentication, the user is redirected back to ionscale.
104+
3. ionscale verifies the authentication and checks if:
105+
- The user is a system administrator (based on the `system_admins` configuration).
106+
- The user has access to any tailnets (based on IAM policies configured for individual tailnets).
107+
108+
## Provider-specific setup instructions
109+
110+
### Google
111+
112+
1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
113+
2. Create a new project or select an existing one.
114+
3. Navigate to "APIs & Services" > "Credentials".
115+
4. Click "Create Credentials" > "OAuth client ID".
116+
5. Select "Web application" as the application type.
117+
6. Add `https://your-ionscale-domain.com/auth/callback` as an authorized redirect URI.
118+
7. Copy the client ID and client secret.
119+
120+
Configure ionscale:
121+
```yaml
122+
auth:
123+
provider:
124+
issuer: "https://accounts.google.com"
125+
client_id: "your-client-id.apps.googleusercontent.com"
126+
client_secret: "your-client-secret"
127+
```
128+
129+
### Auth0
130+
131+
1. Go to the [Auth0 Dashboard](https://manage.auth0.com/).
132+
2. Create a new application or select an existing one of type "Regular Web Application".
133+
3. Under "Settings", configure:
134+
- Allowed Callback URLs: `https://your-ionscale-domain.com/auth/callback`
135+
4. Copy the Domain, Client ID, and Client Secret.
136+
137+
Configure ionscale:
138+
```yaml
139+
auth:
140+
provider:
141+
issuer: "https://your-tenant.auth0.com/"
142+
client_id: "your-client-id"
143+
client_secret: "your-client-secret"
144+
```
145+
146+
### Microsoft Azure AD / Entra ID
147+
148+
1. Go to the [Azure Portal](https://portal.azure.com/).
149+
2. Navigate to "Azure Active Directory" > "App registrations".
150+
3. Create a new registration.
151+
4. Add `https://your-ionscale-domain.com/auth/callback` as a redirect URI of type "Web".
152+
5. Under "Certificates & secrets", create a new client secret.
153+
6. Copy the Application (client) ID and the new secret.
154+
155+
Configure ionscale:
156+
```yaml
157+
auth:
158+
provider:
159+
issuer: "https://login.microsoftonline.com/your-tenant-id/v2.0"
160+
client_id: "your-client-id"
161+
client_secret: "your-client-secret"
162+
additional_scopes: "offline_access"
163+
```
164+
165+
## Complete configuration example
166+
167+
```yaml
168+
auth:
169+
provider:
170+
issuer: "https://accounts.google.com"
171+
client_id: "your-client-id.apps.googleusercontent.com"
172+
client_secret: "your-client-secret"
173+
additional_scopes: "groups"
174+
175+
system_admins:
176+
emails:
177+
- "admin@example.com"
178+
filters:
179+
- "domain == \"example.com\" && token.groups contains \"admin\""
180+
```
181+
182+
## OIDC without system admin
183+
184+
If you've configured OIDC but no system administrators, you can still use the system admin key from your initial setup for administrative tasks:
185+
186+
```bash
187+
export IONSCALE_URL="https://your-ionscale-domain.com"
188+
export IONSCALE_KEY="your-system-admin-key"
189+
ionscale tailnet list
190+
```
191+

‎mkdocs/docs/configuration/dns-providers.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Configuring DNS providers
2+
3+
ionscale supports integration with various DNS providers to enable Tailscale's HTTPS certificate functionality. When a DNS provider is properly configured, ionscale can automatically manage TXT records required for the DNS-01 challenge when requesting certificates.
4+
5+
## Why configure a DNS provider
6+
7+
While not strictly required for basic ionscale operation, configuring a DNS provider enables important Tailscale features:
8+
9+
1. **Tailscale HTTPS Certificates**: Allows nodes to receive valid HTTPS certificates for their Tailscale hostnames, enabling secure web services within your tailnet.
10+
2. **Tailscale Serve**: Supports the `tailscale serve` feature, which allows users to easily share web services with proper HTTPS.
11+
12+
Without a configured DNS provider, these features will not be available to your users.
13+
14+
## Supported DNS providers
15+
16+
ionscale uses the [libdns](https://github.com/libdns) libraries to support the following DNS providers:
17+
18+
- [Azure DNS](https://github.com/libdns/azure)
19+
- [Cloudflare](https://github.com/libdns/cloudflare)
20+
- [DigitalOcean](https://github.com/libdns/digitalocean)
21+
- [Google Cloud DNS](https://github.com/libdns/googleclouddns)
22+
- [Amazon Route 53](https://github.com/libdns/route53)
23+
24+
!!! info "Provider availability"
25+
These are the DNS providers supported at the time of this writing. Since ionscale uses the libdns ecosystem, additional providers may be added in future releases as the ecosystem expands.
26+
27+
If you need support for a different DNS provider, check the [libdns GitHub organization](https://github.com/libdns) for newly available providers or consider contributing an implementation for your provider.
28+
29+
!!! note "Future plugin system"
30+
A plugin system for DNS providers is currently in the ideation phase. This would make it significantly easier to add and configure additional DNS providers without modifying the core ionscale code. Stay tuned for updates on this feature in future releases.
31+
32+
## DNS provider configuration
33+
34+
To configure a DNS provider, add the appropriate settings to your ionscale configuration file (`config.yaml`):
35+
36+
```yaml
37+
dns:
38+
# The base domain for MagicDNS FQDN hostnames
39+
magic_dns_suffix: "ionscale.net"
40+
41+
# DNS provider configuration for HTTPS certificates
42+
provider:
43+
# Name of your DNS provider
44+
name: "cloudflare"
45+
# The DNS zone to use (typically your domain name)
46+
zone: "example.com"
47+
# Provider-specific configuration (varies by provider)
48+
config:
49+
# Provider-specific credentials and settings go here
50+
# See provider-specific examples below
51+
```
52+
53+
### Important requirements
54+
55+
1. The `magic_dns_suffix` must be a subdomain of the provider's zone (or the zone itself).
56+
2. MagicDNS must be enabled for the tailnet to use HTTPS certificates.
57+
3. You must have administrative access to the DNS zone to configure the provider.
58+
59+
## Provider-specific examples
60+
61+
### Cloudflare
62+
63+
```yaml
64+
dns:
65+
magic_dns_suffix: "ts.example.com"
66+
provider:
67+
name: "cloudflare"
68+
zone: "example.com"
69+
config:
70+
auth_token: "your-cloudflare-api-token"
71+
# OR use email/api_key authentication
72+
# email: "your-email@example.com"
73+
# api_key: "your-global-api-key"
74+
```
75+
76+
For Cloudflare, create an API token with the "Edit" permission for "Zone:DNS".
77+
78+
### Azure DNS
79+
80+
```yaml
81+
dns:
82+
magic_dns_suffix: "ts.example.com"
83+
provider:
84+
name: "azure"
85+
zone: "example.com"
86+
config:
87+
tenant_id: "your-tenant-id"
88+
client_id: "your-client-id"
89+
client_secret: "your-client-secret"
90+
subscription_id: "your-subscription-id"
91+
resource_group_name: "your-resource-group"
92+
```
93+
94+
For Azure, create a service principal with "DNS Zone Contributor" role for your DNS zone's resource group.
95+
96+
### Amazon Route 53
97+
98+
```yaml
99+
dns:
100+
magic_dns_suffix: "ts.example.com"
101+
provider:
102+
name: "route53"
103+
zone: "example.com"
104+
config:
105+
access_key_id: "your-access-key-id"
106+
secret_access_key: "your-secret-access-key"
107+
# Optional region, defaults to us-east-1
108+
region: "us-east-1"
109+
```
110+
111+
For AWS Route 53, create an IAM user with permissions to modify records in your hosted zone.
112+
113+
### Google Cloud DNS
114+
115+
```yaml
116+
dns:
117+
magic_dns_suffix: "ts.example.com"
118+
provider:
119+
name: "googleclouddns"
120+
zone: "example-com" # Note: GCP uses zone names without dots
121+
config:
122+
project: "your-project-id"
123+
# Either provide service account JSON directly
124+
service_account_json: '{"type":"service_account","project_id":"your-project",...}'
125+
# OR specify a path to a service account key file
126+
# service_account_key_file: "/path/to/service-account-key.json"
127+
```
128+
129+
For Google Cloud DNS, create a service account with the "DNS Administrator" role.
130+
131+
### DigitalOcean
132+
133+
```yaml
134+
dns:
135+
magic_dns_suffix: "ts.example.com"
136+
provider:
137+
name: "digitalocean"
138+
zone: "example.com"
139+
config:
140+
token: "your-digitalocean-api-token"
141+
```
142+
143+
For DigitalOcean, create an API token with read and write access.
144+
145+
## Enabling HTTPS certificates for a tailnet
146+
147+
After configuring a DNS provider in your ionscale server, you can enable HTTPS certificates for a tailnet:
148+
149+
```bash
150+
# Enable MagicDNS and HTTPS certificates for a tailnet
151+
ionscale dns update --tailnet "my-tailnet" --magic-dns --https-certs
152+
```
153+
154+
## Verifying DNS provider configuration
155+
156+
To verify that your DNS provider is correctly configured:
157+
158+
1. Configure a tailnet with MagicDNS and HTTPS certificates enabled.
159+
2. Connect a device to the tailnet.
160+
3. On the device, run:
161+
```bash
162+
tailscale cert <hostname>
163+
```
164+
4. If successful, the command will obtain a certificate for the hostname.
165+
5. You should see TXT records created in your DNS zone for the ACME challenge.
166+
167+
## Troubleshooting
168+
169+
If you encounter issues with DNS provider integration:
170+
171+
1. **Check DNS Provider Credentials**: Ensure the credentials in your configuration have sufficient permissions.
172+
2. **Verify Zone Configuration**: Make sure the zone in your configuration matches your actual DNS zone.
173+
3. **Check MagicDNS Settings**: Confirm that `magic_dns_suffix` is properly configured as a subdomain of your zone.
174+
4. **Review Server Logs**: The ionscale server logs may contain error messages related to DNS provider integration.
175+
5. **Test DNS Record Creation**: Some providers offer tools to test API access for creating and updating DNS records.
176+

0 commit comments

Comments
 (0)