Migration: consolidate Echo6 docs to cortex with full infrastructure cleanup sync
- Documents recent infrastructure cleanup (8 CTs destroyed, 35 DNS records removed, Headscale cleanup) - Adds 24 new runbooks covering Authentik, PeerTube, Meshtastic, RECON, Proxmox, Mailcow, Internet Archive, GPU routing - Adds project documentation for headscale, vaultwarden, peertube, matrix, mmud, advbbs, arr stack - Updates services.md, environment.md, caddy.md, authentik.md to match live infrastructure - Removes 4 deprecated runbook duplicates (canonical versions live in projects/) - Adds .gitignore for binary archives and editor temp files Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
89834796ff
commit
e9231ac24a
93 changed files with 51223 additions and 254 deletions
204
runbooks/authentik-create-invitation.md
Normal file
204
runbooks/authentik-create-invitation.md
Normal file
|
|
@ -0,0 +1,204 @@
|
|||
# Authentik: Create Invitation
|
||||
|
||||
Create user invitations via the Authentik Admin UI. Supports two modes: email (automatic delivery) and link-sharing (manual delivery).
|
||||
|
||||
---
|
||||
|
||||
## When to Use This
|
||||
|
||||
Any time a new user needs to be invited to Echo6 services. Invitations create a time-limited enrollment link that lets the invitee set up their own username and password.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Authentik admin access at https://auth.echo6.co
|
||||
- For email mode: SMTP must be configured and working (no-reply@echo6.co via Mailcow)
|
||||
|
||||
---
|
||||
|
||||
## Mode 1: Invite via Email (Automatic)
|
||||
|
||||
The invitation email is sent automatically when the invitation is created with an `email` field in custom attributes.
|
||||
|
||||
### Steps
|
||||
|
||||
1. Log in to https://auth.echo6.co as admin
|
||||
2. Navigate to **Directory → Invitations → Create**
|
||||
3. Fill in:
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Name | Descriptive name (e.g., `jane-smith-2026-02`) |
|
||||
| Flow | **Invitation Enrollment** |
|
||||
| Single use | **On** (recommended) |
|
||||
| Expires | Set appropriately (e.g., 7 days from now) |
|
||||
|
||||
4. In **Custom attributes** (YAML format):
|
||||
|
||||
```yaml
|
||||
name: Jane Smith
|
||||
email: jane@example.com
|
||||
```
|
||||
|
||||
5. Click **Create**
|
||||
|
||||
The expression policy (`invitation-email-sender`) detects the `email` field and calls `ak_send_email()` to deliver the enrollment link to the invitee. The email includes the invitation URL with the `?itoken=` parameter.
|
||||
|
||||
### What the Invitee Receives
|
||||
|
||||
- Email from `no-reply@echo6.co` with subject "You've been invited to join Echo6"
|
||||
- Contains a link to `https://auth.echo6.co/if/flow/invitation-enrollment/?itoken=<token>`
|
||||
- The link takes them through the enrollment flow: accept invitation → set username/password → auto-login
|
||||
|
||||
---
|
||||
|
||||
## Mode 2: Invite via Link (Manual)
|
||||
|
||||
For cases where you want to share the link yourself (Slack, Signal, in person, etc.), omit the `email` field.
|
||||
|
||||
### Steps
|
||||
|
||||
1. Log in to https://auth.echo6.co as admin
|
||||
2. Navigate to **Directory → Invitations → Create**
|
||||
3. Fill in:
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Name | Descriptive name (e.g., `jane-smith-link`) |
|
||||
| Flow | **Invitation Enrollment** |
|
||||
| Single use | **On** (recommended) |
|
||||
| Expires | Set appropriately |
|
||||
|
||||
4. **Custom attributes** — either leave empty `{}` or include only the name:
|
||||
|
||||
```yaml
|
||||
name: Jane Smith
|
||||
```
|
||||
|
||||
Do **not** include an `email` field — this prevents the automatic email from being sent.
|
||||
|
||||
5. Click **Create**
|
||||
6. In the invitation list, **expand the row** to reveal the invitation link
|
||||
7. Copy and share the link manually
|
||||
|
||||
---
|
||||
|
||||
## Custom Attributes Reference
|
||||
|
||||
| Field | Required | Purpose |
|
||||
|-------|----------|---------|
|
||||
| `name` | No | Pre-fills the invitee's display name (if enrollment flow uses it) |
|
||||
| `email` | No | Triggers automatic email delivery. Omit for link-sharing mode |
|
||||
|
||||
Only `email` affects system behavior. Any other fields are stored as metadata on the invitation.
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Expiry
|
||||
|
||||
- **Email invitations:** 7 days is reasonable — gives time for the email to arrive and the user to act
|
||||
- **Link invitations:** 24–48 hours if sharing in real-time; 7 days if async
|
||||
- **Never use no-expiry** — orphaned invitations are a security risk
|
||||
|
||||
### Single Use
|
||||
|
||||
- **Always enable** for individual invitations — prevents link reuse after the invitee enrolls
|
||||
- Only disable if you're creating a batch enrollment link for a group (rare)
|
||||
|
||||
### Naming Convention
|
||||
|
||||
Use `firstname-lastname-YYYY-MM` or `purpose-YYYY-MM` for easy identification:
|
||||
- `jane-smith-2026-02`
|
||||
- `jodie-media-access-2026-02`
|
||||
- `batch-beta-testers-2026-03`
|
||||
|
||||
---
|
||||
|
||||
## After Enrollment
|
||||
|
||||
New users are created under the `users/enrolled` path. To grant them access to services:
|
||||
|
||||
1. Navigate to **Directory → Groups**
|
||||
2. Add the user to the appropriate group(s):
|
||||
|
||||
| Group | Grants Access To |
|
||||
|-------|-----------------|
|
||||
| media-users | Jellyfin, Jellyseer, PeerTube |
|
||||
| ai-users | Open WebUI |
|
||||
| cloud-users | Immich, Nextcloud |
|
||||
| communication-users | Mailcow, Matrix |
|
||||
|
||||
See the [Access Groups runbook](authentik-access-groups.md) for detailed group management procedures.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Email not sent (email mode)
|
||||
|
||||
1. **Check custom attributes** — the `email` field must be present and correctly formatted
|
||||
2. **Check SMTP** — verify Authentik can send email:
|
||||
```bash
|
||||
ssh root@100.64.0.1
|
||||
docker exec authentik-server ak test_email matt@echo6.co
|
||||
```
|
||||
3. **Check Mailcow authsource** — if SMTP auth fails, the no-reply@echo6.co mailbox may have reverted to `generic-oidc`. See [Mailcow Create Mailbox runbook](mailcow-create-mailbox.md), Step 2
|
||||
4. **Check Authentik logs**:
|
||||
```bash
|
||||
docker compose -f /opt/authentik/docker-compose.yml logs server --since 5m 2>&1 | grep -i email
|
||||
```
|
||||
|
||||
### "Invalid invite/invite not found" when clicking link
|
||||
|
||||
- The invitation has expired or was already used (single-use)
|
||||
- The invitation was deleted
|
||||
- The `?itoken=` parameter is missing or malformed in the URL
|
||||
|
||||
### User enrolled but can't access any apps
|
||||
|
||||
- The user needs to be added to at least one service group (see "After Enrollment" above)
|
||||
- By default, enrolled users have no group memberships
|
||||
|
||||
---
|
||||
|
||||
## Managing Existing Invitations
|
||||
|
||||
### View All Invitations
|
||||
|
||||
Admin UI → **Directory → Invitations** — shows all active invitations with name, expiry, and usage status.
|
||||
|
||||
### Delete an Invitation
|
||||
|
||||
Click the trash icon next to the invitation. This immediately invalidates the link — anyone who hasn't enrolled yet will see "Invalid invite."
|
||||
|
||||
### Via API
|
||||
|
||||
```bash
|
||||
# List all invitations
|
||||
curl -s "https://auth.echo6.co/api/v3/stages/invitation/invitations/" \
|
||||
-H "Authorization: Bearer $AUTHENTIK_API_TOKEN" | python3 -m json.tool
|
||||
|
||||
# Delete by PK
|
||||
curl -s -X DELETE "https://auth.echo6.co/api/v3/stages/invitation/invitations/<PK>/" \
|
||||
-H "Authorization: Bearer $AUTHENTIK_API_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
```
|
||||
[ ] Invitation created with correct flow (Invitation Enrollment)
|
||||
[ ] Single use enabled
|
||||
[ ] Expiry set appropriately
|
||||
[ ] Email mode: email field in custom attributes, delivery confirmed
|
||||
[ ] Link mode: link copied and shared manually
|
||||
[ ] After enrollment: user added to appropriate groups
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Created: 2026-02-16*
|
||||
Loading…
Add table
Add a link
Reference in a new issue