Integration Guide

Step 1: Generate an RSA Key Pair

You’ll use your private key to sign JWTs and share the public key with Arena so we can verify them.

🔐 Key Generation (Bash)

# Generate 2048-bit RSA private key
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048

# Extract the public key
openssl rsa -pubout -in private_key.pem -out public_key.pem

IMPORTANT: Keep private_key.pem secret and secure. Load it from an environment variable. Share only public_key.pem and your JWT endpoint URL with Arena.

Step 2: Implement the Arena JWT SSO Endpoint

Your backend must expose a secure route (e.g. /arena/sso-jwt) that:

Verifies the user is authenticated on your site
Generates a short-lived JWT containing user identity
Signs it with your RSA private key
Returns the JWT in the response

🧾 JWT Payload Claims

{
  "sub": "[email protected]",     // Same as email
  "email": "[email protected]",
  "displayName": "Jane Doe",
  "photoURL": "https://example.com/avatar.jpg",
  "iat": 1720452000,             // Issued at (Unix timestamp)
  "exp": 1720452300,             // Expires (1 minute from now)
  "iss": "your_website_sso_id"   // Your website SSO issuer ID, provided by Arena's tech team during onboarding
}

🔧 Node.js Example (using jsonwebtoken)

const jwt = require('jsonwebtoken');
const express = require('express');
const app = express();

// must contain the contents of private_key.pem generated in step 1
const PRIVATE_KEY = process.env.ARENA_SSO_PRIVATE_KEY;

// provided by Arena's tech team during onboarding
const ARENA_SSO_ISSUER_ID = process.env.ARENA_SSO_ISSUER_ID;

app.get('/arena/sso-jwt', (req, res) => {
  // replace whis validation with your website's own auth validation
  const user = req.authenticatedUser;
  if (!user) return res.status(401).json({ error: 'Unauthorized' });

  const payload = {
    sub: user.id,
    email: user.email,
    displayName: user.name,
    photoURL: user.avatar,
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + 60, // 1-minute expiry
    iss: ARENA_SSO_ISSUER_ID
  };

  const token = jwt.sign(payload, PRIVATE_KEY, { algorithm: 'RS256' });

  res.json({ token });
});

🔧 PHP Example (using firebase/php-jwt)

use Firebase\JWT\JWT;
use Firebase\JWT\Key;

// must contain the contents of private_key.pem generated in step 1
$privateKey = getenv('ARENA_SSO_PRIVATE_KEY');

// provided by Arena's tech team during onboarding
$ssoIssuerID = getenv('ARENA_SSO_ISSUER_ID');

// replace whis validation with your website's own auth validation
$user = get_authenticated_user();
if (!$user) {
  http_response_code(401);
  echo json_encode(['error' => 'Unauthorized']);
  exit;
}

$payload = [
  'sub' => $user['id'],
  'email' => $user['email'],
  'displayName' => $user['name'],
  'photoURL' => $user['avatar'],
  'iat' => time(),
  'exp' => time() + 60,
  'iss' => $ssoIssuerID
];

$jwt = JWT::encode($payload, $privateKey, 'RS256');

echo json_encode(['token' => $jwt]);

Step 3: Send Information to Arena

Send the following to the Arena team:

The public endpoint URL of your JWT SSO route implemented in step 2 (e.g. https://yourdomain.com/arena/sso-jwt)
Your public key (contents of public_key.pem)

Arena will register your public key and endpoint to verify JWTs issued by your system.

Step 4: Arena SSO in Action

Once configured, the Arena widget will enter "SSO mode" and will:

Call your JWT SSO endpoint when embedded on your website
Receive the signed JWT
Exchange user data contained in the JWT with Arena's authentication service
Sign the user into Arena automatically

Your users are now seamlessly authenticated through your own system without needing to sign in manually.