coldbox-security-sso

Configure OAuth2/OpenID Connect SSO for ColdBox applications using the cbsso module.

1|Updated Apr 10, 2026
One-click install
npx skills add https://github.com/ColdBox/skills --skill coldbox-security-sso
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: coldbox-security-sso
Source: https://github.com/ColdBox/skills/tree/main/security/sso-integration
Command: npx skills add https://github.com/ColdBox/skills --skill coldbox-security-sso

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

SSO integration for ColdBox apps using the cbsso module and OAuth2/OpenID Connect, enabling users to authenticate with external providers while maintaining local user mappings.

Core Features & Use Cases

  • OAuth2 / OpenID Connect based authentication with external providers (Google, Azure AD, Okta, GitHub, etc.)
  • Provider configuration, including client IDs, secrets, and redirect URIs
  • End-to-end login flow: redirect to provider, handle callback, map to local users, and establish sessions
  • User provisioning and metadata syncing when new users authenticate via SSO
  • UI integration: social login buttons and provider switcher for the login page
  • Route and security best practices: CSRF protection, token validation, HTTPS redirects

Quick Start

Configure your cbsso providers in config/ColdBox.cfc and define routes for /sso/login, /sso/callback, and /sso/logout, then trigger /sso/login/google to start a sign-in.

Frequently Asked Questions about coldbox-security-sso

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add OAuth2 single sign-on to a ColdBox application?

You can enable single sign-on in a ColdBox app by wiring the cbsso module to external identity providers using OAuth2. Configure provider client IDs, secrets, and redirect URIs in module settings to handle login redirects and callback exchanges.

Does ColdBox SSO support Azure AD and Okta authentication?

Yes, ColdBox SSO supports Azure AD and Okta authentication alongside Google and GitHub. It uses OpenID Connect and OAuth2 protocols to integrate with these external providers, managing user provisioning and local identity mapping during the callback exchange.

How does user provisioning work when authenticating via OpenID Connect in ColdBox?

When new users authenticate via OpenID Connect, ColdBox SSO handles user provisioning by mapping external identities to local users. It syncs metadata and establishes sessions automatically after the provider callback exchange completes successfully.

What routes do I need to configure for SSO callbacks in a ColdBox app?

You need to define routes for /sso/login, /sso/callback, and /sso/logout in your ColdBox configuration. Triggering /sso/login/google starts the sign-in flow, directing users to the provider and returning through the callback route.

Can I use ColdBox SSO to add social login buttons to my login page?

Yes, ColdBox SSO includes UI integration features for adding social login buttons and a provider switcher to your login page. This allows users to select from configured providers like Google or GitHub for authentication.

What security measures are needed for OAuth2 redirects in ColdBox SSO?

ColdBox SSO requires CSRF protection, token validation, and HTTPS redirects as security best practices. These measures secure the OAuth2 login flow, callback exchanges, and session management across multiple routes.