Proxied Authentication Request

Overview

By default, Puzzel authentication requests can be initiated from any location via a browser or HTTP client. While standard sitemapping is sufficient for most use cases, business-critical applications may require stricter security controls.

To enhance security, you can proxy the authentication request through your own infrastructure. This allows you to restrict token generation to a specific, white-listed IP range (IPv4 or IPv6) controlled by your organization.

1. Server-Side Configuration

To enable IP restrictions, you must define the allowed IP ranges in the Puzzel Administration Portal.

• Location: Puzzel IDP Settings
• Action: Input the public IP address or CIDR range of the proxy server that will handle the requests.

2. Proxy Implementation

The proxy server acts as an intermediary between the client browser and the Puzzel Identity Provider.

Upstream API Specification

Your proxy must forward requests to the following endpoint:

• Endpoint: https://app-consumeridp.puzzel.com/connect/token
• Method: POST
• Content-Type: application/x-www-form-urlencoded

Required Body Parameters:

Response:
On success, the endpoint returns a JSON object containing the access_token and refresh_token.

Example Implementation (Node.js/Express)

The following example demonstrates a basic Express server that forwards the token request.

const express = require('express');
const axios = require('axios');
const bodyParser = require('body-parser');

const app = express();
const PORT = 3000;
const UPSTREAM_URL = 'https://app-consumeridp.puzzel.com/connect/token';

// Middleware to parse application/x-www-form-urlencoded
app.use(bodyParser.urlencoded({ extended: true }));

app.post('/connect/token', async (req, res) => {
  try {
    // Forward the request to Puzzel IDP
    const response = await axios.post(
      UPSTREAM_URL,
      new URLSearchParams(req.body).toString(),
      {
        headers: {
          // It is recommended to selectively forward headers rather than spreading all
          'Content-Type': 'application/x-www-form-urlencoded',
        },
      }
    );
    
    // Return the IDP response to the client
    res.status(response.status).send(response.data);
    
  } catch (error) {
    if (error.response) {
      // Handle upstream errors (e.g., 401, 403)
      res.status(error.response.status).send(error.response.data);
    } else {
      // Handle network or server errors
      console.error(error);
      res.status(500).send({ error: 'Internal server error' });
    }
  }
});

app.listen(PORT, () => {
  console.log(`Proxy server running on http://localhost:${PORT}`);
});

3. Client-Side Configuration

To utilize the proxy, you must override the default token endpoint in the Puzzel loader script using the data-custom-token-endpoint attribute.

Script Parameters

• data-customer-id: Your Puzzel Customer ID.
• data-custom-token-endpoint: The full URL to your proxy server endpoint (e.g., https://myproxyserver.customer.com/connect/token).

Implementation Snippet

<script type="text/javascript"> 
  (function (a, b) { 
    var loader = a.createElement('script'); 
    loader.type = 'text/javascript';
    loader.src = 'https://app-cdn.puzzel.com/public/js/pzl_loader.js'; 
    loader.setAttribute('id', 'pzlModuleLoader'); 
    
    // Set Customer ID
    loader.setAttribute('data-customer-id', b); 
    
    // Set Custom Proxy Endpoint
    loader.setAttribute('data-custom-token-endpoint', 'https://myproxyserver.customer.com/connect/token');
    
    a.body.append(loader); 
  })(document, 'your_customer_id'); 
</script>