Federation Provisioning Implementation

This guide covers the complete technical implementation for enabling your customers to connect their identity providers to your application through Authonomy’s federation provisioning service.

Overview

Federation provisioning allows your customers to connect their own IDPs (such as Okta, Azure AD, Google Workspace, etc.) to your application through your existing IDP infrastructure. Authonomy handles the complex federation setup automatically while you maintain a single integration point with your own IDP.

What you’ll implement:

• Configure your IDP in Authonomy with OIDC permissions
• Set up JWT authentication for tenant-level operations
• Generate appropriate JWTs with proper permissions
• Redirect customers to the federation wizard

Prerequisites

Before starting, ensure you have:

• An existing IDP (such as Okta, Azure AD, etc.) configured for your application
• Administrative access to your IDP
• Authonomy account with API access
• Understanding of OIDC/OAuth2 flows

Implementation Steps

Step 1: Setup Your IDP with Authonomy

Before customers can use the federation wizard, you need to configure your IDP to work with Authonomy. This involves creating an OIDC application in your IDP and granting Authonomy the necessary permissions to manage federation on your behalf.

Why this is needed: Authonomy needs administrative access to your IDP to automatically provision federated connections when your customers connect their IDPs. This one-time setup enables the automated federation provisioning that makes the customer experience seamless.

What gets configured:

• OIDC application in your IDP with appropriate scopes
• Administrative permissions for identity provider management
• Secure credential exchange between your IDP and Authonomy

IDP-specific setup guides:

• Setup Your Okta IDP - Complete Okta configuration steps

Step 2: Configure Your Application to Generate JWTs and Redirect Users

Implement JWT generation and redirect functionality in your application to send customers to the federation wizard with proper authentication.

Required Federation Permissions

Your JWTs must include these specific permissions in the permissions claim:

Note: Replace {idp_id} with the actual UUID of your identity provider (e.g., bbd5235b-1599-41d4-a800-485d7d8fcd76).

2.1 Generate JWT Tokens for Federation

First, implement JWT generation with the required federation permissions:

const jwt = require('jsonwebtoken');
const fs = require('fs');

function generateFederationJWT(userId, tenantId, idpId, customerMetadata) {
  const privateKey = fs.readFileSync('federation_jwt_private.pem', 'utf8');
  
  const payload = {
    iss: 'https://yourapp.com',
    aud: 'authonomy-federation',
    sub: userId,
    tenant_id: tenantId,
    permissions: [
      `idp:read:item:${idpId}`,
      `federation:create:idp:${idpId}`,
      `federation:push:idp_item:*`
    ],
    customer_metadata: customerMetadata,
    exp: Math.floor(Date.now() / 1000) + (60 * 60), // 1 hour
    iat: Math.floor(Date.now() / 1000),
    jti: `jwt_${Date.now()}_${Math.random()}`
  };

  return jwt.sign(payload, privateKey, { algorithm: 'RS256' });
}

2.2 Construct Federation Wizard URL

Build the federation wizard URL with the JWT token and required parameters:

function buildFederationWizardURL(idpId, jwt, returnUrl, options = {}) {
  const baseUrl = `https://authonomy.io/federation-setup/${idpId}`;
  const params = new URLSearchParams({
    token: jwt,
    return_url: returnUrl
  });
  
  return `${baseUrl}?${params.toString()}`;
}

// Example usage
const wizardUrl = buildFederationWizardURL(
  'bbd5235b-1599-41d4-a800-485d7d8fcd76', // IDP ID
  generatedJWT,
  'https://yourapp.com/settings/federation/complete'
);

2.3 Handle Federation Wizard Redirect

In your application’s federation settings page:

// When customer clicks "Connect Identity Provider"
function initiateFederation(customerId, userId, identityProviderId) {
  // Generate JWT for this customer with specific IDP permissions
  const jwt = generateFederationJWT(
    userId,
    `customer_${customerId}`,
    identityProviderId, // The specific IDP they want to configure
    {
      name: customer.name,
      contact_email: customer.adminEmail
    }
  );
  
  // Build wizard URL
  const wizardUrl = buildFederationWizardURL(
    identityProviderId,
    jwt,
    `https://yourapp.com/customers/${customerId}/federation/complete`
  );
  
  // Redirect to federation wizard
  window.location.href = wizardUrl;
}

2.4 Handle Federation Completion

Set up a callback endpoint to handle the completion:

// Route: /customers/:customerId/federation/complete
app.get('/customers/:customerId/federation/complete', (req, res) => {
  const { status, federation_id, error } = req.query;
  
  if (status === 'success') {
    // Federation setup completed successfully
    // Store federation_id for this customer
    await database.updateCustomer(req.params.customerId, {
      federation_id: federation_id,
      federation_status: 'active',
      federation_completed_at: new Date()
    });
    
    res.redirect(`/customers/${req.params.customerId}/settings?federation=success`);
  } else {
    // Handle federation setup failure
    console.error('Federation setup failed:', error);
    res.redirect(`/customers/${req.params.customerId}/settings?federation=error&message=${error}`);
  }
});

Step 3: Configure JWT Authentication in Authonomy

Configure Authonomy to accept and validate JWT tokens from your application for federation wizard access.

What you’ll do:

• Set up JWT validation rules in the Authonomy admin dashboard
• Configure your JWT signing keys and issuer details
• Test JWT token validation

Complete setup instructions: Follow the JWT Configuration guide to:

1. Access the Authonomy admin dashboard
2. Navigate to JWT Authentication settings
3. Upload your public key for JWT signature verification
4. Configure your issuer URL and audience
5. Test JWT token validation

You now have a complete federation provisioning implementation that allows your customers to seamlessly connect their IDPs to your application through Authonomy’s automated configuration service.