Foxia Auth SDK

A lightweight and efficient SDK for seamless integration of Foxia Authentication (OIDC) into your Node.js applications.

Installation

Install the package via npm:

npm install foxia-auth-sdk

Getting Started

Import and initialize FoxiaAuth with your configuration details:

const { FoxiaAuth } = require('foxia-auth-sdk');

const auth = new FoxiaAuth({
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    redirectUri: 'your-redirect-callback-uri',
    hydraPublicUrl: 'your-hydra-public-url',
    scopes: ['openid', 'profile', 'email']
});

Integration Guide

Step 1: Generate Login URL

Create a route to redirect users to the Foxia login page:

// Route: /login
app.get('/login', (req, res) => {
    const { url, state } = auth.generateAuthUrl();
    
    // Store 'state' in session or cookie to verify later (CSRF protection)
    req.session.oauthState = state;
    
    res.redirect(url);
});

Step 2: Handle Callback and Token Exchange

After successful login, the user will be redirected to your redirectUri with code and state parameters.

// Route: /callback
app.get('/callback', async (req, res) => {
    const { code, state } = req.query;
    
    // 1. Verify state
    if (state !== req.session.oauthState) {
        return res.status(400).send('Invalid state');
    }
    
    try {
        // 2. Exchange code for tokens
        const tokens = await auth.exchangeCode(code);
        
        // tokens object includes:
        // {
        //   access_token: "...",
        //   id_token: "...",
        //   refresh_token: "...",
        //   expires_in: 3600,
        //   ...
        // }
        
        console.log('Access Token:', tokens.access_token);
        
        // Store tokens or create a local session for the user...
        res.json(tokens);
        
    } catch (error) {
        console.error('Login failed:', error.message);
        res.status(500).send('Authentication failed');
    }
});

Step 3: Retrieve User Information

Use the Access Token to fetch the user's profile information:

const userInfo = await auth.getUserInfo(accessToken);

console.log(userInfo);
// {
//   sub: "user-id",
//   email: "[email protected]",
//   name: "Full Name",
//   ...
// }

API Reference

new FoxiaAuth(config)

• clientId (string, required): Your application's Client ID.
• redirectUri (string, required): The registered callback URL.
• hydraPublicUrl (string, required): The Base URL of the Auth server.
• clientSecret (string, optional): Required for server-side applications (Confidential Clients).
• scopes (array, optional): List of access privileges requested.

generateAuthUrl(options)

• Returns { url, state }.
• options.state: Pass a custom state value if you wish to manage it manually.
• options.scopes: Override default scopes for this request.

exchangeCode(code)

• Exchanges the authorization code for an Access Token, ID Token, and Refresh Token.
• Returns a Promise that resolves to an object containing the tokens.

getUserInfo(accessToken)

• Retrieves user profile information from the userinfo endpoint.