> 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/providers/built-in-providers/mircosoftsamlprovider.md).

# MicrosoftSAMLProvider

The MicrosoftSAMLProvider gives you the ability to integrate with Microsoft's Entra single sign-on service. You can read more about [Microsoft's Entra AuthNRequest workflow here.](https://learn.microsoft.com/en-us/entra/identity-platform/single-sign-on-saml-protocol)

### Example Configuration

```cfscript
component {
  public any function configure(){
    return {
      "providers" : [
        {
          // name is optional, can be used to control the redirect uri
          // with name:     https://your.app.com/cbsso/auth/entra
          // without name:  https://your.app.com/cbsso/auth/MicrosoftSAMLProvider
          name:         "entra",
          type:         "MicrosoftSAMLProvider@cbsso",

          // these values are configured with Microsoft and available in your app dashboard
          clientId:     "YOUR-CLIENT-ID",
          clientSecret: "YOUR-CLIENT-SECRET",
          authEndpoint: "https://login.microsoftonline.com/YOUR-TENANT-ID/saml2",
          expectedIssuer: "https://sts.windows.net/YOUR-TENANT-ID/",
          federationMetadataURL: "https://login.microsoftonline.com/YOUR-TENANT-ID/federationmetadata/2007-06/federationmetadata.xml"
        }
      ]
    };  
  }
}
```

### Validation and replay protection

`MicrosoftSAMLProvider` accepts a response only after it has passed the following checks:

* The response and assertion issuers match `expectedIssuer`.
* The assertion audience matches the configured `clientId`.
* The assertion's bearer confirmation is addressed to the configured ACS URL. Set `redirectUri` when the default `/cbsso/auth/:providerName` URL is not used.
* The assertion is signed by a certificate from the federation metadata, and its signature reference is bound to the assertion whose claims will be read.
* The response and the accepted bearer subject confirmation echo the AuthNRequest ID that started the flow.
* The assertion has a valid time window. A 60-second clock-skew allowance is applied.
* The response contains exactly one assertion. Encrypted assertions are not supported because cbSSO cannot decrypt them.

Federation metadata is fetched with 10-second connection and request timeouts. The provider cannot validate responses until the metadata has been fetched successfully and at least one IdP signing certificate has been loaded.

Identity is extracted only from the assertion whose signature was verified. Attributes or `NameID` values added elsewhere in the response are not treated as user data. XML documents with a `DOCTYPE`, non-XML input, or a decoded response larger than 1 MiB are rejected before normal response processing.

Each AuthNRequest ID is stored in the CacheBox cache selected by `samlRequestCacheName` and is consumed after successful validation. This prevents a valid response from being replayed and does not require session management. See [SAML request replay cache](/usage/configuration.md#saml-request-replay-cache) for the single-node default and distributed-cache configuration required for clustered deployments.

### Additional Server Configuration

If you are using the `MicrosoftSAMLProvider` you will need to add some java libraries to your server.\
\
If using a CommandBox `server.json` you can do that like so

````
```jsonc
{
    "app":{
        // add this line to ensure the java library is loaded at the appropriate level
        "libDirs":"modules/cbsso/lib"
    }
}
```
````


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://cbsso.ortusbooks.com/providers/built-in-providers/mircosoftsamlprovider.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.