Jak krok za krokem nakonfigurovat OpenID Connect v Authelii

Pokud na serveru používáte více aplikací, může se správa samostatného účtu pro každou z nich rychle stát problémem. Nastavení systému jednotné přihlašování neboli SSO Umožňuje centralizovat ověřování a přístup k různým službám pomocí jediné identity.

Authelia může fungovat jako Poskytovatel OpenID ConnectTím se ověřuje identita uživatele a doručují se potřebné informace každé aplikaci prostřednictvím podepsaných tokenů. Kompatibilní aplikace, jako například Portainer, Nextcloud, Grafana a Jellyfin, se na toto ověření spoléhají a již přímo nespravují primární přihlašovací údaje.

V této příručce se podíváme, jak nakonfigurovat OpenID Connect v Authelii, vygenerovat potřebné klíče, zaregistrovat klienta a vyřešit nejčastější chyby.

Jakou roli hraje Authelia v OpenID Connect?

Integrace OpenID Connect zahrnuje primárně dvě strany. Authelia funguje jako Poskytovatel OpenID nebo poskytovatel identity, zatímco chráněná aplikace funguje jako spoléhající se strana nebo klient OIDC.

Když se uživatel pokusí přihlásit do aplikace, aplikace ho přesměruje na Authelia. Po ověření jeho přihlašovacích údajů a případně i druhého faktoru vrátí Authelia autorizační kód. Aplikace tento kód vymění za tokeny potřebné k identifikaci uživatele.

Authelia může hrát roli poskytovatele, ale Nefunguje jako OIDC klient.Lze jej tedy použít k přihlášení do jiných aplikací prostřednictvím Authelie, ale nikoli k přístupu k Authelii pomocí účtu Google, GitHub nebo jiného poskytovatele třetí strany.

Ačkoli je tato implementace nadále označována jako otevřená beta verzeAuthelia je certifikována podle standardu OpenID Connect. Před upgradem na hlavní verze je vhodné službu udržovat aktuální a zkontrolovat změny konfigurace.

Co potřebujete před nastavením OIDC

Před registrací klienta se ujistěte, že Authelia funguje správně a používá stabilní veřejnou IP adresu, nejlépe zabezpečenou pomocí HTTPS. Dále potřebujete aplikaci kompatibilní s OpenID Connect a přístup k jejímu ověřovacímu panelu.

Před úpravou souboru si vezměte na vědomí následující informace configuration.yml:

• Veřejná URL adresa Authelie: Například, https://auth.ejemplo.com.
• Veřejná URL adresa aplikace: Například, https://app.ejemplo.com.
• URI přesměrování: Musí to být přesně ten, který je uveden v žádosti.
• ID klienta: jedinečný identifikátor, který umožňuje identifikaci zákazníka.
• Tajemství klienta: tajemství sdílené mezi Authelií a aplikací.
• Požadované rozsahy: Určují, jaké informace bude aplikace obdržovat.

URI pro přesměrování je obzvláště důležité, protože rozlišuje mezi velkými a malými písmenyProtokol, doména, port, cesta a případná koncová lomítka musí odpovídat hodnotě používané aplikací.

Pokud stále potřebujete zabezpečit externí přístup, můžete se podívat, jak Ochrana aplikace pomocí Authelia před pokračováním v integraci OIDC.

Jak vygenerovat tajný klíč HMAC a klíč JWKS

Poskytovatel OIDC potřebuje dva různé kryptografické prvky. Prvním je Tajný klíč HMACkterý musí být náhodný řetězec o délce alespoň 64 znaků. Můžete ho vygenerovat pomocí OpenSSL:

openssl rand -hex 64

Druhým prvkem je soukromý klíč obsažený v sadě JWKS. Authelia vyžaduje alespoň jeden Soukromý klíč RSA kompatibilní s RS256 a alespoň 2048 bitů. Můžete jej vytvořit tímto příkazem:

openssl genpkey -algorithm RSA -out oidc-private.pem -pkeyopt rsa_keygen_bits:2048
chmod 600 oidc-private.pem

Základní blok dodavatele bude mít strukturu podobnou této:

identity_providers:
  oidc:
    hmac_secret: 'REEMPLAZA_ESTO_POR_UN_SECRETO_ALEATORIO'

    jwks:
      - algorithm: 'RS256'
        use: 'sig'
        key: |
          -----BEGIN PRIVATE KEY-----
          CONTENIDO_DE_LA_CLAVE_PRIVADA
          -----END PRIVATE KEY-----

Klíč musí být soukromé a kódované ve formátu PEMNevkládejte pouze veřejný klíč, protože Authelia potřebuje podepsat vydané tokeny. Řetězec certifikátů také není vyžadován, pokud to klientská aplikace výslovně nenařizuje.

V produkčním prostředí ukládejte tyto hodnoty pomocí tajných souborů nebo chráněných proměnných. Nenahrávejte tajný nebo soukromý klíč HMAC do Gitu, i když je repozitář soukromý.

Jak vygenerovat identifikátor a tajný klíč klienta

Každá aplikace potřebuje svůj vlastní client_id y client_secretNepoužívejte stejný tajný klíč opakovaně napříč různými službami, protože únik by vám umožnil vydávat se za všechny klienty, kteří jej sdílejí.

Pokud Authelia běží v kontejneru s názvem autheliaNáhodný tajný kód a jeho hash PBKDF2 můžete vygenerovat pomocí:

docker exec -it authelia authelia crypto hash generate pbkdf2 --random --random.length 72

Příkaz zobrazí dvě hodnoty, které slouží různým funkcím:

• Původní tajemství: Musí být zadán v nastavení aplikace.
• Haš PBKDF2: by mělo být uloženo jako client_secret v Authelii.

Nezadávejte hash do aplikace. Potřebuje původní tajemství, netransformované prokázat vaši totožnost při kontaktování koncového bodu tokenu.

Jak zaregistrovat aplikaci jako OIDC klienta

Zákazníci jsou přidáváni do identity_providers.oidc.clientsTato generická konfigurace používá tok autorizačního kódu a vyžaduje dvoufaktorové ověřování:

identity_providers:
  oidc:
    hmac_secret: 'SECRETO_HMAC'

    jwks:
      - algorithm: 'RS256'
        use: 'sig'
        key: |
          -----BEGIN PRIVATE KEY-----
          CONTENIDO_DE_LA_CLAVE_PRIVADA
          -----END PRIVATE KEY-----

    clients:
      - client_id: 'mi-aplicacion'
        client_name: 'Mi aplicación'
        client_secret: '$pbkdf2-sha512$...'
        public: false
        authorization_policy: 'two_factor'
        redirect_uris:
          - 'https://app.ejemplo.com/oauth/callback'
        scopes:
          - 'openid'
          - 'profile'
          - 'email'
          - 'groups'
        grant_types:
          - 'authorization_code'
        response_types:
          - 'code'
        consent_mode: 'explicit'

Nahraďte vzorový URI identifikátorem URI poskytnutým aplikací. Některé používají trasu zpětného volání, zatímco jiné očekávají pouze kořenovou URL. Tuto adresu si nevymýšlejte ani neupravujte.Zkopírujte přesně tak, jak je uvedeno v dokumentaci nebo v zákaznickém panelu.

Hodnota public: false To se týká aplikací, které dokáží uchovávat tajemství v tajnosti. Jednostránkové aplikace, některé konzolové nástroje a další klienti, kteří nemohou chránit přihlašovací údaje, by měli být nakonfigurováni jako veřejné a používat PKCE.

Jak zadat data Authelie do aplikace

Mnoho aplikací umožňuje konfigurovat OIDC pouhým zadáním URL odesílatele nebo dokumentu pro zjišťování:

• Vydavatel: https://auth.ejemplo.com.
• URL adresa pro vyhledávání: https://auth.ejemplo.com/.well-known/openid-configuration.
• ID klienta: identifikátor registrovaný v Authelii.
• Tajemství klienta: původní tajemství, nikdy jeho hash.
• URI přesměrování: stejná adresa registrovaná v Authelii.
• Rozsahy: normálně openid profile email groups.

Pokud aplikace nepodporuje automatické vyhledávání, můžete si koncové body vyžádat samostatně. Typické adresy Authelia jsou:

• Autorizační URL: https://auth.ejemplo.com/api/oidc/authorization.
• URL tokenu: https://auth.ejemplo.com/api/oidc/token.
• URL adresa s informacemi o uživateli: https://auth.ejemplo.com/api/oidc/userinfo.

Příklad konfigurace s Portainerem

V Portaineru musíte zadat Nastavení > OvěřováníVyberte OAuth a zvolte vlastního poskytovatele. Oficiální konfigurace používá jako adresu pro přesměrování kořenovou URL adresu Portaineru:

• Autorizační URL: https://auth.ejemplo.com/api/oidc/authorization.
• URL přístupového tokenu: https://auth.ejemplo.com/api/oidc/token.
• URL zdroje: https://auth.ejemplo.com/api/oidc/userinfo.
• URL adresa pro přesměrování: https://portainer.ejemplo.com.
• Identifikátor uživatele: preferred_username.
• Rozsahy: openid profile groups email.
• Styl autorizace: In Params.

Pokud povolíte automatické vytváření uživatelů, Portainer bude schopen vygenerovat lokální účet, když se někdo poprvé přihlásí pomocí Authelia. Zkontrolujte, jaká oprávnění daný účet následně obdrží, protože Ověření uživatele neznamená, že se z něj stává správce..

Jaké rozsahy a nároky byste měli povolit

Rozsahy určují, jaké informace může aplikace požadovat. Nejlepší je udělit pouze ty nezbytné:

• openid: Aktivuje OpenID Connect a je povinné.
• profil: Poskytuje základní atributy, jako je jméno a uživatelské jméno.
• e-mail: umožňuje zákazníkovi získat e-mailovou adresu.
• skupiny: Poskytuje skupiny a usnadňuje používání oprávnění v rámci aplikace.

Konkrétní poskytnutá data se nazývají nárokyNapříklad Portainer může použít preferred_username identifikovat uživatele a nárok groups přiřadit oprávnění.

Nepřidávejte osobní údaje přímo do ID tokenu, pokud je klient nezbytně nepotřebuje. Tyto tokeny jsou obvykle podepsané, ale nemusí být nutně šifrovanéJeho obsah proto může dekódovat kdokoli, kdo k němu má přístup.

Jak omezit, kdo může používat klienta OIDC

Parametr authorization_policy Umožňuje vám vyžadovat jeden nebo dva faktory. Můžete si také vytvořit vlastní zásady, které omezí klienta na konkrétní uživatele nebo skupiny:

identity_providers:
  oidc:
    authorization_policies:
      administradores:
        default_policy: 'deny'
        rules:
          - policy: 'two_factor'
            subject: 'group:admins'

    clients:
      - client_id: 'portainer'
        authorization_policy: 'administradores'

S touto konfigurací pouze členové skupiny admins Budou schopni dokončit autorizaci a musí projít druhým krokem.

Tyto zásady OIDC se liší od obecných pravidel access_controlToto se vztahuje pouze na autorizační požadavky OpenID Connect. Chcete-li ovládat domény, trasy a sítě pomocí Forward Auth, podívejte se, jak na to. Konfigurace pravidel přístupu v Authelii.

Kdykoli je to možné, používejte také ovládací prvky oprávnění aplikací. Authelia může rozhodnout, kdo získá autorizaci, ale klient to musí určit sám. jaké operace může každý uživatel provádět jakmile jste uvnitř.

Jak nakonfigurovat souhlas a PKCE

Parametr consent_mode Řídí, zda Authelia zobrazuje uživateli oprávnění požadovaná aplikací. Výchozí hodnota je auto, který aplikuje příslušné chování podle zbytku konfigurace.

Nejdůležitější možnosti jsou:

• explicitní: Během procesu autorizace požaduje souhlas uživatele.
• předkonfigurované: Umožňuje, aby byl udělený souhlas zapamatován po určitou dobu.
• auto: automaticky vybírá z kompatibilních chování.
• implicitní: Uděluje souhlas bez ptání, ale nedoporučuje se to.

Nepoužívejte implicit jen aby se eliminovala další obrazovka. Pokud se chcete vyhnout opakovaným otázkám, je bezpečnější použít pre-configured spolu s omezenou dobou trvání.

PKCE přidává ochranu do autorizačního procesu a zabraňuje zneužití zachyceného kódu. Pokud klient tuto funkci podporuje, můžete ji aktivovat následujícím způsobem:

require_pkce: true
pkce_challenge_method: 'S256'

Metoda S256 je výhodnější než plainNěkteré aplikace však stále nepodporují PKCE. Například aktuálně zdokumentovaná konfigurace pro Portainer jej ponechává vypnutý.

Kdy upravit dobu platnosti tokenu

Authelia umožňuje konfigurovat dobu platnosti autorizačního kódu, přístupový token, ID token a obnovovací token. Toto se doporučuje ve většině instalací. zachovat výchozí hodnoty a upravovat je pouze v případě konkrétní potřeby.

Pokud citlivá aplikace potřebuje kratší relace, vytvořte v globální sekci vlastní nastavení doby trvání. lifespans.custom a odkazuje na jejich jméno od klienta lifespanNezaměňujte dobu platnosti tokenů OIDC s obecným souborem cookie relace Authelia, protože se jedná o různé ovládací prvky.

Jak ověřit konfiguraci před restartem

Chyba odsazení v YAML může zabránit spuštění Authelie. Před restartem služby ověřte soubor pomocí:

authelia config validate --config /config/configuration.yml

Pokud je kontejner již spuštěn a je volána autheliaMůžete spustit:

docker exec authelia authelia config validate --config /config/configuration.yml

Po provedení změn zkontrolujte protokoly při pokusu o přihlášení:

docker compose logs -f authelia

Protokoly vám umožňují kontrolovat client_id, přijatý identifikátor URI, použitá zásada a přesný důvod odmítnutí požadavku.

Časté chyby při konfiguraci OpenID Connect v Authelii

Aplikace zobrazuje chybu redirect_uri_mismatch.

URI odeslaný aplikací se přesně neshoduje s žádným záznamem v redirect_urisZkontrolujte protokol, doménu, port, cestu, velká písmena a koncové lomítko.

Authelia vrací invalid_client nebo chybu 401.

Ověřte, zda má aplikace původní tajný klíč a zda Authelia ukládá jeho hash. Měli byste také zkontrolovat metodu ověřování koncového bodu tokenu, protože někteří klienti používají client_secret_basic a další client_secret_post.

Konfigurace ukazuje, že chybí klíč RS256.

Authelia vyžaduje alespoň jeden soukromý klíč RSA nakonfigurovaný pro RS256. Potvrďte prosím, že jste vložili celý soukromý blok a že klíč má délku alespoň 2048 bitů.

Uživatel se ověřuje, ale obdrží chybu access_denied.

Autorizační zásady neodpovídají zdrojovému uživateli, skupině nebo síti. Nezapomeňte, že pravidla se vyhodnocují v pořadí a že výchozí zásada... deny zablokuje jakýkoli případ, který není výslovně povolen.

Aplikace nepřijímá e-mail ani skupiny

Ověřte, zda má klient povolené obory. email y groupsže si je aplikace vyžádá a že uživatel má tyto atributy definované v backendu identity.

Zdá se, že tokeny vypršely nebo ještě nejsou platné.

Zkontrolujte čas na serveru Authelia a na počítači, na kterém běží aplikace. Dočasný problém se synchronizací může způsobit odmítnutí polí platnosti tokenu.

Dochází k přesměrovací smyčce

Ověřte, zda veřejná URL adresa Authelie používá HTTPS a zda proxy správně doručuje hlavičky protokolu a hostitele. Pokud je problém na této úrovni, zkontrolujte, jak… propojení Authelie s Nginx Proxy Managerem.

Veřejný zákazník nemůže dokončit autorizaci.

Veřejní zákazníci musí používat public: truePole tajného prvku nechte prázdné a obvykle použijte PKCE s metodou S256. Nekonfigurujte jako důvěrnou aplikaci, která nedokáže chránit své přihlašovací údaje.

Konfigurace OpenID Connect v Authelii umožňuje centralizovat přihlašování bez sdílení primárních přihlašovacích údajů s každou aplikací. Klíčem je správně vygenerovat tajný klíč HMAC a soukromý klíč JWKS, zaregistrovat přesný URI pro přesměrování a poskytnout každému klientovi pouze ty rozsahy, které potřebuje.

Jakmile je konfigurace ověřena, můžete přidat nové aplikace pouhým opakováním registrace klienta a zachováním jednotný systém identityucelené zásady a možnost vyžadovat vícefaktorové ověřování u nejcitlivějších služeb.