<commit_before># Single sign-on with Azure Active Directory (Azure AD)

You can use [Azure Active Directory](https://azure.microsoft.com/en-us/services/active-directory/#overview) as an SSO provider for your Buildkite organization. To complete this tutorial, you need admin privileges for both Azure and Buildkite.

<div class="Docs__note">
  <p>You can also set up SSO providers manually with GraphQL. See the <a href="/docs/integrations/sso/sso-setup-with-graphql">SSO Setup with GraphQL Guide</a> for detailed instructions and code samples.</p>
</div>

{:toc}

## Step 1. Create a Buildkite SSO provider

In your [Buildkite Organization Settings](https://buildkite.com/organizations/~/settings), click _Single Sign On_, then choose the custom SAML provider from the available options:

<%= image "sso-settings.png", width: 1716/2, height: 884/2, alt: "Screenshot of the Buildkite SSO Settings Page" %>

1. Choose the _Provide IdP Metadata Later_ option when configuring your custom SAML provider
2. Copy the Assertion Consumer Service (ACS) URL for use in [Step 2](#step-2-add-buildkite-in-azure-ad)

## Step 2. Add Buildkite in Azure AD

In your [Azure Admin Console](https://portal.azure.com/), follow these instructions:

1. Choose _Azure Active Directory_, and under _Quick actions_, choose _Add enterprise application_.
2. Click _+ Create your own application_.
3. Give your application a name, for example 'Buildkite'.
4. Choose _Integrate any other application you don't find in the gallery (Non-gallery)_ and click _Create_.
5. Choose _Set up single sign on_, then _SAML_, then in the _Basic SAML Configuration_ box, choose _Edit_.
6. Enter the following configuration and save:
    * _Identifier (Entity ID)_: `https://buildkite.com`
    * _Reply URL (Assertion Consumer Service URL)_: the ACS URL you copied in [Step 1](#step-1-create-a-buildkite-sso-provider)
7. Copy the _App Federation Metadata Url_ value from the _SAML Signing Certificate_ box for use in [Step 3](#step-3-update-your-buildkite-sso-provider).

## Step 3. Update your Buildkite SSO provider

On your [Buildkite Organization Settings](https://buildkite.com/organizations/~/sso) _Single Sign On_ page, select the custom SAML provider from the list of _Configured SSO Providers_.

1. Click the _Edit Provider_ button, choose the _Configure Using IdP Meta Data URL_ option, and enter the _App Federation Metadata Url_ you copied in Step 2.
2. Save your new settings. Buildkite returns you to your custom SAML provider page.

## Step 4. Perform a test login

On your Custom SAML provider page, click _Perform Test Login_ to verify that SSO is working correctly before you activate it for your organization members.

If you receive an error from Microsoft about the user not being assigned to the application, you can assign an initial user:

1. In your Azure Admin Console, select the new _Buildkite_ enterprise app.
2. Choose _Users and groups_ from the navigation sidebar.
3. Click _Add user/group_.
4. Select the user and click _Assign_.

Then, on your [Buildkite Organization Settings](https://buildkite.com/organizations/~/sso) _Single Sign On_ page, select the Custom SAML provider from the list of _Configured SSO Providers_, and retry the test login.

## Step 5. Enable the new SSO provider

Once you've [performed a test login](#step-4-perform-a-test-login) you can enable your SSO provider using the _Enable_ button. Enabling the SSO provider will not force a log out of any signed in users, but will cause all new or expired sessions to authorize through Azure AD before accessing any organization data.

<div class="Docs__troubleshooting-note">
  <p>If you need to edit or update your Azure Active Directory provider settings, you will need to <a href="/docs/integrations/sso#disabling-and-removing-sso">disable the SSO provider</a> first.</p>
</div>

## Using SCIM to provision and manage users

Enterprise customers can automatically add and remove user accounts from their Buildkite organization using the SCIM provisioning settings in Azure AD.

### Supported SCIM features

* Create users
* Deactivate users (deprovisioning)

<div class="Docs__note">
  <p>Buildkite does not bill you for users that you add to Azure AD until they sign in to your Buildkite organization.</p>
</div>

### Configuration instructions

Adding and removing users accounts in Azure AD is called provisioning. You need an enabled Azure AD SSO Provider for your Buildkite Organization before you can set up SCIM provisioning.

<div class="Docs__note">
  <p>User deprovisioning is an Enterprise only feature that needs to be enabled. Please contact support at <EMAIL> to have this enabled.</p>
</div>

After enabling your Azure AD SSO provider in Buildkite, get the _Base URL_ and _API Token_ from your Azure AD SSO provider settings:

<%= image "azuread-scim-settings.png", width: 1440/2, height: 548/2, alt: "Screenshot of the Buildkite Settings SCIM Deprovisioning section" %>

Then go to your [Azure Admin Console](https://portal.azure.com/) and select the new Buildkite enterprise app to set up provisioning:

1. Choose _Provisioning_ from the navigation sidebar, then click _Get started_.
2. Select _Automatic_ provisioning mode and enter the following details:
    * _Tenant URL_: the Base URL from your Buildkite SSO Provider settings
    * _Secret Token_: the API Token from your Buildkite SSO Provider settings
3. Click _Test Connection_, and when you receive confirmation the settings are valid, save.
4. Disable group synchronization:
    1. Expand _Mappings_, then click _Provision Azure Active Directory Groups_.
    2. Toggle _Enabled_ to _No_ and click _Save_.
5. Customize the User mappings:
    1. Expand _Mappings_, then click _Provision Azure Active Directory Users_.
    2. Keep the following four mappings, and delete any others:
        - _userPrincipalName_ to _userName_
        - _Switch([IsSoftDeleted], , "False", "True", "True", "False")_ to _active_
        - _givenName_ to _name.givenName_
        - _surname_ to _name.familyName_
6. Toggle _Provisioning Status_ to _On_ and save.
7. Return to the _Provisioning_ menu of your Azure AD enterprise app and view the _Current cycle status_ section:
    * If provisioning is working, this will say _Initial cycle completed_.
    * If errors are displayed, click _View provisioning logs_ for more details on what went wrong.

## SAML user attributes

<%= render_markdown partial: 'integrations/sso/saml_user_attributes' %><commit_msg>Fix "givenName" spelling by wrapping in code<commit_after># Single sign-on with Azure Active Directory (Azure AD)

You can use [Azure Active Directory](https://azure.microsoft.com/en-us/services/active-directory/#overview) as an SSO provider for your Buildkite organization. To complete this tutorial, you need admin privileges for both Azure and Buildkite.

<div class="Docs__note">
  <p>You can also set up SSO providers manually with GraphQL. See the <a href="/docs/integrations/sso/sso-setup-with-graphql">SSO Setup with GraphQL Guide</a> for detailed instructions and code samples.</p>
</div>

{:toc}

## Step 1. Create a Buildkite SSO provider

In your [Buildkite Organization Settings](https://buildkite.com/organizations/~/settings), click _Single Sign On_, then choose the custom SAML provider from the available options:

<%= image "sso-settings.png", width: 1716/2, height: 884/2, alt: "Screenshot of the Buildkite SSO Settings Page" %>

1. Choose the _Provide IdP Metadata Later_ option when configuring your custom SAML provider
2. Copy the Assertion Consumer Service (ACS) URL for use in [Step 2](#step-2-add-buildkite-in-azure-ad)

## Step 2. Add Buildkite in Azure AD

In your [Azure Admin Console](https://portal.azure.com/), follow these instructions:

1. Choose _Azure Active Directory_, and under _Quick actions_, choose _Add enterprise application_.
2. Click _+ Create your own application_.
3. Give your application a name, for example 'Buildkite'.
4. Choose _Integrate any other application you don't find in the gallery (Non-gallery)_ and click _Create_.
5. Choose _Set up single sign on_, then _SAML_, then in the _Basic SAML Configuration_ box, choose _Edit_.
6. Enter the following configuration and save:
    * _Identifier (Entity ID)_: `https://buildkite.com`
    * _Reply URL (Assertion Consumer Service URL)_: the ACS URL you copied in [Step 1](#step-1-create-a-buildkite-sso-provider)
7. Copy the _App Federation Metadata Url_ value from the _SAML Signing Certificate_ box for use in [Step 3](#step-3-update-your-buildkite-sso-provider).

## Step 3. Update your Buildkite SSO provider

On your [Buildkite Organization Settings](https://buildkite.com/organizations/~/sso) _Single Sign On_ page, select the custom SAML provider from the list of _Configured SSO Providers_.

1. Click the _Edit Provider_ button, choose the _Configure Using IdP Meta Data URL_ option, and enter the _App Federation Metadata Url_ you copied in Step 2.
2. Save your new settings. Buildkite returns you to your custom SAML provider page.

## Step 4. Perform a test login

On your Custom SAML provider page, click _Perform Test Login_ to verify that SSO is working correctly before you activate it for your organization members.

If you receive an error from Microsoft about the user not being assigned to the application, you can assign an initial user:

1. In your Azure Admin Console, select the new _Buildkite_ enterprise app.
2. Choose _Users and groups_ from the navigation sidebar.
3. Click _Add user/group_.
4. Select the user and click _Assign_.

Then, on your [Buildkite Organization Settings](https://buildkite.com/organizations/~/sso) _Single Sign On_ page, select the Custom SAML provider from the list of _Configured SSO Providers_, and retry the test login.

## Step 5. Enable the new SSO provider

Once you've [performed a test login](#step-4-perform-a-test-login) you can enable your SSO provider using the _Enable_ button. Enabling the SSO provider will not force a log out of any signed in users, but will cause all new or expired sessions to authorize through Azure AD before accessing any organization data.

<div class="Docs__troubleshooting-note">
  <p>If you need to edit or update your Azure Active Directory provider settings, you will need to <a href="/docs/integrations/sso#disabling-and-removing-sso">disable the SSO provider</a> first.</p>
</div>

## Using SCIM to provision and manage users

Enterprise customers can automatically add and remove user accounts from their Buildkite organization using the SCIM provisioning settings in Azure AD.

### Supported SCIM features

* Create users
* Deactivate users (deprovisioning)

<div class="Docs__note">
  <p>Buildkite does not bill you for users that you add to Azure AD until they sign in to your Buildkite organization.</p>
</div>

### Configuration instructions

Adding and removing users accounts in Azure AD is called provisioning. You need an enabled Azure AD SSO Provider for your Buildkite Organization before you can set up SCIM provisioning.

<div class="Docs__note">
  <p>User deprovisioning is an Enterprise only feature that needs to be enabled. Please contact support at <EMAIL> to have this enabled.</p>
</div>

After enabling your Azure AD SSO provider in Buildkite, get the _Base URL_ and _API Token_ from your Azure AD SSO provider settings:

<%= image "azuread-scim-settings.png", width: 1440/2, height: 548/2, alt: "Screenshot of the Buildkite Settings SCIM Deprovisioning section" %>

Then go to your [Azure Admin Console](https://portal.azure.com/) and select the new Buildkite enterprise app to set up provisioning:

1. Choose _Provisioning_ from the navigation sidebar, then click _Get started_.
2. Select _Automatic_ provisioning mode and enter the following details:
    * _Tenant URL_: the Base URL from your Buildkite SSO Provider settings
    * _Secret Token_: the API Token from your Buildkite SSO Provider settings
3. Click _Test Connection_, and when you receive confirmation the settings are valid, save.
4. Disable group synchronization:
    1. Expand _Mappings_, then click _Provision Azure Active Directory Groups_.
    2. Toggle _Enabled_ to _No_ and click _Save_.
5. Customize the User mappings:
    1. Expand _Mappings_, then click _Provision Azure Active Directory Users_.
    2. Keep the following four mappings, and delete any others:
        - `userPrincipalName` to `userName`
        - `Switch([IsSoftDeleted], , "False", "True", "True", "False")` to `active`
        - `givenName` to `name.givenName`
        - `surname` to `name.familyName`
6. Toggle _Provisioning Status_ to _On_ and save.
7. Return to the _Provisioning_ menu of your Azure AD enterprise app and view the _Current cycle status_ section:
    * If provisioning is working, this will say _Initial cycle completed_.
    * If errors are displayed, click _View provisioning logs_ for more details on what went wrong.

## SAML user attributes

<%= render_markdown partial: 'integrations/sso/saml_user_attributes' %>
{'fraction_non_alphanumeric': 0.07007007007007007, 'fraction_numerical': 0.008778008778008778, 'mean_word_length': 4.4686315789473685, 'pattern_counts': {'":': 0, '<': 51, '<?xml version=': 0, '>': 51, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2750264', 'n_tokens_mistral': 3710, 'n_tokens_neox': 3543, 'n_words': 1736}