Duo Universal PHP SDK

Duo Universal PHP is the official SDK for integrating Duo’s Universal Prompt into PHP web applications. It implements the OIDC redirect flow that Duo uses for second-factor authentication: your application redirects the user to Duo, the user completes 2FA, and Duo returns an authorization code your application exchanges for a verified result.

The SDK is a thin Client class that handles the security-critical details for you — generating and validating state, building the signed request JWT, performing the health check, constructing the authorization URL, and exchanging the returned code for a 2FA result token. It pins Duo’s CA certificate and signs requests with firebase/php-jwt, so integrators focus on wiring the redirect into their login flow rather than the OIDC mechanics.

What You Get

• A Client that implements the full Duo Universal Prompt OIDC redirect flow
• generateState() and state validation to protect against CSRF/replay
• createAuthUrl() to build the signed redirect URL to Duo
• exchangeAuthorizationCodeFor2FAResult() to verify the returned code and retrieve the result
• healthCheck() plus CA-certificate pinning for the connection to Duo

Common Use Cases

• Adding Duo second-factor authentication to a custom PHP login flow
• Layering MFA onto an existing primary authentication mechanism
• Enforcing Duo verification before granting access to sensitive PHP application areas

Under The Hood

Architecture — The SDK is essentially one class, Duo\DuoUniversal\Client in src/Client.php (~390 lines), plus a DuoException and a bundled ca_certs.pem. The public flow is four methods: generateState() (random anti-forgery state), healthCheck() (verifies connectivity/credentials), createAuthUrl($username, $state) (builds the signed redirect URL by creating a request JWT), and exchangeAuthorizationCodeFor2FAResult($duoCode, $username, $nonce) (posts the code to Duo’s token endpoint and validates the returned result JWT). Private helpers handle JWT payload creation, secret padding, and the curl-based HTTPS call with CA pinning.

Tech Stack — PHP >=7.4, requiring ext-curl and ext-json, and depending on firebase/php-jwt (^6.0 || ^7.0) for signing outbound requests and verifying Duo’s response tokens. HTTPS calls go through curl with the pinned certificate bundle.

Code Quality — The tests/ directory contains ClientTest and a dedicated CAPinningTest, the latter reflecting the SDK’s emphasis on connection security. Error conditions are surfaced through a single DuoException, and getExceptionFromResult() maps Duo error responses into meaningful messages.

API Design — The four-method flow maps directly onto the OIDC redirect steps, so a typical integration is short and hard to get wrong: generate state, redirect via the auth URL, then exchange the code on the callback. Security-sensitive concerns (state, JWT signing, cert pinning) are handled internally rather than left to the caller.