Add a New Service Behind Authentik

Prerequisites#

Before starting, confirm the following:

• The target service is running and accessible on its internal hostname/port
• Traefik is operational and routing traffic correctly
• Authentik is healthy (check https://auth.valkyrienexus.com/if/flow/initial-setup/)
• You have Authentik admin credentials
• The DNS record for the new service exists in Cloudflare (or will be created via tunnel)
• The Cloudflare Tunnel is running and connected

Step 1: Create the Authentik Application#

1. Log into the Authentik admin interface at https://auth.valkyrienexus.com/if/admin/

2. Navigate to Applications > Applications

3. Click Create and fill in:

   • Name: Human-readable name (e.g., "Grafana Dashboard")
   • Slug: URL-safe identifier (e.g., grafana-dashboard)
   • Group: Select the appropriate group or leave blank
   • Launch URL: The external URL users will access (e.g., https://grafana.valkyrienexus.com)

4. Click Create to save the application

Step 2: Create the Provider#

Each application needs a provider that defines how authentication works.

For Proxy Authentication (most common)#

1. Navigate to Applications > Providers

2. Click Create and select Proxy Provider

3. Configure:

   • Name: Match the application name with "Provider" suffix
   • Authorization flow: Select default-provider-authorization-explicit-consent for first-time consent, or default-provider-authorization-implicit-consent for seamless SSO
   • External host: The public URL (e.g., https://grafana.valkyrienexus.com)
   • Mode: Forward auth (single application)

4. Under Advanced protocol settings:

   • Token validity: hours=24 for standard services, hours=8 for sensitive ones

5. Click Finish and link the provider to the application created in Step 1

For OAuth2/OIDC (if the service supports it)#

1. Select OAuth2/OpenID Provider instead
2. Set the Redirect URIs to the service's callback URL
3. Note the Client ID and Client Secret for service configuration

Step 3: Configure Traefik Routing#

Add the service to your Traefik dynamic configuration. If using Docker labels:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.grafana.rule=Host(`grafana.valkyrienexus.com`)"
  - "traefik.http.routers.grafana.entrypoints=websecure"
  - "traefik.http.routers.grafana.tls=true"
  - "traefik.http.routers.grafana.middlewares=authentik@docker"
  - "traefik.http.services.grafana.loadbalancer.server.port=3000"

If using a file-based configuration:

# dynamic/grafana.yml
http:
  routers:
    grafana:
      rule: "Host(`grafana.valkyrienexus.com`)"
      entryPoints:
        - websecure
      service: grafana
      middlewares:
        - authentik-forward-auth
      tls: {}

  services:
    grafana:
      loadBalancer:
        servers:
          - url: "http://grafana:3000"

The authentik-forward-auth middleware should already be defined in your Traefik static configuration. If not, add it:

http:
  middlewares:
    authentik-forward-auth:
      forwardAuth:
        address: "http://authentik-server:9000/outpost.goauthentik.io/auth/traefik"
        trustForwardHeader: true
        authResponseHeaders:
          - X-authentik-username
          - X-authentik-groups
          - X-authentik-email
          - X-authentik-name
          - X-authentik-uid
          - X-authentik-jwt
          - X-authentik-meta-jwks
          - X-authentik-meta-outpost
          - X-authentik-meta-provider
          - X-authentik-meta-app
          - X-authentik-meta-version

Step 4: Add the Cloudflare Tunnel Route#

If the service should be externally accessible, add a route to your cloudflared configuration:

# cloudflared/config.yml
tunnel: <your-tunnel-id>
credentials-file: /etc/cloudflared/credentials.json

ingress:
  # ... existing routes ...
  - hostname: grafana.valkyrienexus.com
    service: http://traefik:80
  # Catch-all (must be last)
  - service: http_status:404

After modifying the config, restart the cloudflared service:

# If running as a systemd service
sudo systemctl restart cloudflared

# If running in Docker
docker compose restart cloudflared

Step 5: Create an Authentik Outpost#

If this is your first proxy-authenticated service, you need an outpost.

1. Navigate to Applications > Outposts

2. Click Create:

   • Name: traefik-outpost
   • Type: Proxy
   • Integration: Select your Docker or Kubernetes integration
   • Applications: Select all applications that should use this outpost

3. If you already have an outpost, edit it and add the new application to its application list

Step 6: Set Access Policies#

1. Navigate to Applications > Applications > select your app
2. Go to the Policy / Group / User Bindings tab
3. Click Bind existing policy or Create and bind Policy

Common Policy Patterns#

Internal users only:

• Bind a Group policy for the internal-users group
• Deny all others

Specific team access:

• Bind a Group policy for the relevant team group
• Set the policy to AND if multiple conditions are required

Public with authentication:

• No restrictive policy needed -- any authenticated user can access
• The authentication flow itself is the gate

Step 7: Verify#

1. Open the external URL in an incognito/private browser window
2. Confirm you are redirected to the Authentik login page
3. Log in with valid credentials
4. Verify the service loads correctly after authentication
5. Test with a user who should NOT have access to confirm the policy denies them
6. Check Authentik's Events > Logs for the authentication events

Rollback#

If something goes wrong:

1. Service unreachable: Check Traefik logs for routing errors. Verify the service is running on its expected port.
2. Authentication loop: The outpost may not be correctly configured. Check that the outpost includes the application and that the forward-auth middleware URL is correct.
3. 403 after login: The access policy is denying the user. Review policy bindings and group membership.
4. 502 Bad Gateway: Traefik cannot reach the backend service. Verify the service URL in Traefik configuration and check network connectivity between containers.

To quickly restore access while debugging, you can temporarily remove the authentik-forward-auth middleware from the Traefik router. This bypasses authentication entirely -- only do this on non-sensitive services and revert immediately after debugging.

Maintenance Notes#

• When upgrading Authentik, always check the outpost version matches the server version
• Rotate provider tokens periodically (set a calendar reminder)
• Audit application access logs monthly via Events > Logs
• Document each new application in the infrastructure inventory