> For the complete documentation index, see [llms.txt](https://docs.bluefletch.com/bluefletch-enterprise/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bluefletch.com/bluefletch-enterprise/product-guides/portal/admin/single-sign-on/azure-setup.md).

# Azure Setup

For organizations using Microsoft Azure Active Directory (AD) as their identity provider and access management service, it is simple and scalable to create users for the BlueFletch Portal website using single sign-on (SSO) through SAML. The BlueFletch Portal can be configured within an organization's Azure Portal as a SAML enterprise application. The resulting metadata should be provided back to BlueFletch to complete the configuration.

Once SSO is configured for the BlueFletch Portal, users who are allowed to access the BlueFletch Portal can login to a new Portal account with their Azure-managed username, and they will be authenticated by Azure AD.

## Configuring SSO with Azure

1. Login to your Azure Portal at <https://portal.azure.com>.
2. Navigate to ***Azure Active Directory*** page.
3. Select Enterprise applications from the panel of Manage options on the left.
4. Press **New Application** and **Create your own application**.
5. Setup the enterprise application with:
   * **Identifier (Entity ID):** "saml.\[*organization's login domain for Azure*]" (e.g. *saml.bluefletch.com*)
   * **Reply URL (Assertion Consumer Service URL):** "<https://ems.bluefletch.com/\\_\\_/auth/handler>"
   * **Sign on URL:** "<https://ems.bluefletch.com>"
6. In **Attributes & Claims**, set the following values to enable email logins to auto-generate BlueFletch Portal user accounts:\
   \
   \&#xNAN;*Required claim:*

   * **Unique User Identifier (Name ID)**
     * *Type:* "SAML"
     * *Value:* "user.userprincipalname"<br>

   *Additional claims:*

   * **EmailAddress**
     * *Type*: "SAML"
     * *Value*: "user.mail"
   * **FirstName**
     * *Type*: "SAML"
     * *Value*: "user.givenname"
   * **LastName**

     * *Type*: "SAML"
     * *Value*: "user.surname"<br>

     ***Note:*** For each *Additional claim*, the claim name is case sensitive and the namespace field should be blank/empty.

     <div align="left"><figure><img src="/files/8RsSwg57vDjE5RkTcG4v" alt=""><figcaption><p><strong>Attributes &#x26; Claims</strong> settings in Microsoft Azure AD</p></figcaption></figure></div>
7. If mapping Azure [groups to Portal roles](/bluefletch-enterprise/product-guides/portal/admin/single-sign-on/portal-setup.md#idp-group-mappings), add a group claim named "Groups" (Portal's code checking for this variable is case-sensitive, so be sure it is spelled with a capital "G").\
   \
   To add a group claim:
   1. Press **Add a group claim**.
   2. For groups to be returned in the claim, select "All groups".
      1. In its documentation, Azure recommends that larger organizations use the "Groups assigned to the application" option to avoid issues due to its per-token group number limit. For more information, consult: <https://docs.azure.cn/en-us/entra/identity-platform/optional-claims?tabs=appui#configure-groups-optional-claims>.
   3. Select "Group ID" or "sAMAccountName" as the source attribute.
      1. Use "Group ID" if using Entra/Azure Active Directory cloud service.
      2. Use "sAMAccountName if using an on-premise Active Directory.

         <div align="left"><figure><img src="/files/fCQ4pL6shs8mkNPvPc6z" alt="" width="563"><figcaption><p>Use sAMAccount only with on-premise Active Directory of the correct version</p></figcaption></figure></div>
   4. Customize the name of the group claim and name it "Groups".
   5. Select the checkbox to expose the claim in JWT tokens.<br>

      <div align="left"><figure><img src="/files/5hR3MTM8r3RXXnuMk7kH" alt="" width="563"><figcaption><p>Customize group claim</p></figcaption></figure></div>
   6. Press **Save**.
8. Retrieve from Azure AD to use in [Portal Setup](/bluefletch-enterprise/product-guides/portal/admin/single-sign-on/portal-setup.md), or provide back to BlueFletch:

   * Federation Metadata XML

   or all of the following:

   * Certificate in Base64
   * Login URL
   * Azure AD Identifier


---

# 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://docs.bluefletch.com/bluefletch-enterprise/product-guides/portal/admin/single-sign-on/azure-setup.md?ask=<question>&goal=<endgoal>
```

`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.