BoxLang 🚀 A New JVM Dynamic Language Learn More...

cbsso

v3.4.0+19 Modules

cbSSO

Welcome to cbSSO a ColdBox module to help integrate SSO into your application easily.

Bundled in this module are several SSO provider implementations that allow you to quickly and easily integrate with Identity Providers such as Microsoft, Google, GitHub or Facebook using standard protocols like SAML and oAuth.

To install run

box install cbsso

Once installed you can configure your settings like so

// config/modules/cbsso.cfc
component {
    function configure(){
        return {
            "providers": [
                {
                    type: "GoogleProvider@cbsso",
                    clientId: getJavaSystem().getProperty( "GOOGLE_CLIENT_ID" ),
                    clientSecret: getJavaSystem().getProperty( "GOOGLE_CLIENT_SECRET" )
                }
            ]
        };
    }
}

Your app now has the ability to direct users to Google for authentication!

SAML request replay cache

The Microsoft SAML provider stores outstanding authentication request IDs in a CacheBox cache. By default, cbSSO creates an application cache named cbssoSAMLRequests with a 10-minute timeout and a maximum of 10,000 entries.

For a clustered deployment, register a distributed CacheBox cache and select it in the cbSSO module settings:

// config/CacheBox.cfc
component {
    function configure(){
        cacheBox = {
            caches: {
                samlRequests: {
                    provider: "your.distributed.CacheBoxProvider",
                    properties: {
                        // Provider-specific settings go here
                    }
                }
            }
        };
    }
}

// config/modules/cbsso.cfc
component {
    function configure(){
        return {
            "samlRequestCacheName": "samlRequests",
            "providers": [
                // Provider configuration
            ]
        };
    }
}

When samlRequestCacheName is set, the named cache must already be registered with CacheBox when cbSSO activates; otherwise module activation fails rather than silently falling back to local memory.

SAML signing certificates

The Microsoft SAML provider reads its signing certificates from federationMetadataURL on first use and re-reads them every 60 minutes, so a rotated IdP certificate is picked up without a restart. Set certificateRefreshMinutes on the provider definition to change the interval. If a refresh fails, the certificates already held stay in use and the refresh is retried after 5 minutes.

For more complete documentation covering features and implementation check out our documentation site cbsso.ortusbooks.com.

Ortus Sponsors

ColdBox is a professional open-source project and it is completely funded by the community and Ortus Solutions, Corp. Ortus Patreons get many benefits like a cfcasts account, a FORGEBOX Pro account and so much more. If you are interested in becoming a sponsor, please visit our patronage page: https://patreon.com/ortussolutions

THE DAILY BREAD

"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.


Unreleased

3.4.0 - 2026-11-09

Fixed

  • Re-read the SAML provider's federation metadata every certificateRefreshMinutes (default 60) instead of once per application lifetime. After an IdP rotated its signing certificate, every login failed until the application restarted. A failed refresh keeps the certificates already held and retries after 5 minutes.

  • Report a failed login, rather than an unhandled error, when the SAML provider cannot initialise OpenSAML or fetch its metadata in processAuthorizationEvent.

  • Redirect to errorRedirect when a provider cannot build its authentication request in Auth.start, instead of an unhandled error. Since OpenSAML initialisation and the metadata fetch moved to first use, an unreachable metadata URL surfaced here.

3.3.0 - 2026-11-07

Fixed

  • Read SAML identity only from the Assertion's own Subject and AttributeStatement. The extraction searched every descendant of the Assertion, including its enveloped ds:Signature, which the signature does not cover. A sender could add a Subject or Attribute to ds:KeyInfo of a validly signed assertion and have it read in place of the signed one.

  • Parse SAML documents as received instead of stripping xmlns="..." with a regex first. Comments are outside the signed content, and comments shaped like <!--xmlns="-->...<!--"--> steered the regex into deleting part of a signed NameID or claim value.

  • Require hyper ^8.0.1. hyper 7.x calls interceptorService.processState(), which ColdBox 8 removed, so every OAuth HTTP call (token exchange, JWKS, profile) threw on ColdBox 8. hyper 8.0.1+ calls announce() when available and still falls back to processState() on older ColdBox. Fixes #12.

  • Resolve bundled OpenSAML classes through cbjavaloader and register this module's /lib, so the jar is available without a server-wide classpath entry.

  • Set the thread context classloader during OpenSAML initialization and assertion verification so BoxLang can discover service and cryptography providers.

  • Retry certificate loading after transient metadata failures instead of leaving a provider permanently without certificates.

  • Publish the SAML generator and validator only after OpenSAML initialization succeeds, allowing failed initialization to be retried.

  • Report MicrosoftSAMLProvider.MissingConfiguration when federationMetadataURL is unset.

  • Raise bundled XML Security, Woodstox, HttpClient, Commons IO, and Velocity dependencies past the CVEs addressed in #28.

Changed

  • Initialize OpenSAML and fetch federation metadata on first use rather than during module registration, avoiding jar loading and IdP requests during application boot.
  • Isolate provider registration so one provider's initialization failure does not prevent other providers or the application from loading.
  • Namespace pending SAML request cache keys by application name so applications sharing a distributed cache cannot accept each other's request IDs.

3.0.0 - 2026-08-25

Added

  • Add getClaims() and getClaim() authorization response accessors.
  • Add getNameId() and getNameIdFormat() authorization response accessors.
  • Include claims, NameID, and NameID format in SAMLParsingService.extractIdentity().
  • Populate SAML claims only after successful response validation.

Changed

  • Request persistent SAML NameIDs.
  • Reject SAML responses larger than 1 MB before parsing.
  • BREAKING Fix SSOAuthorizationResponse.getName() to return Name, with a first/last name fallback.
  • Resolve the requested provider in Auth's preHandler.
  • BREAKING Make SAML display-name claims optional; use objectidentifier or NameID for identification.
  • BREAKING Replace extractUserInfo() with extractStatus() and extractIdentity().
  • Reject transient NameIDs when no other subject identifier is available.

Fixed

  • SECURITY Harden SAML XML parsing against XXE, DOCTYPE declarations, non-XML input, and deeply nested documents.
  • SECURITY Require a successful response with one signed, non-encrypted assertion and a matching issuer.
  • SECURITY Bind assertions to the configured audience and ACS recipient; require bearer confirmation and an AuthnStatement.
  • SECURITY Validate the SAML signature profile and bind its reference to the validated assertion.
  • SECURITY Enforce assertion and bearer confirmation validity windows, including a required expiry.
  • Add metadata fetch timeouts and robust, namespace-aware certificate parsing.
  • Improve signature verification errors and preserve cached certificates when metadata refreshes fail.
  • Read SAML identity only from the validated assertion.
  • Report clear errors for documents that are not SAML responses.
  • Match prefixed SAML claims and collect repeated or multi-valued claims.
  • #16 Fix missing-provider handling and events.
  • #17 Initialize failed authorization response properties safely.
  • Return an empty struct from getRawResponseData() when no response exists.

2.1.0 - 2026-05-08

  • Fix several bugs
  • Change SAMLParser to respect both claims/emailaddress and claims/name

2.0.0 - 2025-12-05

1.0.7 - 2024-09-05

1.0.6 - 2024-09-04

1.0.5 - 2024-09-04

1.0.4 - 2024-09-04

1.0.3 - 2024-09-04

1.0.2 - 2024-09-04

1.0.1 - 2024-09-04

1.0.0 - 2024-09-04

  • Add support for several SSO IP integrations

$ box install cbsso

No collaborators yet.
     
  • {{ getFullDate("2024-09-04T10:49:04-05:00") }}
  • {{ getFullDate("2026-11-09T11:31:36-06:00") }}
  • 2,632
  • 9,161