SAML

Security Assertion Markup Language (SAML) is a common web protocol used to pass authorized credentials between two web applications, a service provider (SP) - Sourcegraph in this instance and an Identity Provider (IdP). This communication is conducted via XML assertions.

Identity Providers

Select your SAML identity provider for setup instructions:

For advanced SAML configuration options, see the saml auth provider documentation.

Add a SAML provider

In Sourcegraph site config, ensure externalURL is set to a value consistent with the URL you used in the previous section in the identity provider configuration.

NOTE: Make sure to use the exact same scheme (http or https), and there should be no trailing slash.
Add an item to auth.providers with type "saml" and either identityProviderMetadataURL or identityProviderMetadata set. The former is preferred, but not all identity providers support it (it is sometimes called "App Federation Metadata URL" or just "SAML metadata URL").

WARNING: There can only be at most 1 element of type saml in auth.providers. Otherwise behavior is undefined. If you have another SAML auth provider configured, remove it from auth.providers before proceeding.

Here are some examples of what your site config might look like:

Example 1:

{
  // ...
  "externalURL": "https://sourcegraph.example.com",
  "auth.providers": [
    {
      "type": "saml",
      "configID": "generic",
      "identityProviderMetadataURL": "https://example.com/saml-metadata"
    }
  ]
}

Example 2:

{
  // ...
  "externalURL": "https://sourcegraph.example.com",
  "auth.providers": [
    {
      "type": "saml",
      "configID": "generic",

      // This is a long XML string you download from your identity provider.
      // You can escape it to a JSON string using a tool like
      // https://json-escape-text.now.sh.
      "identityProviderMetadata": "<?xml version=\"1.0\" encoding=\"utf-8\"?><EntityDescriptor ID=\"_86c6d3fd-e0a9-4b99-b830-40b248003fb9\" entityID=\"https://sts.windows.net/6c1b91af-8e37-4921-bbfa-ef68aa2e2d1e/\" xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\"><Signature xmlns=\"http://www.w3.org/2000/09/xmldsig#\"><SignedInfo><CanonicalizationMethod Algorithm=\"http://www.w3.org/2001/10/xml-exc-c14n#\" /><SignatureMethod Algorithm=\"http://www.w3.org/2001/04/xmldsig-more#rsa-sha256\" /><Reference URI=\"#_86c6d3fd-e0a9-4b99-b830-40b248003fb9\"><Transforms><Transform Algorithm=\"http://www.w3.org/2000/09/xmldsig#enveloped-signature\" /><Transform Algorithm=\"http://www.w3.org/2001/10/xml-exc-c14n#\" /></Transforms><DigestMethod Algorithm=\"http://www.w3.org/2001/04/xmlenc#sha256\" /><DigestValue> ..."
    }
  ]
}

Then, confirm that there are no error messages in:

The sourcegraph-frontend deployment logs for instances using Docker Compose and Kubernetes
The sourcegraph/server container logs for instances using a single docker container

The most likely error message indicating a problem is:

Error prefetching SAML service provider metadata

Use the following filters to restrict how users can create accounts and sign in to your Sourcegraph instance via SAML auth provider.

allowSignup

Allows new users to creating their accounts via SAML authentication, or blocks the sign-up when set to false.

If false, users signing in via SAML must have an existing Sourcegraph account, which will be linked to their SAML identity after the sign-in.

If not set, it will default to true.

  {
    "type": "saml",
    // ...
    "allowSignup": false
  }

allowGroups

Restricts login to members of the allowed SAML groups. By groups we understand any SAML assertion by which we can determine if a user should be allowed to sign-in or sign-up to a sourcegraph account. This SAML assertion attribute needs to return a list of strings.

When not configured or set totrue, sign-in will be allowed. If the list of allowed groups is empty, sign-in is not allowed.

The groupsAttributeName is an optional parameter that can be used to set a different name for the SAML attribute assertion that contains a list of groups the user belongs to. It defaults to "groups" when not provided.

If combined with "allowSignup": true or if allowSignup is not set, only members of the allowed groups can create their accounts in Sourcegraph via SAML authentication. When set with "allowSignup": false, an admin should first create the user account so that the user can login with SAML.

  {
    "type": "saml",
    // ...
    "allowSignup": false,
    "allowGroups": ["sourcegraph"],
    "groupsAttributeName": "mySAMLgroup"
  }

Group names with special characters

Special characters such as the & (ampersand) will be encoded in the XML document, the format used by SAML. For example, if you have a group Dogs & cats set in your Identity Provider, it will be shown as Dogs & cats in the XML assertions.

This is expected - just avoid using the encoded character when adding a group name to the allowGroups array.

Instead of

  {
    "allowGroups":
    [
      "Dogs &amp; cats", // wrong
      "Dogs &gt; cats", // wrong
      "Cats &lt; dogs" // wrong
    ]
  }

Use

  {
    "allowGroups":
    [
      "Dogs & cats", // correct
      "Dogs > cats", // correct
      "Cats < dogs" // correct
    ]
  }

See SAML troubleshooting for more tips.

Troubleshooting

Enable logging in Sourcegraph containers

Set the env var INSECURE_SAML_LOG_TRACES=1 to log all SAML requests and responses on:

The sourcegraph-frontend deployment for instances using Docker Compose and Kubernetes
The sourcegraph/server container for instances using a single docker container

Debugging with your browser

When debugging a problem with SAML its often helpful to use the browser's developer tools to directly observe the XML assertions and their contents. Below are some general pointers on how to collect SAML communications:

Navigate to Sourcegraph in the browser and prepare to attempt a login via SAML
Open the developer tools and navigate to the Network tab and enable the option to preserve logs if it is available
Clear the collection of network logs in the the Network tab and attempt a SAML login
Look for a network request in the Network tab that indicates a SAML request response communication (this might be labeled ACS, or Authn)
Select the network request and observe its headers

You should see something like the image below from a Sourcegraph Okta login, observed via Safari devTools:

Screen Shot 2021-09-15 at 1 13 17 PM The above example does not contain any sensitive information. In a real network response you will often find that the header info in the Network tab has a SAMLResponse field containing XML that has been encoded and/or encrypted.

There are a variety of ways to decompress and decrypt XML. For an easy to use tools we recommend samltool.com, which provides a user friendly UI to accomplish these tasks.

If you're not sure why your SAML isn't working and you've collected the network request and response from your login attempts, please feel free to reach out to our support team at [email protected], please redact any secret keys that may be present in your site configuration or SAML assertions before sharing with us at Sourcegraph.