<commit_before># SAML with a Custom Provider

Any identify provider that supports SAML 2.0 can be used to authorize access to your Buildkite organization. If there isn't a Buildkite guide for your chosen provider, you can set up SAML using the instructions below.

<%= toc %>

## Set up your provider

There are two ways to set up your custom provider: using the Buildkite meta-data XML to your identity provider, or manually adding your Buildkite data into your identity provider. After setting up your provider, you'll need to send the Buildkite team your [application information](#send-your-application-information-to-buildkite).

Self-service SSO provisioning in Buildkite is available via our GraphQL explorer. For further information, see the [GraphQL SSO Setup Guide](/docs/tutorials/graphql-sso). 

<div class="Docs__note">
<p class="Docs__note__heading">Before starting your provider setup</p>
<p>Email the Buildkite team at <EMAIL> to request your unique SSO service URL, you will need this during set up.</p>
</div>

### Setting up with meta-data

The Buildkite SAML meta data endpoint contains all the information you need to set up SAML with any provider.

If your provider has an XML URL field, you can enter the buildkite meta-data URL directly: <a href="https://buildkite.com/user/authorize/saml/metadata">https://buildkite.com/user/authorize/saml/metadata</a>.

### Setting up manually

Manual setup is different for each provider, however it usually requires the following fields:

<table>
    <tr>
        <td>Single Sign-On URL</td>
        <td>
            Your unique SSO service URL from Buildkite that will be sending requests to your identity provider. 
        </td>
    </tr>
    <tr>
        <td>Entity Identifier</td>
        <td>
            https://buildkite.com  
        </td>
    </tr>
    <tr>
        <td>Name ID</td>
        <td>
            The field used to identify users.
            Email Address.
        </td>
    </tr>
</table>

If your custom provider needs further information, please email <EMAIL>.

## Send your application information to Buildkite

After completing your identity provider's setup process, email <EMAIL> with the following information:

<table>
    <tr>
        <td>Domain name</td>
        <td>
            The domain you use with your SAML provider for which you want to enable SSO. This must match one of the emails you have verified with your Buildkite account.
        </td>
    </tr>
    <tr>
        <td>organization slug</td>
        <td>
            The Buildkite organization for which you want to enable SSO.  
        </td>
    </tr>
    <tr>
        <td>SAML 2.0 Endpoint (HTTP)</td>
        <td>
            The SAML endpoint for your chosen provider.
        </td>
    </tr>
    <tr>
        <td>Issuer URL</td>
        <td>
            The identifing URL of your chosen provider.  
        </td>
    </tr>
    <tr>
        <td>X.509 certificate</td>
        <td>
            The public key certificate for your chosen provider.
        </td>
    </tr>
</table>

When we receive your email, the Buildkite team will:

1. Enable SSO for the specified organization
1. Reply to your email and get you to test that it's all working
1. Deauthorize all the users in the organization, so that everyone will authorize via your chosen provider next time they attempt to access that organization on Buildkite.com

## SAML User Attributes

Buildkite accepts a subset of the SAML attributes from identity providers. The accepted attributes are:

<table>
    <tr>
        <th>
            Attribute
        </th>
        <th>
            Description
        </th>
    </tr>
    <tr>
        <td>
            <code>admin</code>
        </td>
        <td>
            A boolean value that describes whether the user should be provisioned with admin permissions
            Example: true
        </td>
    </tr>
    <tr>
        <td>
            <code>email</code>
        </td>
        <td>
            A string of the user's email address
            Example: "<EMAIL>"
        </td>
    </tr>
    <tr>
        <td>
            <code>name</code>
        </td>
        <td>
            A string of the user's full name
            Example: "<NAME>"
        </td>
    </tr>
    <tr>
        <td>
            <code>teams</code>
        </td>
        <td>
            A comma separated list of team UUIDs. A team's UUID can be found on the Team Settings page in Buildkite. 
            Example: a1aaaa1a-b2bb-cccc-d4dd-aa2aaa6aaaaa,b5bbbbbb-3aaa-dd1d-aaa1-eee4eee6eeee
        </td>
    </tr>
</table>

<commit_msg>Add teams example, fix metadata info and casing<commit_after># SAML with a Custom Provider

Any identify provider that supports SAML 2.0 can be used to authorize access to your Buildkite organization. If there isn't a Buildkite guide for your chosen provider, you can set up SAML using the instructions below.

<%= toc %>

## Set up your provider

There are two ways to set up your custom provider: using the Buildkite meta-data XML to your identity provider, or manually adding your Buildkite data into your identity provider. After setting up your provider, you'll need to send the Buildkite team your [application information](#send-your-application-information-to-buildkite).

Self-service SSO provisioning in Buildkite is available via our GraphQL explorer. For further information, see the [GraphQL SSO Setup Guide](/docs/tutorials/graphql-sso). 

<div class="Docs__note">
<p class="Docs__note__heading">Before starting your provider setup</p>
<p>Email the Buildkite team at <EMAIL> to request your unique SSO service URL, you will need this during set up.</p>
</div>

### Setting up with meta-data

A custom URL containing your organization's metadata can be generated. You can request the URL from <EMAIL> alongside your SSO service URL. The custom endpoint contains all the information you need to set up SAML with any provider.

If your provider has an XML URL field, you can enter the buildkite meta-data URL directly: <a href="https://buildkite.com/user/authorize/saml/metadata">https://buildkite.com/user/authorize/saml/metadata</a>.

### Setting up manually

Manual setup is different for each provider, however it usually requires the following fields:

<table>
    <tr>
        <td>Single Sign-On URL</td>
        <td>
            Your unique SSO service URL from Buildkite that will be sending requests to your identity provider. 
        </td>
    </tr>
    <tr>
        <td>Entity Identifier</td>
        <td>
            https://buildkite.com  
        </td>
    </tr>
    <tr>
        <td>Name ID</td>
        <td>
            The field used to identify users.
            Email Address.
        </td>
    </tr>
</table>

If your custom provider needs further information, please email <EMAIL>.

## Send your application information to Buildkite

After completing your identity provider's setup process, email <EMAIL> with the following information:

<table>
    <tr>
        <td>Domain name</td>
        <td>
            The domain you use with your SAML provider for which you want to enable SSO. This must match one of the emails you have verified with your Buildkite account.
        </td>
    </tr>
    <tr>
        <td>Organization slug</td>
        <td>
            The Buildkite organization for which you want to enable SSO.  
        </td>
    </tr>
    <tr>
        <td>SAML 2.0 Endpoint (HTTP)</td>
        <td>
            The SAML endpoint for your chosen provider.
        </td>
    </tr>
    <tr>
        <td>Issuer URL</td>
        <td>
            The identifing URL of your chosen provider.  
        </td>
    </tr>
    <tr>
        <td>X.509 certificate</td>
        <td>
            The public key certificate for your chosen provider.
        </td>
    </tr>
</table>

When we receive your email, the Buildkite team will:

1. Enable SSO for the specified organization
1. Reply to your email and get you to test that it's all working
1. Deauthorize all the users in the organization, so that everyone will authorize via your chosen provider next time they attempt to access that organization on Buildkite.com

## SAML User Attributes

Buildkite accepts a subset of the SAML attributes from identity providers. The accepted attributes are:

<table>
    <tr>
        <th>
            Attribute
        </th>
        <th>
            Description
        </th>
    </tr>
    <tr>
        <td>
            <code>admin</code>
        </td>
        <td>
            A boolean value that describes whether the user should be provisioned with admin permissions
            Example: true
        </td>
    </tr>
    <tr>
        <td>
            <code>email</code>
        </td>
        <td>
            A string of the user's email address
            Example: "<EMAIL>"
        </td>
    </tr>
    <tr>
        <td>
            <code>name</code>
        </td>
        <td>
            A string of the user's full name
            Example: "<NAME>"
        </td>
    </tr>
    <tr>
        <td>
            <code>teams</code>
        </td>
        <td>
            A comma separated list of team UUIDs. A team's UUID can be found on the Team Settings page in Buildkite. 
            Example: `a1aaaa1a-b2bb-cccc-d4dd-aa2aaa6aaaaa,b5bbbbbb-3aaa-dd1d-aaa1-eee4eee6eeee`
        </td>
    </tr>
</table>

When using the `teams` attribute, you can also specify roles. The `maintainer` or `member` role can be appended to the team UUID. 

For example, the following code will specify the member role for the first team and the maintainer role for the second team:

```
teams="b5bbbbbb-3aaa-dd1d-aaa1-eee4eee6eeee/member, a1aaaa1a-b2bb-cccc-d4dd-aa2aaa6aaaaa/maintainer"
```

{'fraction_non_alphanumeric': 0.08769755190579485, 'fraction_numerical': 0.005784526391901663, 'mean_word_length': 2.2909585316111487, 'pattern_counts': {'":': 0, '<': 216, '<?xml version=': 0, '>': 216, 'https://': 6, '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': '6325467', 'n_tokens_mistral': 2852, 'n_tokens_neox': 2761, 'n_words': 1146}