SSO dla apek 3rd-party

Portainer, Grafana, Argo CD, Proxmox, Gitea — wepnij WolfieAuth przed dowolną apkę która mówi OIDC albo OAuth2. Krok po kroku.

SSO dla apek 3rd-party — używanie WolfieAuth jako identity provider

TL;DR: WolfieAuth to standardowy OIDC provider pod https://auth.wolfieguard.com. Wszystko co mówi OIDC albo generic OAuth2 (Portainer, Grafana, Argo CD, Proxmox, Gitea, Nextcloud, …) wpina się przez zarejestrowanie jednego OidcClient i wkleja czterech URL-i w settings auth-u apki. Passwordless propaguje się automatycznie — gdy user zaloguje się do WolfieAuth passkeyem albo magic linkiem, downstream apki widzą tylko ważny id_token; nigdy nie wiedzą jak user się uwierzytelnił.

Trzy rzeczy które zawsze robisz

Każda integracja na tej stronie idzie tymi trzema krokami:

1. Zarejestruj apkę w WolfieAuth. https://auth.wolfieguard.com/admin/clients/new → wybierz appKind=oauth (albo custom), ustaw redirect URI na to co mówią docsy apki (lista poniżej), skopiuj client_id + client_secret.
2. Wklej discovery URL do apki. Nowoczesne apki chcą tylko https://auth.wolfieguard.com/.well-known/openid-configuration i auto-discover-ują resztę. Starsze chcą cztery endpointy ręcznie:
   • Authorize: https://auth.wolfieguard.com/auth
   • Token: https://auth.wolfieguard.com/token
   • Userinfo: https://auth.wolfieguard.com/me
   • JWKS: https://auth.wolfieguard.com/jwks
3. Test round-trip — wyloguj się, klik “Sign in with WolfieAuth”, potwierdź że wracasz uwierzytelniony. Jeśli masz passkey na koncie WolfieAuth, cały ten flow jest passwordless end-to-end.

Reszta strony to per-apka boilerplate: gdzie siedzi każdy setting, jakie scopes prosić, jakie claimy mapować na role.

Portainer

Portainer ma dwie edycje: Community Edition (free, “Custom OAuth” provider) i Business Edition (natywny OIDC dropdown). Obie działają. BE jest bardziej turn-key bo auto-discover-uje przez .well-known URL.

Portainer CE — Custom OAuth flow

W panelu admin Portainera: Settings → Authentication → OAuth → Custom.

Potem w WolfieAuth /admin/clients/<twoja-portainer-app> → Overview, zarejestruj Redirect URI jako https://portainer.twoj-host.tld/. Zapisz. Klik “Sign in with OAuth” na login page Portainera — powinieneś bouncnąć do auth.wolfieguard.com, zalogować się (albo przejść silently jeśli masz już SSO cookie), i wylądować jako Portainer user.

Portainer BE — natywny OIDC

Settings → Authentication → OIDC.

BE dodaje team auto-mapping: jeśli ticknięte “Auto team membership” + wybrany default team, każdy user który zaloguje się przez WolfieAuth dostaje auto-add do tego teamu. Możesz override-ować per-user później.

Mapowanie ról WolfieAuth na Portainer

Portainer domyślnie nie czyta JWT claims dla ról — każdy OIDC user ląduje jako “standard user”. Awansujesz go do admina przez:

• Ustawienie is_admin raz przez stronę Users w Portainer, ALBO
• Pre-create-owanie teamu “wolfieauth-admins” w Portainer i toggle Auto team membership z wybranym tym teamem.

Dla ziarnistej kontroli per WolfieAuth org/plan użyj JWT template na OidcClient żeby przemapować wolfieauth_role_slug na claim groups: ["admin"], potem włącz group sync w Portainer BE.

Grafana

Grafana ma first-class Generic OAuth support który mapuje czyściutko na WolfieAuth.

grafana.ini (albo env vary):

[auth.generic_oauth]
enabled = true
name = WolfieAuth
client_id = <z-panelu-wolfieauth>
client_secret = <z-panelu-wolfieauth>
scopes = openid email profile
auth_url = https://auth.wolfieguard.com/auth
token_url = https://auth.wolfieguard.com/token
api_url = https://auth.wolfieguard.com/me
allow_sign_up = true
role_attribute_path = contains(wolfieauth_role_slug, 'admin') && 'Admin' || contains(wolfieauth_role_slug, 'editor') && 'Editor' || 'Viewer'

W WolfieAuth zarejestruj redirect URI jako https://grafana.twoj-host.tld/login/generic_oauth. JMESPath w role_attribute_path mapuje twój WolfieAuth role slug na trzy role Grafany.

Dla mapowania org / team Grafany, requestuj scope org w WolfieAuth + użyj:

team_ids_attribute_path = wolfieauth_org_slug

Argo CD

Argo CD config OIDC siedzi w ConfigMap argocd-cm:

data:
  url: https://argocd.twoj-host.tld
  oidc.config: |
    name: WolfieAuth
    issuer: https://auth.wolfieguard.com
    clientID: <z-panelu-wolfieauth>
    clientSecret: $oidc.wolfieauth.clientSecret  # z secret
    requestedScopes: ["openid", "profile", "email"]
    requestedIDTokenClaims:
      groups:
        essential: true    

W WolfieAuth: redirect URI = https://argocd.twoj-host.tld/auth/callback. Użyj JWT template żeby emitować groups: ["{{wolfieauth_role_slug}}"] żeby polityki RBAC Argo mogły matchować.

argocd-rbac-cm:

data:
  policy.csv: |
    g, admin, role:admin
    g, editor, role:readonly    

Proxmox VE 8+

Proxmox 8 dodał natywny OIDC. Datacenter → Permissions → Realms → Add → OpenID Connect.

Redirect URI do zarejestrowania w WolfieAuth: https://proxmox.twoj-host.tld:8006/. Proxmox auto-tworzy userów przy pierwszym logowaniu jako <email>@wolfieauth. Permissions przypisujesz w Datacenter → Permissions → Add → User Permission.

Gitea / Forgejo

Site Administration → Authentication Sources → Add → OAuth2 → OpenID Connect.

Redirect URI: https://gitea.twoj-host.tld/user/oauth2/WolfieAuth/callback.

Nextcloud

Zainstaluj appkę OpenID Connect Login, potem Settings → Administration → OpenID Connect Login:

Identifier:           WolfieAuth
Authorization URL:    https://auth.wolfieguard.com/auth
Token URL:            https://auth.wolfieguard.com/token
Userinfo URL:         https://auth.wolfieguard.com/me
Logout URL:           https://auth.wolfieguard.com/session/end
JWKS URL:             https://auth.wolfieguard.com/jwks
Client ID / Secret:   <z-panelu-wolfieauth>
Scopes:               openid email profile
Attribute mapping → uid: sub
                  → display name: name
                  → email: email

Redirect URI: https://nextcloud.twoj-host.tld/apps/oidc_login/oidc.

Apki bez natywnego OIDC — oauth2-proxy / Traefik forward-auth

Dla apek które wcale nie mówią OIDC (admin dashboardy, internal Kibana, statyczne dashboardy, legacy PHP panele), postaw oauth2-proxy albo Traefik forward-auth middleware między apką a światem.

oauth2-proxy (docker-compose snippet)

services:
  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:latest
    command:
      - --provider=oidc
      - --oidc-issuer-url=https://auth.wolfieguard.com
      - --client-id=<z-panelu-wolfieauth>
      - --client-secret=<z-panelu-wolfieauth>
      - --redirect-url=https://protected.twoj-host.tld/oauth2/callback
      - --upstream=http://twoja-internal-apka:8080
      - --cookie-secret=$(openssl rand -base64 32)
      - --email-domain=*
      - --pass-access-token=true
      - --set-xauthrequest=true
    ports: ["4180:4180"]

Teraz https://protected.twoj-host.tld jest gated przez WolfieAuth — żadnych patchów do upstream apki. Headery X-Auth-Request-User, X-Auth-Request-Email, X-Auth-Request-Groups docierają do twojej apki żeby zidentyfikowała usera.

Traefik forward-auth

http:
  middlewares:
    wolfieauth-sso:
      forwardAuth:
        address: "http://oauth2-proxy:4180/oauth2/auth"
        trustForwardHeader: true
        authResponseHeaders:
          - X-Auth-Request-User
          - X-Auth-Request-Email

Wpinasz w dowolny router: traefik.http.routers.kibana.middlewares=wolfieauth-sso@file.

Inne apki które działają tak samo

Wzorzec ten sam co wszystko powyżej — zarejestruj clienta, wklej cztery URL-e, opcjonalnie remapuj claim. Sample lista stacków potwierdzonych przeciwko endpointom OIDC WolfieAuth-a:

Troubleshooting

“redirect_uri_mismatch” — URI zarejestrowany w WolfieAuth nie matchuje byte-by-byte tego co wysyła apka. Trailing slashes, http vs https, i trailing /callback paths — wszystkie mają znaczenie. Skopiuj URL z network tab apki i wklej dosłownie.

“invalid_client” — client_secret nie matchuje. Rotuj przez /admin/clients/<id> → Rotate Secret, wklej nowy do apki, zapisz, retry.

“User has no role” / ląduje jako guest — twój role claim nie dociera do apki pod nazwą której oczekuje. Sprawdź docs apki czego oczekuje (Grafana chce role, Portainer czyta is_admin, Argo CD chce groups). Użyj JWT template na OidcClient żeby zmienić nazwę albo policzyć claim. Preview pod /admin/clients/<id>/jwt-template/preview pokazuje jak będzie wyglądał wyrenderowany token.

Nic się nie dzieje przy klik — sprawdź czy https://auth.wolfieguard.com/.well-known/openid-configuration resolve-uje się z wewnątrz sieci apki. Self-hosted apki w prywatnych sieciach czasami nie dochodzą do public IdP — otwórz egress dla auth.wolfieguard.com:443 najpierw.

Logout nie wylogowuje — apka wyczyściła swoje lokalne cookie ale SSO cookie pod auth.wolfieguard.com zostało żywe. Skonfiguruj “End-session” / “Logout URL” apki na https://auth.wolfieguard.com/session/end?id_token_hint=<id_token>&post_logout_redirect_uri=<url-twojej-apki> żeby RP-initiated logout odpalił.

Continue reading

• SSO & Sesje — co siedzi na drucie podczas OIDC tańca
• Admin — JWT templates, redirect URIs, rotacja sekretów
• Tryb reseller — gdy twoja downstream apka sama ma hostować sub-tenantów

Ostatnia aktualizacja: 2026-05-02