Auth0 Php

Auth0 PHP Web App Integration

Add login, logout, and user profile to a PHP web application using auth0/auth0-php.

---

Prerequisites

• PHP 8.2+ with extensions: mbstring, openssl, json
• Composer installed
• Auth0 Regular Web Application configured (not an API - must be an Application)
• If you don't have Auth0 set up yet, use the auth0-quickstart skill first

When NOT to Use

• PHP APIs with JWT Bearer validation - Use auth0-php-api for stateless API token validation
• Laravel applications - Use a dedicated Laravel integration with auth0/laravel-auth0
• Symfony applications - Use a dedicated Symfony integration with auth0/symfony
• Single Page Applications - Use auth0-react, auth0-vue, or auth0-angular for client-side auth
• Next.js applications - Use auth0-nextjs which handles both client and server
• Node.js web apps - Use auth0-express or auth0-fastify for session-based auth

---

Quick Start Workflow

1. Install SDK

composer require auth0/auth0-php vlucas/phpdotenv guzzlehttp/guzzle guzzlehttp/psr7

• auth0/auth0-php - The Auth0 SDK
• vlucas/phpdotenv - Load .env files into $_ENV
• guzzlehttp/guzzle + guzzlehttp/psr7 - PSR-18 HTTP client required by the SDK

2. Configure Environment

Create .env:

AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_client_secret
AUTH0_COOKIE_SECRET=your_generated_secret
AUTH0_REDIRECT_URI=http://localhost:3000/callback

AUTH0_DOMAIN is your Auth0 tenant domain (without https://). AUTH0_CLIENT_ID and AUTH0_CLIENT_SECRET come from your Auth0 Application settings. AUTH0_COOKIE_SECRET is used for encrypting session cookies - generate with openssl rand -hex 32.

3. Configure Auth0 Dashboard

In your Auth0 Application settings:

• Application Type: Regular Web Application
• Allowed Callback URLs: http://localhost:3000/callback
• Allowed Logout URLs: http://localhost:3000

4. Create Auth Configuration

Create auth0.php to initialize the SDK:

load();

$configuration = new SdkConfiguration(
    strategy: SdkConfiguration::STRATEGY_REGULAR,
    domain: $_ENV['AUTH0_DOMAIN'],
    clientId: $_ENV['AUTH0_CLIENT_ID'],
    clientSecret: $_ENV['AUTH0_CLIENT_SECRET'],
    cookieSecret: $_ENV['AUTH0_COOKIE_SECRET'],
    redirectUri: $_ENV['AUTH0_REDIRECT_URI'],
    scope: ['openid', 'profile', 'email'],
);

$auth0 = new Auth0($configuration);

Create one Auth0 instance and reuse it. Never hardcode credentials - always use environment variables.

How this works: The SDK encrypts session data (tokens, user profile) using AES-256-GCM with a key derived from cookieSecret via HKDF-SHA256. Session data is stored in an encrypted cookie by default - no server-side database required.

5. Create Index Page (Router)

Create index.php as a simple front controller. Create the routes/ directory first:

getCredentials();
?>

    
    
    Auth0 PHP App
    

    
        
            
                
                    user['picture'] ?? '') ?>" alt="avatar" class="avatar" />
                    
                        Hello, user['name'] ?? 'User') ?>!
                        user['email'] ?? '') ?>
                    
                
                
                    View Profile & Tokens
                    Logout
                
            
        
            
                Auth0 PHP Web App
                Session-based authentication with Auth0 SDK
                Login
            
        
    

8. Add Login Route

Create routes/login.php:

login());
exit;

login() returns a URL string pointing to Auth0's Universal Login page. You must redirect the user to it.

9. Add Callback Route

Create routes/callback.php:

getExchangeParameters()) {
    try {
        $auth0->exchange();
        header('Location: /');
        exit;
    } catch (\Exception $e) {
        error_log('Auth0 callback error: ' . $e->getMessage());
        http_response_code(400);
        echo "Authentication failed. Please try again.";
        exit;
    }
}

header('Location: /');
exit;

getExchangeParameters() checks if the callback contains authorization code parameters. exchange() exchanges the code for tokens and establishes the session. Always wrap in try/catch since the token exchange can fail (e.g. expired code, CSRF mismatch).

10. Add Profile Route (Protected)

Create routes/profile.php:

getCredentials();

if (null === $credentials) {
    header('Location: /login');
    exit;
}

$user = $credentials->user;
?>

    
    
    Profile - Auth0 PHP App
    

    
        
            ← Back to Home
            Logout
        

        
            
                " alt="avatar" class="avatar avatar-lg" />
                
                    
                    
                
            
        

        
            User Profile Claims
            
                 $value): ?>
                
                    
                    
                
                
            
        

        
            ID Token
            idToken ?? 'N/A') ?>
        

        
            Access Token
            accessToken ?? 'N/A') ?>
            
                
                    Expires
                    accessTokenExpiration ? date('Y-m-d H:i:s', $credentials->accessTokenExpiration) . ' (' . ($credentials->accessTokenExpired ? 'EXPIRED' : 'valid') . ')' : 'N/A' ?>
                
                
                    Scopes
                    accessTokenScope ?? [])) ?>
                
            
        

        refreshToken): ?>
        
            Refresh Token
            refreshToken) ?>
        
        
    

getCredentials() returns the user's session data, or null if not logged in. The profile page displays all user claims and tokens for verification during development.

11. Add Logout Route

Create routes/logout.php:

logout(returnUri: 'http://localhost:3000'));
exit;

logout() returns the Auth0 logout URL. Redirect the user to it. The returnUri is where Auth0 sends the user after logout - it must be listed in Allowed Logout URLs. In production, replace with your actual domain.

12. Test the App

php -S localhost:3000 index.php

Visit http://localhost:3000/login to start the login flow.

---

Common Mistakes

| Mistake | Fix | |---------|-----| | Hardcoding domain, clientId, or clientSecret in source | Always read from environment variables - never embed credentials in code | | Using an old auth0-PHP version login(?string $redirectUrl, ?array $params): string | Returns authorization URL string - redirect user to it | | exchange | $auth0->exchange(?string $redirectUri, ?string $code, ?string $state): bool | Exchanges authorization code for tokens, establishes session | | getCredentials | $auth0->getCredentials(): ?object | Returns current session credentials or null | | getExchangeParameters | $auth0->getExchangeParameters(): ?object | Checks if callback contains exchange parameters | | logout | $auth0->logout(?string $returnUri, ?array $params): string | Returns Auth0 logout URL string | | renew | $auth0->renew(?array $params): self | Refreshes expired access token (requires offline_access scope) | | clear | $auth0->clear(bool $transient = true): self` | Clears local session without Auth0 logout |

---

Credentials Object

After successful authentication, getCredentials() returns an object with:

$credentials = $auth0->getCredentials();

$credentials->user;                    // array - user profile claims
$credentials->idToken;                 // string - raw ID token
$credentials->accessToken;             // string - access token
$credentials->refreshToken;            // string|null - refresh token (requires offline_access)
$credentials->accessTokenExpiration;   // int - expiration timestamp
$credentials->accessTokenExpired;      // bool - whether token is expired
$credentials->accessTokenScope;        // array - granted scopes

User profile claims ($credentials->user):

• sub - unique user identifier
• name, nickname, picture
• email, email_verified
• given_name, family_name
• updated_at, locale

---

Related Skills

• auth0-php-api - For protecting PHP APIs with JWT Bearer token validation
• auth0-quickstart - Basic Auth0 setup and framework detection
• auth0-cli - Manage Auth0 resources from the terminal
• auth0-mfa - Add Multi-Factor Authentication

---

Quick Reference

SdkConfiguration for web apps:

$configuration = new SdkConfiguration(
    strategy: SdkConfiguration::STRATEGY_REGULAR,        // required
    domain: $_ENV['AUTH0_DOMAIN'],                        // required
    clientId: $_ENV['AUTH0_CLIENT_ID'],                   // required
    clientSecret: $_ENV['AUTH0_CLIENT_SECRET'],           // required
    cookieSecret: $_ENV['AUTH0_COOKIE_SECRET'],           // required
    redirectUri: $_ENV['AUTH0_REDIRECT_URI'],             // required
    scope: ['openid', 'profile', 'email'],               // recommended
);

Route protection pattern:

$credentials = $auth0->getCredentials();
if (null === $credentials) {
    header('Location: /login');
    exit;
}

Environment variables:

• AUTH0_DOMAIN - your Auth0 tenant domain (e.g. tenant.us.auth0.com)
• AUTH0_CLIENT_ID - your Application's client ID
• AUTH0_CLIENT_SECRET - your Application's client secret
• AUTH0_COOKIE_SECRET - encryption secret key (generate: openssl rand -hex 32)
• AUTH0_REDIRECT_URI - callback URL (e.g. http://localhost:3000/callback)

---

Detailed Documentation

• [Setup Guide](references/setup.md) - Automated setup scripts, environment configuration, Auth0 CLI usage
• [Integration Guide](references/integration.md) - Protected routes, calling APIs, session management, error handling
• [API Reference](references/api.md) - Complete Auth0 SDK API, configuration options, session storage, security

---

References

• auth0/auth0-php on Packagist
• auth0/auth0-PHP on GitHub
• Auth0 PHP Web App Quickstart
• PHP Documentation

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: auth0
• Source: auth0/agent-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.