Zuplo
Authentication

PingFederate Authentication Setup

PingFederate is an enterprise federation server that enables secure single sign-on (SSO) and API security for organizations. This guide walks you through integrating PingFederate with Dev Portal using OpenID Connect.

Prerequisites

  • Access to a PingFederate server (version 9.0 or later recommended)
  • Administrative access to configure OAuth clients in PingFederate
  • Your PingFederate server's base URL

Setup Steps

  1. Create an OAuth Client in PingFederate

    In the PingFederate administrative console:

    • Navigate to Applications → OAuth → Clients
    • Click Add Client
    • Configure the client:
      • Client ID: Choose a unique identifier (e.g., zudoku-docs)
      • Client Authentication: Select None (Public Client)
      • Grant Types: Enable Authorization Code and Refresh Token
      • Redirect URIs:
        • Production: https://your-site.com/oauth/callback
        • Preview (wildcard): https://*.your-domain.com/oauth/callback
        • Local Development: http://localhost:3000/oauth/callback

  2. Configure OpenID Connect Settings

    Still in the OAuth client configuration:

    • Enable OpenID Connect
    • Configure scopes:
      • Enable openid, profile, and email (minimum required)
      • Add any custom scopes your organization requires
    • ID Token Signing Algorithm: RS256 (recommended)
    • Access Token Manager: Select or create an appropriate token manager
    • Save the configuration

  3. Configure Zudoku

    Add the PingFederate configuration to your Dev Portal configuration file:

    Code
     
    // zudoku.config.ts
export default {
  // ... other configuration
  authentication: {
    type: "openid",
    clientId: "zudoku-docs", // Your OAuth client ID
    issuer: "https://pingfederate.your-domain.com", // Your PingFederate base URL
    scopes: ["openid", "profile", "email"], // Optional: add custom scopes
  },
  // ... other configuration
};

Configuration Options

Custom Scopes

If your organization uses custom scopes for authorization, include them in the configuration:

Code
 
authentication: {
  type: "openid",
  clientId: "zudoku-docs",
  issuer: "https://pingfederate.your-domain.com",
  scopes: ["openid", "profile", "email", "groups", "roles", "api:read"],
}

Advanced Configuration

CORS Configuration

Configure CORS in PingFederate for your documentation site:

  1. Navigate to System → Server Configuration → Cross-Origin Resource Sharing
  2. Add your site's domain to the allowed origins:
    • https://your-site.com
    • http://localhost:3000 (for local development)

Attribute Mapping

PingFederate can map user attributes from various sources. Ensure these standard claims are mapped:

  1. Go to OAuth → Access Token Management → Your Token Manager
  2. Configure attribute mappings:
    • sub → User's unique identifier
    • name → User's display name
    • email → User's email address
    • picture → User's profile picture URL (if available)

Troubleshooting

Common Issues

  1. Discovery Endpoint Not Found: Ensure your issuer URL is correct and accessible. The OpenID Connect discovery endpoint should be available at https://your-pingfederate-server/.well-known/openid-configuration.

  2. Invalid Client Configuration: Verify that the client ID matches exactly and that the redirect URIs are properly configured in PingFederate.

  3. CORS Errors: Check that your site's domain is added to PingFederate's CORS configuration.

  4. Missing User Attributes: Ensure attribute mappings are configured in your Access Token Manager.

  5. Token Validation Errors: Verify that your PingFederate server's certificates are valid and that clock synchronization is accurate.

Security Considerations

  • Always use HTTPS for production deployments
  • Regularly rotate signing certificates in PingFederate
  • Configure appropriate session timeouts
  • Review and audit OAuth client configurations periodically

Next Steps

Last modified on
Azure ADSupabase