Auth SSO

2 min read

How login works

sequenceDiagram
    participant B as Browser
    participant N as App Nginx vhost
    participant A as Authelia :51091
    participant P as Protected app
    B->>N: GET https://app.loca.zone/
    N->>A: auth_request /api/authz/auth-request
    A->>A: Check authelia_session and access_control
    alt no valid session
        A-->>N: 401 plus portal Location
        N-->>B: 302 to auth.loca.zone
        B->>A: Submit username and password
        A-->>B: Set loca.zone session cookie
        B->>N: Retry original URL with cookie
    end
    A-->>N: 2xx plus identity headers
    N->>P: Forward request and trusted identity headers
    P-->>B: App response

Components

  • browser:
    • stores the cookie named authelia_session
    • sends it to eligible loca.zone HTTPS hosts
  • protected app Nginx vhost:
    • server scope: include snippets/authelia-location.conf;
    • protected location: include snippets/authelia-authrequest.conf;
    • does not send the original response body to Authelia
    • sends original method and URL as authorization context
  • Authelia:
    • listens inside the container on 9091
    • is published only on host loopback 127.0.0.1:51091
    • checks the session and the matching access_control rule
    • returns authorization metadata, not the protected app itself
  • protected app:
    • receives Remote-User, Remote-Groups, Remote-Name, and Remote-Email only after a successful authorization response

Anonymous request

  • request path:
    • browser requests a protected host
    • Nginx runs the internal auth_request
    • Authelia finds no valid session and returns 401 with a sign-in location
    • Nginx converts that result to a browser 302
    • browser opens https://auth.loca.zone
  • loop prevention:
    • auth.loca.zone has an explicit bypass access rule
    • protecting the portal with its own one_factor request would create a redirect loop

Successful sign-in

  • portal action:
    • file authentication checks /config/users_database.yml
    • current protected-host policy is one_factor
    • Authelia creates the authelia_session cookie for domain loca.zone
  • return action:
    • browser retries the original URL with the cookie
    • Authelia returns success to Nginx
    • Nginx forwards the request and identity headers to the app
  • session duration:
    • checkbox unticked: expiration and inactivity govern the session
    • checkbox ticked: remember_me governs cookie lifetime and the inactivity check is bypassed
    • exact values and consequences: Sessions and remember me

Two mechanisms that are easy to confuse

  • Nginx auth_request:
    • guards a web route before the app receives the request
    • uses the rules listed on Protected apps
  • OIDC:
    • lets an application perform its own Authelia-backed login
    • uses registered redirect URIs and tokens
    • current registrations: OIDC clients
  • they are not interchangeable:
    • adding an access rule does not register an OIDC client
    • registering an OIDC client does not make an Nginx location protected

References

  • Authelia Nginx integration:
  • local executable configuration:
    • /etc/nginx/snippets/authelia-location.conf
    • /etc/nginx/snippets/authelia-authrequest.conf