Sådan konfigurerer du OpenID Connect i Authelia trin for trin

Hvis du bruger flere applikationer på din server, kan det hurtigt blive et problem at administrere en separat konto for hver enkelt. Opsætning af et system af enkeltlogon eller SSO Det muliggør centralisering af godkendelse og adgang til forskellige tjenester ved hjælp af en enkelt identitet.

Authelia kan fungere som OpenID Connect-udbyderDette verificerer brugeridentitet og leverer de nødvendige oplysninger til hver applikation via signerede tokens. Kompatible applikationer, såsom Portainer, Nextcloud, Grafana og Jellyfin, er afhængige af denne validering og administrerer ikke længere direkte primære legitimationsoplysninger.

I denne guide vil vi se, hvordan man konfigurerer OpenID Connect i Authelia, genererer de nødvendige nøgler, registrerer en klient og løser de mest almindelige fejl.

Hvilken rolle spiller Authelia i OpenID Connect?

En OpenID Connect-integration involverer primært to parter. Authelia fungerer som OpenID-udbyder eller identitetsudbyder, mens den beskyttede applikation fungerer som en Relying Party- eller OIDC-klient.

Når en bruger forsøger at logge ind på en applikation, omdirigerer applikationen dem til Authelia. Efter at have valideret deres legitimationsoplysninger og, hvor det er relevant, den anden faktor, returnerer Authelia en godkendelseskode. Applikationen udveksler denne kode med de tokens, der er nødvendige for at identificere brugeren.

Authelia kan spille rollen som forsørger, men Den fungerer ikke som en OIDC-klient.Derfor kan den bruges til at logge ind på andre applikationer via Authelia, men ikke til at få adgang til Authelia ved hjælp af en Google-, GitHub- eller anden tredjepartsudbyderkonto.

Selvom denne implementering fortsat identificeres som en åben betaversionAuthelia er certificeret til at overholde OpenID Connect-standarden. Det anbefales at holde tjenesten opdateret og gennemgå konfigurationsændringer, før du opgraderer til større versioner.

Hvad du skal bruge, før du konfigurerer OIDC

Før du registrerer en klient, skal du sørge for, at Authelia fungerer korrekt med en stabil offentlig IP-adresse, helst sikret med HTTPS. Du skal også bruge en OpenID Connect-kompatibel applikation og adgang til dens godkendelsesdashboard.

Bemærk følgende oplysninger, før du ændrer filen configuration.yml:

• Authelias offentlige URL: For eksempel, https://auth.ejemplo.com.
• Offentlig URL til applikationen: For eksempel, https://app.ejemplo.com.
• Omdirigerings-URI: Det skal være den, der er præcist angivet i applikationen.
• Klient-ID: unik identifikator, der gør det muligt at genkende kunden.
• Klienthemmelighed: en hemmelighed, der deles mellem Authelia og appen.
• Nødvendige omfang: De bestemmer, hvilke oplysninger ansøgningen skal modtage.

Omdirigerings-URI'en er særligt vigtig fordi skelner mellem store og små bogstaverProtokollen, domænet, porten, stien og eventuelle efterfølgende skråstreger skal stemme overens med den værdi, der bruges af applikationen.

Hvis du stadig har brug for at sikre ekstern adgang, kan du tjekke hvordan Beskyt en applikation med Authelia før du fortsætter med OIDC-integrationen.

Sådan genererer du HMAC-hemmeligheden og JWKS-nøglen

OIDC-udbyderen har brug for to forskellige kryptografiske elementer. Det første er HMAC-hemmelighedsom skal være en tilfældig streng på mindst 64 tegn. Du kan generere den med OpenSSL:

openssl rand -hex 64

Det andet element er en privat nøgle inkluderet i JWKS-sættet. Authelia kræver mindst én RSA privat nøgle kompatibel med RS256 og mindst 2048 bit. Du kan oprette den med denne kommando:

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

Den grundlæggende leverandørblok vil have en struktur, der ligner denne:

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-----

Nøglen skal være privat og være kodet i PEM-formatIndsæt ikke kun den offentlige nøgle, da Authelia skal signere de udstedte tokens. En certifikatkæde er heller ikke påkrævet, medmindre klientapplikationen eksplicit kræver det.

I et produktionsmiljø skal disse værdier gemmes ved hjælp af hemmelige filer eller beskyttede variabler. Undgå at uploade HMAC-hemmeligheden eller den private nøgle til Git, selvom arkivet er privat.

Sådan genererer du klient-id'et og hemmeligheden

Hver applikation har brug for sin egen client_id y client_secretGenbrug ikke den samme hemmelighed på tværs af flere tjenester, da en lækage vil give dig mulighed for at udgive dig for at være alle de klienter, der deler den.

Hvis Authelia kører i en container kaldet autheliaDu kan generere en tilfældig hemmelighed og dens PBKDF2-hash med:

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

Kommandoen viser to værdier, der tjener forskellige funktioner:

• Oprindelig hemmelighed: Det skal indtastes i applikationsindstillingerne.
• Hash PBKDF2: skal gemmes som client_secret i Authelia.

Indtast ikke hashen i applikationen. Den skal bruge oprindelig hemmelighed, utransformeret for at bevise din identitet, når du kontakter token-slutpunktet.

Sådan registrerer du en applikation som en OIDC-klient

Kunder tilføjes indenfor identity_providers.oidc.clientsDenne generiske konfiguration bruger godkendelseskodeflowet og kræver tofaktorgodkendelse:

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'

Erstat eksempel-URI'en med den, der leveres af applikationen. Nogle bruger en callback-rute, mens andre kun forventer rod-URL'en. Opfind eller tilpas ikke denne adresse: kopier præcis som angivet i dokumentationen eller kundepanelet.

Værdien public: false Dette gælder for applikationer, der kan holde hemmeligheder fortrolige. Enkeltsidede applikationer, nogle konsolværktøjer og andre klienter, der ikke kan beskytte legitimationsoplysninger, bør konfigureres som offentlige og bruge PKCE.

Sådan indtaster du Authelias data i appen

Mange applikationer giver dig mulighed for at konfigurere OIDC ved blot at indtaste afsenderens URL eller registreringsdokumentet:

• Udsteder: https://auth.ejemplo.com.
• Opdagelses-URL: https://auth.ejemplo.com/.well-known/openid-configuration.
• Klient-ID: den identifikator, der er registreret i Authelia.
• Klienthemmelighed: den oprindelige hemmelighed, aldrig dens hash.
• Omdirigerings-URI: samme adresse registreret i Authelia.
• Omfang: normalt openid profile email groups.

Hvis applikationen ikke understøtter automatisk registrering, kan du anmode om slutpunkterne separat. Typiske Authelia-adresser er:

• Autorisations-URL: https://auth.ejemplo.com/api/oidc/authorization.
• Token-URL: https://auth.ejemplo.com/api/oidc/token.
• Brugerinfo-URL: https://auth.ejemplo.com/api/oidc/userinfo.

Eksempelkonfiguration med Portainer

I Portainer skal du indtaste Indstillinger > GodkendelseVælg OAuth, og vælg en brugerdefineret udbyder. Den officielle konfiguration bruger Portainer-rod-URL'en som omdirigeringsadresse:

• Autorisations-URL: https://auth.ejemplo.com/api/oidc/authorization.
• URL til adgangstoken: https://auth.ejemplo.com/api/oidc/token.
• Ressource-URL: https://auth.ejemplo.com/api/oidc/userinfo.
• Omdirigerings-URL: https://portainer.ejemplo.com.
• Brugeridentifikator: preferred_username.
• Omfang: openid profile groups email.
• Godkendelsesstil: In Params.

Hvis du aktiverer automatisk brugeroprettelse, vil Portainer kunne generere en lokal konto, når nogen logger ind for første gang ved hjælp af Authelia. Gennemgå hvilke tilladelser den konto får bagefter, fordi Godkendelse af en bruger indebærer ikke at gøre vedkommende til administrator.

Hvilke omfang og krav bør du tillade

Omfang bestemmer, hvilke oplysninger en ansøgning kan anmode om. Det er bedst kun at imødekomme de nødvendige:

• åben-id: Det aktiverer OpenID Connect og er obligatorisk.
• profil: Den indeholder grundlæggende attributter såsom navn og brugernavn.
• e-mail: giver kunden mulighed for at modtage e-mailadressen.
• grupper: Den leverer grupperne og gør det nemt at anvende tilladelser i applikationen.

De specifikke data, der gives, kaldes påstandeFor eksempel kan Portainer bruge preferred_username at identificere brugeren og kravet groups at tildele tilladelser.

Tilføj ikke personlige oplysninger direkte til ID-tokenet, medmindre klienten absolut har brug for det. Disse tokens er typisk signerede, men ikke nødvendigvis krypteretDerfor kan dens indhold afkodes af enhver, der har adgang til det.

Sådan begrænser du, hvem der kan bruge OIDC-klienten

Parameteren authorization_policy Det giver dig mulighed for at kræve en eller to faktorer. Du kan også oprette en brugerdefineret politik for at begrænse klienten til bestemte brugere eller grupper:

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

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

Med denne konfiguration er det kun medlemmerne af gruppen admins De vil være i stand til at fuldføre godkendelsen og skal bestå den anden faktor.

Disse OIDC-politikker er forskellige fra de generelle regler for access_controlDisse gælder kun for OpenID Connect-godkendelsesanmodninger. Se hvordan du kan kontrollere domæner, ruter og netværk ved hjælp af Forward Auth. Konfigurer adgangsregler i Authelia.

Brug også applikationstilladelseskontroller, når det er muligt. Authelia kan bestemme, hvem der får autorisation, men klienten skal selv bestemme, hvilke handlinger hver bruger kan udføre en gang indenfor.

Sådan konfigurerer du samtykke og PKCE

Parameteren consent_mode Styrer, om Authelia viser brugeren de tilladelser, som applikationen anmoder om. Standardværdien er auto, som anvender den passende adfærd i henhold til resten af ​​konfigurationen.

De vigtigste muligheder er:

• eksplicit: Den anmoder om brugerens samtykke under godkendelsesprocessen.
• forudkonfigureret: Det gør det muligt at huske det givne samtykke i en periode.
• bil: vælger automatisk fra kompatible adfærdsmønstre.
• implicit: Den giver samtykke uden at spørge, men det frarådes.

Må ikke anvendes implicit bare for at fjerne en ekstra skærm. Hvis du vil undgå gentagne spørgsmål, er det sikrere at bruge pre-configured sammen med en begrænset varighed.

PKCE tilføjer beskyttelse til autorisationsflowet og forhindrer udnyttelse af opsnappet kode. Når klienten understøtter det, kan du aktivere det på følgende måde:

require_pkce: true
pkce_challenge_method: 'S256'

Metoden S256 er at foretrække frem for plainNogle applikationer understøtter dog stadig ikke PKCE. For eksempel holder den aktuelt dokumenterede konfiguration for Portainer den deaktiveret.

Hvornår skal tokenets varighed ændres

Authelia giver dig mulighed for at konfigurere godkendelseskodens varighed, adgangstoken, ID-token og opdateringstoken. Dette anbefales i de fleste installationer. behold standardværdier og kun ændre dem, når der er et specifikt behov.

Hvis en følsom applikation har brug for kortere sessioner, skal du oprette en brugerdefineret varighedsindstilling i den globale sektion. lifespans.custom og refererer til deres navn fra klienten ved lifespanForveksl ikke varigheden af ​​OIDC-tokens med den generelle Authelia-sessionscookie, da de er forskellige kontroller.

Sådan validerer du konfigurationen før genstart

En indrykningsfejl i YAML kan forhindre Authelia i at starte. Før du genstarter tjenesten, skal du validere filen med:

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

Hvis containeren allerede kører og kaldes autheliaDu kan køre:

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

Når du har implementeret ændringerne, skal du kontrollere loggene, mens du prøver at logge ind:

docker compose logs -f authelia

Loggene giver dig mulighed for at kontrollere client_id, den modtagne URI, den anvendte politik og den nøjagtige årsag til, at en anmodning er blevet afvist.

Almindelige fejl ved konfiguration af OpenID Connect i Authelia

Applikationen viser redirect_uri_mismatch

Den URI, der sendes af applikationen, matcher ikke præcist nogen af ​​posterne i redirect_urisKontroller protokol, domæne, port, sti, store bogstaver og det efterfølgende skråstreg.

Authelia returnerer invalid_client eller en 401-fejl

Bekræft, at applikationen har den originale hemmelighed, og at Authelia gemmer sin hash. Du bør også kontrollere token-slutpunktets godkendelsesmetoder, som nogle klienter bruger. client_secret_basic og andre client_secret_post.

Konfigurationen angiver, at der mangler en RS256-nøgle.

Authelia kræver mindst én RSA privatnøgle konfigureret til RS256. Bekræft venligst, at du har indsat hele den private blok, og at nøglen er mindst 2048 bit lang.

Brugeren godkender, men modtager en access_denied-fejl

Autorisationspolitikken matcher ikke kildebrugeren, -gruppen eller -netværket. Husk, at regler evalueres i rækkefølge, og at en standardpolitik... deny vil blokere enhver sag, der ikke udtrykkeligt er tilladt.

Applikationen modtager ikke e-mailen eller grupperne

Bekræft, at klienten har aktiveret scopes. email y groupsat applikationen anmoder om dem, og at brugeren har disse attributter defineret i identitets-backend'en.

Tokenerne ser ud til at være udløbne eller endnu ikke gyldige

Kontroller tiden på Authelia-serveren og den computer, hvor applikationen kører. Et midlertidigt synkroniseringsproblem kan medføre, at tokenets gyldighedsfelter afvises.

Der opstår en omdirigeringsløkke

Bekræft, at Authelias offentlige URL bruger HTTPS, og at proxyen leverer protokollen og værtsheaderne korrekt. Hvis problemet er på dette lag, skal du gennemgå, hvordan Forbind Authelia med Nginx Proxy Manager.

Den offentlige kunde kan ikke fuldføre godkendelsen

Offentlige kunder skal bruge public: trueLad feltet "hemmelighed" stå tomt, og brug normalt PKCE med S256-metoden. Konfigurer ikke et program som fortroligt, hvis det ikke kan beskytte sine legitimationsoplysninger.

Konfiguration af OpenID Connect i Authelia giver dig mulighed for at centralisere login uden at dele primære legitimationsoplysninger med hver applikation. Nøglen er at generere HMAC-hemmeligheden og JWKS-privatnøglen korrekt, registrere en præcis omdirigerings-URI og kun give hver klient de scopes, den har brug for.

Når konfigurationen er valideret, kan du tilføje nye applikationer ved blot at gentage klientregistreringen og holde et enkelt identitetssystemsammenhængende politikker og muligheden for at kræve multifaktorgodkendelse på de mest følsomme tjenester.