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 endpointNote: 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:
- Extracts external user ID (e.g., Azure B2C object ID)
- Looks up Wicket person UUID using user_identity link
- Generates standard CAS service ticket
- 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-abcdefgFrom 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 attributesApplication 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):
- Administrator creates person in Wicket Admin
roles.grantedwebhook fires to middleware iPaaS- Middleware creates user in external provider (B2C, Auth0, etc.)
- Middleware calls
/user_identities/provisionto link external ID to Wicket person - Person can now authenticate via delegated CAS
External-First Flow (User signs up in external provider first):
- User signs up in external provider (self-service)
- External provider webhook fires to middleware iPaaS
- Middleware creates person in Wicket via API
- Middleware calls
/user_identities/provisionto link accounts - 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:
- User clicks login → redirected to external provider (B2C, Auth0, Okta)
- User authenticates with external provider
- External provider returns to your application with auth code/token
- Your application calls
/user_identities/provisionwith external user ID - Wicket creates/links person and returns person UUID
- Your application signs Wicket JWT with person UUID
- 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:
-
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)
-
Attribute Mapping:
- External user ID → Wicket person UUID lookup
- Email, name, custom attributes
- Claim/attribute transformation rules
-
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
| Aspect | Standard CAS | Delegated (CAS-Proxied) | Delegated (Direct) |
|---|---|---|---|
| User Storage | Wicket database | External IdP | External IdP |
| Authentication | CAS validates Wicket users | CAS proxies to IdP | App calls IdP directly |
| App Code | Standard CAS | Identical - Standard CAS | OIDC/SAML client |
| Setup | Wicket team enables CAS | Wicket team configures | You configure OAuth app |
| Provisioning | Create in Wicket Admin | Middleware iPaaS (webhooks) | App during login |
| OAuth App Management | N/A | Wicket manages | You manage |
| Password Management | Wicket | External provider | External provider |
| MFA/2FA | Wicket CAS (if enabled) | External provider | External provider |
| User Self-Service | Wicket member portal | External provider portal | External provider portal |
| Complexity | Lower | Medium (requires middleware) | Medium (requires app code) |
| Flexibility | Lower | Lower | Higher |
Testing Delegated Authentication
1. Verify CAS Delegation Works
Steps:
- Implement standard CAS authentication in your application
- Test with standard Wicket CAS (should work)
- Ask Wicket team to configure delegation to external provider
- Test again — should redirect to external provider login
- Authenticate with external provider
- Verify you're logged into your application
- 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:
- User visits application → redirects to CAS
- CAS redirects to external provider (B2C, Auth0, etc.)
- User authenticates with external provider
- External provider returns to CAS
- CAS returns ticket to application
- Application validates ticket
- Application receives personUuid
- 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_slugin middleware matches Wicket configuration