Auth0 Integration

Relevant source files

The following files were used as context for generating this wiki page:

• security/auth0_integration.py
• api/v1/auth0_endpoints.py
• AUTH0_FASTAPI_INTEGRATION_GUIDE.md
• security/jwt_auth.py
• AUTH0_INTEGRATION_GUIDE.md
• UNICORN_QUICK_START_CHECKLIST.md

The DevSkyy platform integrates Auth0 to provide an enterprise-grade authentication and authorization system. This integration adapts the standard OAuth 2.0 flow for FastAPI, supporting multiple application types (SPA, Native, M2M) and social logins.

A key feature of this system is its hybrid nature. After a user authenticates with Auth0, the system generates a DevSkyy-specific JWT. This allows the platform to leverage Auth0's robust identity management features while maintaining compatibility with its existing internal JWT-based authentication infrastructure. This approach provides enterprise-level security features like Multi-Factor Authentication (MFA) and brute-force protection, as detailed in the Authentication & Security Foundation.

Sources: AUTH0_FASTAPI_INTEGRATION_GUIDE.md, AUTH0_INTEGRATION_GUIDE.md, UNICORN_QUICK_START_CHECKLIST.md

Architecture

The integration employs a hybrid authentication architecture that bridges Auth0's OAuth 2.0 flow with DevSkyy's internal JWT system. The process involves redirecting the user to Auth0 for login, receiving a callback with an authorization code, exchanging that code for an Auth0 access token, and finally, creating a custom DevSkyy JWT for use in subsequent API requests.

This diagram illustrates the high-level data flow of the hybrid authentication system.

Components

The system is composed of several key components:

Component	Description	Source File
Auth0 Applications	Configurations for different clients like Web (SPA), Mobile (Native), Admin Dashboard, and API (M2M).	AUTH0_INTEGRATION_GUIDE.md
Auth0 APIs	Defines API resources and scopes (permissions) for DevSkyy services, such as https://api.devskyy.com.	AUTH0_INTEGRATION_GUIDE.md
FastAPI Endpoints	A set of API endpoints to handle the OAuth 2.0 login, callback, and logout flow.	api/v1/auth0_endpoints.py
OAuth2 Client	An Auth0OAuth2Client class responsible for generating authorization URLs and exchanging codes for tokens.	AUTH0_FASTAPI_INTEGRATION_GUIDE.md
JWT Token Bridge	A function that converts user data from Auth0 into a signed DevSkyy JWT token.	AUTH0_FASTAPI_INTEGRATION_GUIDE.md
Token Verification	Functions to verify both Auth0-issued tokens (using RS256 and JWKS) and internal DevSkyy tokens (using HS256).	AUTH0_INTEGRATION_GUIDE.md, security/jwt_auth.py

Configuration

Proper configuration is essential for the integration to work. This involves setting up environment variables in the backend and configuring the application in the Auth0 dashboard.

Environment Variables

The following environment variables must be set for the application to connect with Auth0 and manage JWTs.

Variable	Description	Example	Source
AUTH0_DOMAIN	Your Auth0 tenant domain.	devskyy.us.auth0.com	AUTH0_FASTAPI_INTEGRATION_GUIDE.md
AUTH0_CLIENT_ID	The Client ID of your Auth0 application.	DQRnklWEQkk6F1D5fhJK4Fjz5bVWXrVv	AUTH0_FASTAPI_INTEGRATION_GUIDE.md
AUTH0_CLIENT_SECRET	The Client Secret of your Auth0 application.	ltEkf...	AUTH0_FASTAPI_INTEGRATION_GUIDE.md
AUTH0_AUDIENCE	The unique identifier for your API in Auth0.	https://api.devskyy.com	AUTH0_FASTAPI_INTEGRATION_GUIDE.md
SECRET_KEY	A 256-bit secret key for signing internal DevSkyy JWTs.	61ea...	AUTH0_FASTAPI_INTEGRATION_GUIDE.md
JWT_ALGORITHM	The algorithm used for signing internal DevSkyy JWTs.	HS256	AUTH0_FASTAPI_INTEGRATION_GUIDE.md
ACCESS_TOKEN_EXPIRE_MINUTES	The expiration time for access tokens.	30	UNICORN_QUICK_START_CHECKLIST.md

Auth0 Dashboard Configuration

In the Auth0 dashboard, an application (typically a Single Page Application) must be configured with the correct callback and logout URLs.

• Allowed Callback URLs: The URL where Auth0 will redirect the user after authentication. Example: http://localhost:8000/api/v1/auth/auth0/callback.
• Allowed Logout URLs: The URL where Auth0 will redirect the user after logout. Example: http://localhost:3000.
• Allowed Web Origins: The origins that are allowed to make cross-origin authentication requests. Example: http://localhost:3000, http://localhost:8000.

Sources: AUTH0_FASTAPI_INTEGRATION_GUIDE.md

Authentication Flow

The authentication process follows the standard OAuth 2.0 Authorization Code Flow.

This sequence diagram shows the interaction between the user, frontend, backend (FastAPI), and Auth0 during the login process.

API Endpoints

The integration is managed through a dedicated set of API endpoints.

Method	Endpoint	Description	Response Model
GET / POST	/api/v1/auth/auth0/login	Initiates the Auth0 login flow by returning an authorization URL.	Auth0LoginResponse
GET / POST	/api/v1/auth/auth0/callback	Handles the callback from Auth0, exchanges the code for a token, and returns a DevSkyy JWT.	Auth0TokenResponse
GET / POST	/api/v1/auth/auth0/logout	Initiates the Auth0 logout flow.	Auth0LogoutResponse
GET	/api/v1/auth/auth0/me	Returns the current user's information based on the provided DevSkyy JWT.	Dict[str, Any]
GET	/api/v1/auth/auth0/demo	A demonstration page for testing the authentication flow.	HTML Response

Sources: AUTH0_FASTAPI_INTEGRATION_GUIDE.md, api/v1/auth0_endpoints.py

Response Models

Model	Field	Type	Description
Auth0LoginResponse	authorization_url	str	The URL to redirect the user to for authentication.
	state	str	A random string to prevent CSRF attacks.
Auth0TokenResponse	access_token	str	The newly created DevSkyy JWT.
	refresh_token	str	The DevSkyy refresh token.
	token_type	str	Always "bearer".
	expires_in	int	The token's lifetime in seconds.
	user_info	Dict	A dictionary containing the user's profile information from Auth0.
Auth0LogoutResponse	logout_url	str	The URL to redirect the user to for logout.
	message	str	A confirmation message.

Sources: AUTH0_FASTAPI_INTEGRATION_GUIDE.md

Token Management

DevSkyy JWT Creation

After successful authentication with Auth0, the backend creates a custom DevSkyy JWT. This token includes claims from the Auth0 user profile but is signed with the DEVSKYY_SECRET_KEY using the HS256 algorithm. This allows the rest of the application to verify tokens without needing to communicate with Auth0.

# Source: AUTH0_FASTAPI_INTEGRATION_GUIDE.md
def create_devskyy_jwt_token(user_data: Dict[str, Any], expires_delta: Optional[timedelta] = None) -> str:
    """Create DevSkyy JWT token with Auth0 user data."""
    payload = {
        "sub": user_data.get("sub"),  # Auth0 user ID
        "email": user_data.get("email"),
        "name": user_data.get("name"),
        "picture": user_data.get("picture"),
        "email_verified": user_data.get("email_verified", False),
        "exp": expire,
        "iat": datetime.utcnow(),
        "iss": "devskyy-platform",
        "aud": "devskyy-api",
        "token_type": "access",
        "auth_provider": "auth0"
    }
    
    # Sign with DevSkyy secret key for compatibility
    return jwt.encode(payload, DEVSKYY_SECRET_KEY, algorithm=DEVSKYY_JWT_ALGORITHM)

Sources: AUTH0_FASTAPI_INTEGRATION_GUIDE.md

Token Verification

The system supports verification of both Auth0-issued tokens and its own internal tokens.

1. Auth0 Token Verification: Used during the callback phase. It fetches the public key (JWKS) from the Auth0 tenant's .well-known endpoint and verifies the token signature using the RS256 algorithm.

   # Source: AUTH0_INTEGRATION_GUIDE.md
   async def verify_auth0_token(token: str = Depends(security)):
       """Verify Auth0 JWT token."""
       try:
           jwks = get_auth0_public_key()
           payload = jwt.decode(
               token.credentials,
               jwks,
               algorithms=["RS256"],
               audience=AUTH0_AUDIENCE,
               issuer=f"https://{AUTH0_DOMAIN}/"
           )
           return payload
       except JWTError:
           raise HTTPException(
               status_code=status.HTTP_401_UNAUTHORIZED,
               detail="Invalid authentication credentials",
           )
   

   Sources: AUTH0_INTEGRATION_GUIDE.md

2. DevSkyy JWT Verification: Used for all subsequent authenticated API requests. It uses the shared SECRET_KEY and HS256 algorithm to validate the token.

   # Source: AUTH0_FASTAPI_INTEGRATION_GUIDE.md
   def verify_devskyy_jwt_token(token: str) -> Dict[str, Any]:
       """Verify DevSkyy JWT token (compatible with existing system)."""
       return jwt.decode(
           token,
           DEVSKYY_SECRET_KEY,
           algorithms=[DEVSKYY_JWT_ALGORITHM],
           audience="devskyy-api",
           issuer="devskyy-platform"
       )
   

   Sources: AUTH0_FASTAPI_INTEGRATION_GUIDE.md, security/jwt_auth.py

Security Features

The integration leverages Auth0's enterprise-grade security features.

Feature	Description
Multi-Factor Authentication (MFA)	Supports TOTP (e.g., Google Authenticator) and SMS to add a second layer of security.
Brute Force Protection	Automatically locks out users and blocks IPs after a number of failed login attempts.
Password Policies	Enforces strong password requirements, including length, complexity, and history checks.
Session Management	Configurable session lifetimes and idle timeouts for different applications (web, mobile, admin).
CSRF Protection	The state parameter is used during the OAuth flow to mitigate Cross-Site Request Forgery attacks.
Refresh Token Rotation	Automatic rotation of refresh tokens to enhance security.

Sources: AUTH0_INTEGRATION_GUIDE.md, AUTH0_FASTAPI_INTEGRATION_GUIDE.md

Summary

The Auth0 integration provides the DevSkyy platform with a robust, scalable, and secure authentication system. By creating a hybrid model that issues internal JWTs after an initial Auth0 login, it combines the powerful identity management capabilities of Auth0 with the simplicity and performance of a self-contained token system. This allows for features like social logins, MFA, and advanced security policies while maintaining compatibility with existing backend services that rely on DevSkyy's JWT format.

Sources: AUTH0_FASTAPI_INTEGRATION_GUIDE.md, AUTH0_INTEGRATION_GUIDE.md