> For the complete documentation index, see [llms.txt](https://cbsso.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cbsso.ortusbooks.com/usage/how-it-works.md). # How It Works Even though there are multiple different SSO strategies out in the wild they generally tend to work on similiar principles. A user visits a website (the service provider) and is provided a set of options for authentication (identity providers). The user selects one of the presented identity providers and proceedes to login in and authorize the service provider to access some of their information. The identity provider then redirects the user back to the web application and confirms to the service provider that the user is who they say they are. This module provides the utilities necessary to accommodate this pattern while being flexible enough to allow for the differences between different protocols and identity providers. When installed cbSSO provides some routes to your application. `/cbsso/auth/:providerName/start` This route is used by your application to determine which provider a user has selected and to provide the application a chance to do any work necessary before redirecting to the identity provider service. `/cbsso/auth/:providerName` This route is used as the redirect URI for the identity provider to communicate back to your application. ## SAML request lifecycle When the `MicrosoftSAMLProvider` starts a login, cbSSO generates an AuthNRequest with a unique request ID and stores that ID in the configured CacheBox cache. The identity provider must return the same ID in both the response and its bearer subject confirmation. The response is accepted only after the signed assertion, issuer, audience, ACS recipient, request binding, and validity window have been checked. Claims are then extracted from that verified assertion, and the request ID is consumed from CacheBox. A second delivery of the same valid response is rejected. The default cache is local to the application node. Configure `samlRequestCacheName` with a distributed CacheBox cache when the application runs behind a load balancer; see [Configuration](/usage/configuration.md#saml-request-replay-cache). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cbsso.ortusbooks.com/usage/how-it-works.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.