BoxLang 🚀 A New JVM Dynamic Language Learn More...
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!
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.
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.
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
"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12
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.
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.
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.
getClaims() and getClaim() authorization response accessors.getNameId() and getNameIdFormat() authorization response accessors.SAMLParsingService.extractIdentity().SSOAuthorizationResponse.getName() to return Name, with a first/last name fallback.Auth's preHandler.objectidentifier or NameID for identification.extractUserInfo() with extractStatus() and extractIdentity().AuthnStatement.getRawResponseData() when no response exists.
$
box install cbsso