Pre-release — content may change.

GuidesSingle Sign-On

Delegated Authentication

Understanding delegated authentication with external identity providers

Delegated authentication allows external identity providers (Azure AD B2C, Auth0, Okta) to manage user accounts instead of Wicket. There are two ways to integrate:

Two Integration Approaches

Option A: CAS-Proxied Delegation (Simpler)

Wicket CAS acts as a transparent proxy to external providers. Your application uses standard CAS authentication code.

Pros:

  • Application code identical to standard CAS
  • Wicket team manages OAuth application configuration
  • Middleware iPaaS handles user provisioning automatically
  • No changes needed when switching providers

Cons:

  • Less control over OAuth application settings
  • Relies on Wicket team for provider configuration

For Developers: Your application code is identical to standard CAS. See CAS Implementation Guide for code examples.


Option B: Direct Integration (More Control)

Your application implements OIDC/SAML directly with the external provider and calls /user_identities/provision during login.

Pros:

  • Full control over OAuth application configuration
  • Can customize OAuth scopes and claims
  • Direct relationship with identity provider
  • More flexibility in authentication flow

Cons:

  • Must implement OIDC/SAML client code
  • Must handle user provisioning in application
  • More code to maintain
  • Must update code when switching providers

For Developers: You implement OIDC/SAML client code and call /user_identities/provision after authentication. See examples in Provider Configuration Guide.


CAS-Proxied Delegation (Option A)

How CAS Delegation Works

Key Concept: CAS translates between external provider protocols (OpenID Connect, SAML) and the CAS protocol, making delegation transparent to your application.

From your application's perspective:

  • You redirect to CAS login URL
  • You validate CAS service tickets
  • You extract person UUID from CAS attributes
  • The integration code is identical to standard CAS

What CAS does internally:

  • Delegates authentication to external provider (B2C, Auth0, Okta, etc.)
  • Receives external authentication response
  • Translates it back to CAS protocol
  • Returns a standard CAS ticket with person UUID

Authentication Flow

Sequence Diagram

Step-by-Step

User Visits Application

User navigates to your application. Your app detects no session and redirects to CAS:

// Your application code - same as standard CAS
res.redirect('https://your-org-login.wicketcloud.com/login?service=...');

CAS Detects Delegation

Wicket CAS detects that delegation is configured and internally redirects to the external provider (B2C, Auth0, etc.):

CAS → Azure B2C OAuth authorize endpoint

Note: This happens inside CAS infrastructure. Your application doesn't see this redirect.

External Provider Authenticates User

User sees the external provider's login page (Azure B2C, Auth0, Okta login screen) and enters credentials.

External provider validates credentials and returns authentication response to CAS.

CAS Translates Response

CAS receives the external authentication response (OIDC ID token, SAML assertion, etc.) and:

  1. Extracts external user ID (e.g., Azure B2C object ID)
  2. Looks up Wicket person UUID using user_identity link
  3. Generates standard CAS service ticket
  4. Includes personUuid in ticket attributes

CAS Returns to Application

CAS redirects back to your application with a standard CAS ticket:

https://your-app.com/auth/callback?ticket=ST-12345-abcdefg

From your application's perspective, this is identical to standard CAS.

Application Validates Ticket

Your application validates the ticket using standard CAS protocol:

// Your application code - identical for standard and delegated CAS
const validateUrl = `${CAS_BASE_URL}/serviceValidate?ticket=${ticket}&service=${service}`;
const response = await fetch(validateUrl);
// Parse XML, extract personUuid from attributes

Application Signs JWT

Your application uses the person UUID to sign a Wicket MDP API JWT:

// Your application code - identical for standard and delegated CAS
const wicketToken = jwt.sign(
  { user_uuid: personUuid, exp: Math.floor(Date.now() / 1000) + 3600 },
  process.env.WICKET_API_SECRET,
  { algorithm: 'HS256' }
);

User Provisioning

User provisioning happens differently depending on your integration approach:

CAS-Proxied Delegation (Option A)

User provisioning happens via middleware (iPaaS), not in your application's login flow.

Provisioning Architecture

Provisioning Flow

MDP-First Flow (Person created in Wicket first):

  1. Administrator creates person in Wicket Admin
  2. roles.granted webhook fires to middleware iPaaS
  3. Middleware creates user in external provider (B2C, Auth0, etc.)
  4. Middleware calls /user_identities/provision to link external ID to Wicket person
  5. Person can now authenticate via delegated CAS

External-First Flow (User signs up in external provider first):

  1. User signs up in external provider (self-service)
  2. External provider webhook fires to middleware iPaaS
  3. Middleware creates person in Wicket via API
  4. Middleware calls /user_identities/provision to link accounts
  5. Person can now authenticate via delegated CAS

Important for CAS-Proxied: Your application does NOT call /user_identities/provision during login with this approach. Provisioning is handled by middleware iPaaS. Your application only implements standard CAS authentication.


Direct Integration (Option B)

Your application handles provisioning by calling /user_identities/provision during the login flow.

Login Flow:

  1. User clicks login → redirected to external provider (B2C, Auth0, Okta)
  2. User authenticates with external provider
  3. External provider returns to your application with auth code/token
  4. Your application calls /user_identities/provision with external user ID
  5. Wicket creates/links person and returns person UUID
  6. Your application signs Wicket JWT with person UUID
  7. User logged in!

Example: Azure B2C Direct Integration

// Your application callback handler
app.get('/auth/b2c/callback', async (req, res) => {
  const { code } = req.query;

  try {
    // 1. Exchange code for tokens with B2C
    const tokens = await exchangeB2CCode(code);
    const idToken = decodeJWT(tokens.id_token);

    // 2. Provision user identity in Wicket
    const provisionResponse = await fetch(
      `${WICKET_API_URL}/user_identities/provision`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${WICKET_ADMIN_TOKEN}`,
          'Content-Type': 'application/vnd.api+json'
        },
        body: JSON.stringify({
          data: {
            type: 'user_identities',
            attributes: {
              provider_slug: 'b2c',
              external_id: idToken.sub,  // B2C user ID
              email: idToken.email,
              person: {
                given_name: idToken.given_name,
                family_name: idToken.family_name
              }
            }
          }
        })
      }
    );

    const userIdentity = await provisionResponse.json();
    const personUuid = userIdentity.data.relationships.person.data.id;

    // 3. Sign Wicket JWT
    const wicketToken = jwt.sign(
      { user_uuid: personUuid, exp: Math.floor(Date.now() / 1000) + 3600 },
      process.env.WICKET_API_SECRET,
      { algorithm: 'HS256' }
    );

    // 4. Store in session
    req.session.wicketToken = wicketToken;
    req.session.personUuid = personUuid;

    res.redirect('/dashboard');

  } catch (error) {
    console.error('SSO error:', error);
    res.redirect('/login?error=auth_failed');
  }
});

See the Provider Configuration Guide for complete OIDC/SAML integration examples.

For Direct Integration: Your application manages the OAuth application configuration in the external provider and calls /user_identities/provision during login. See User Provisioning Guide for complete API documentation.


Supported External Providers

CAS can delegate to any of these provider types:

OpenID Connect (OIDC)

  • Azure AD B2C — Microsoft's consumer identity platform
  • Auth0 — Third-party identity platform
  • Okta — Enterprise identity platform
  • Keycloak — Open-source identity solution
  • Google Identity Platform — Google accounts
  • Custom OIDC providers — Any OpenID Connect compliant provider

SAML 2.0

  • Azure AD — Microsoft enterprise Active Directory
  • Okta — SAML integration
  • OneLogin — Enterprise SSO
  • Shibboleth — Academic/research identity federation
  • Custom SAML IdPs — Any SAML 2.0 compliant provider

OAuth 2.0

  • Custom OAuth providers — For providers not supporting OIDC
  • Legacy integrations — OAuth 2.0 only systems

External CAS

  • University CAS servers — Existing academic CAS infrastructure
  • Enterprise CAS — Corporate CAS deployments
  • CAS-to-CAS delegation — Chain multiple CAS servers

Configuration

Delegated authentication is configured by Wicket implementation team, not through a UI.

Contact Wicket Support: Delegated authentication setup requires Wicket implementation team configuration. There is no self-service UI for configuring external providers yet.

What Wicket implementation team configures:

  1. External Provider Details:

    • Provider type (OIDC, SAML, OAuth, CAS)
    • Connection endpoints (discovery URL, SSO URL, etc.)
    • Client credentials (Client ID, Client Secret)
    • Certificates (for SAML)
  2. Attribute Mapping:

    • External user ID → Wicket person UUID lookup
    • Email, name, custom attributes
    • Claim/attribute transformation rules
  3. CAS Integration:

    • Enable delegation for your organization's CAS
    • Configure CAS attribute passthrough
    • Set up person UUID resolution

What you provide to Wicket team:

  • Provider name and type (e.g., "Azure B2C", "Okta SAML")
  • Connection details (tenant ID, domain, etc.)
  • Client credentials from provider setup
  • Attribute mapping requirements
  • Middleware iPaaS webhook endpoints

See the Provider Configuration Guide for detailed setup requirements for each provider type.

Advantages of Delegated CAS

1. No Application Code Changes

Your application code is identical for standard and delegated CAS:

// This code works for BOTH standard and delegated CAS
app.get('/login', (req, res) => {
  res.redirect(`${CAS_BASE_URL}/login?service=${SERVICE_URL}`);
});

app.get('/auth/callback', async (req, res) => {
  const personUuid = await validateCASTicket(req.query.ticket);
  const wicketToken = generateWicketJWT(personUuid);
  req.session.wicketToken = wicketToken;
  res.redirect('/dashboard');
});

2. Centralized Authentication Logic

All authentication complexity is handled by CAS:

  • Protocol translation (OIDC → CAS, SAML → CAS)
  • Token validation
  • Session management
  • Person UUID resolution

Your application stays simple and focused on business logic.

3. Consistent User Experience

Users always see a consistent login flow:

  • Redirected to CAS
  • Authenticate (whether Wicket or external)
  • Return to application logged in

No different code paths for different auth methods.

4. Easy to Switch Providers

Wicket team can change external providers without touching your application:

  • Switch from Auth0 to Okta
  • Add Azure B2C alongside existing auth
  • Migrate between authentication methods

Your application code remains unchanged.

When to Use Delegated CAS

Good Use Cases

✅ Enterprise Active Directory Integration

  • Company uses Azure AD for employee accounts
  • Need SSO across all enterprise applications
  • Existing identity governance policies

✅ Multi-Tenant SaaS

  • Different customers use different identity providers
  • Each tenant has their own Auth0/Okta configuration
  • Need to support various enterprise SSO requirements

✅ Existing External User Base

  • Users already exist in Auth0, Okta, etc.
  • Don't want to duplicate user management
  • External system is source of truth for identity

✅ Regulatory/Compliance Requirements

  • Must use specific enterprise identity provider
  • Identity federation requirements
  • Audit and compliance tracking needs

When Standard CAS is Better

✅ Simple Membership Organization

  • Members managed directly in Wicket
  • No external identity requirements
  • Wicket is primary membership system

✅ Rapid Development/Prototyping

  • Don't want to set up external providers
  • Standard CAS is simpler to configure
  • Can migrate to delegated later if needed

Comparison: Standard vs Delegated Approaches

AspectStandard CASDelegated (CAS-Proxied)Delegated (Direct)
User StorageWicket databaseExternal IdPExternal IdP
AuthenticationCAS validates Wicket usersCAS proxies to IdPApp calls IdP directly
App CodeStandard CASIdentical - Standard CASOIDC/SAML client
SetupWicket team enables CASWicket team configuresYou configure OAuth app
ProvisioningCreate in Wicket AdminMiddleware iPaaS (webhooks)App during login
OAuth App ManagementN/AWicket managesYou manage
Password ManagementWicketExternal providerExternal provider
MFA/2FAWicket CAS (if enabled)External providerExternal provider
User Self-ServiceWicket member portalExternal provider portalExternal provider portal
ComplexityLowerMedium (requires middleware)Medium (requires app code)
FlexibilityLowerLowerHigher

Testing Delegated Authentication

1. Verify CAS Delegation Works

Steps:

  1. Implement standard CAS authentication in your application
  2. Test with standard Wicket CAS (should work)
  3. Ask Wicket team to configure delegation to external provider
  4. Test again — should redirect to external provider login
  5. Authenticate with external provider
  6. Verify you're logged into your application
  7. Check application received person UUID correctly

2. Test User Provisioning

Verify user identity linkage:

# After successful login, check user identity exists
GET /people/{person_id}/user_identities

# Should return:
{
  "data": [{
    "type": "user_identities",
    "attributes": {
      "provider_slug": "b2c",
      "external_id": "external-user-id-from-b2c",
      "provider_type": "generic_oidc"
    }
  }]
}

3. Test Round-Trip Flow

End-to-end test:

  1. User visits application → redirects to CAS
  2. CAS redirects to external provider (B2C, Auth0, etc.)
  3. User authenticates with external provider
  4. External provider returns to CAS
  5. CAS returns ticket to application
  6. Application validates ticket
  7. Application receives personUuid
  8. Application signs JWT and grants access

All steps should complete successfully.

Troubleshooting

User Redirected to Wrong Provider

Issue: CAS redirects to unexpected external provider

Solutions:

  • Verify Wicket team configured correct provider for your organization
  • Check CAS delegation configuration
  • Ensure provider slug matches expected provider

Person UUID Not Found

Issue: CAS returns error "Person not found for external user"

Solutions:

  • Verify user identity was provisioned (check /user_identities)
  • Ensure middleware iPaaS is running and processing webhooks
  • Check middleware logs for provisioning errors
  • Verify external user ID matches what's stored in Wicket

External Provider Login Fails

Issue: External provider shows error or rejects login

Solutions:

  • Verify user exists in external provider
  • Check external provider credentials are valid
  • Ensure CAS redirect URI is whitelisted in provider config
  • Review external provider logs for specific error

Middleware Not Provisioning Users

Issue: Users authenticate but no user_identity created

Solutions:

  • Verify middleware iPaaS is receiving webhooks
  • Check webhook endpoint URLs are correct
  • Ensure middleware has admin token for Wicket MDP API
  • Review middleware logs for errors
  • Verify provider_slug in middleware matches Wicket configuration

On this page