Learn Authelia - Duo Push

#Introduction

In episode 10, WebAuthn fended off phishing with domain-bound credentials. But hardware authenticators aren't always practical for everyone, and TOTP authenticator apps require users to type codes. There's one second method that combines convenience and verification strength: push notification — a notification on your phone, one tap, authentication done.

Duo Push is the most popular implementation of this pattern. Authelia integrates Duo Security as one of its second methods, where the "is this really you" decision happens in the Duo Mobile app. In this episode you'll set up a Duo account, install the API key in the duo_api configuration, enroll user devices, and understand when push notifications win — and when you still need a fallback.

#Understanding the Duo Push Architecture

Duo shifts part of the authentication responsibility to Duo Security's cloud service. The flow:

1. The user logs in with a password (first factor) at the Authelia portal.
2. Authelia requests a challenge from the Duo API with the device ID stored in storage (episode 8).
3. Duo sends a push notification to the Duo Mobile app on the user's phone.
4. The user taps approve; Duo reports the result back to Authelia.

Note the dependency: Authelia doesn't handle the push itself, it asks the Duo service. This is Duo Push's main trade-off compared to TOTP or WebAuthn, which run completely independently — Duo requires an internet connection to Duo's infrastructure, and Authelia only stores device IDs, not the entire secret.

#Setting Up a Duo Account and API Key

The first step happens in the Duo dashboard, not in Authelia:

1. Create an account at the Duo service and log in to the admin dashboard.
2. Open the Applications menu, then Protect an Application.
3. Look for the Partner Auth API application type and select Protect.
4. Duo will display three values: the integration key (IKey), secret key (SKey), and API hostname.

The integration key acts like a client identifier, the secret key like a password, and the hostname is the API address Authelia will contact. All three must go into the configuration.

#duo_api Configuration

On the Authelia side, everything is managed through the duo_api section:

duo_api:
  hostname: "api-12345678.duosecurity.com"
  integration_key: "DIXYZ1234567890"
  secret_key: "duo-secret-key-secret"
  enable_self_enrollment: false

• hostname: the API hostname from the Duo dashboard.
• integration_key: the IKey Duo gave you.
• secret_key: the secret SKey; never store it as plaintext in a repository.
• enable_self_enrollment: if true, users can register their own devices through the Authelia portal.

When duo_api is configured, Authelia automatically shows Duo as an available second method at the portal.

#Second Methods in Duo Mobile

Once integrated, users don't always have to tap a notification. Duo Mobile provides several per-device authentication methods:

• Push: a notification that only needs a one-tap approve.
• Passcode: a 6-digit code generated by the Duo Mobile app, useful when push is blocked or the user is on a device that can't receive notifications.
• SMS: a code via SMS to a registered number, depending on the mobile carrier.
• Phone call: verification via a phone call for emergencies.

Which methods are active is controlled from the Duo dashboard and the user's device settings, not from Authelia. Authelia simply asks Duo to authenticate against already-enrolled devices.

#User Device Enrollment

To use Duo Push, every user must have a device registered at Duo. Two approaches:

• Self enrollment: enable enable_self_enrollment: true. Users choose Duo as their second method at the portal, then follow the Duo Mobile installation guide and register their own device.
• Admin enrollment: the admin sets up a device for the user from the Duo dashboard, and the device ID is recorded when Authelia communicates with Duo.

When a user logs in with the Duo method for the first time, Authelia stores the device ID in storage. This is the data Authelia uses on subsequent logins to trigger a push to the right device.

#Fallback Strategy: Don't Depend on a Single Service

Duo Push is convenient, but never make it the only second method. Three main reasons:

• Third-party dependency: if Duo has issues or the connection to its infrastructure is cut, Authelia can't verify anyone using only Duo.
• Lost device: a lost phone means the second method disappears instantly.
• Service availability: cloud services can suffer outages beyond your control.

A healthy policy: make Duo Push the primary method for its convenience, ensure every user also has TOTP registered, and store the Duo credentials (IKey and SKey) somewhere safe so you can disable the integration quickly when it has problems.

#Closing

Key points of this episode:

• Duo Push moves the second-factor verification to the Duo service via API; Authelia only stores device IDs.
• API keys from the Duo dashboard: integration key, secret key, and hostname, entered in the duo_api section.
• Duo Mobile offers push, passcode, SMS, and phone call as device methods.
• Enrollment can be done by users themselves or arranged by admins via the Duo dashboard.
• Duo is a third party: always provide a TOTP or WebAuthn fallback.

With Duo Push, Authelia's MFA phase is complete: TOTP for the practical, WebAuthn for the strict, Duo for the most convenient. Three second methods are ready for two_factor. In episode 12, you'll turn from the login side to the operational side: password reset, SMTP configuration for emails, and user and device management — the part that determines whether your Authelia is comfortable to manage long-term.