Configuring SAML with Microsoft Active Directory Federation Services (ADFS)

This document applies to the following versions of Microsoft Active Directory Federation Services (ADFS):

  • ADFS 2.1 (Windows Server 2012)
  • ADFS 3.0 (Windows Server 2012 R2)
  • ADFS 4.0 (Windows Server 2016)

These instructions guide you through configuring Sourcegraph as a relying party (RP) of ADFS, which enables users to authenticate to Sourcegraph using their Active Directory credentials.

Pre-requisites

  • Active Directory instance where all users have email and username attributes.
  • An instance of ADFS running on Windows Server, joined to your Active Directory domain.
  • Sourcegraph should be configured to use HTTPS.
  • Ensure that externalURL in site config meets the followingcriteria:
    • It is the URL used by end users (no trailing slash).
    • It is HTTPS.

1. Add Sourcegraph as a relying party (RP) to ADFS

These steps should be completed on the Windows Server instance with ADFS installed.

  1. Open Server Manager.
  2. In the upper right corner, click Tools > AD FS Management. This should open the AD FSManagement tool in a new window.
  3. In the sidebar of the AD FS Management tool, right-click Relying Party Trusts > Add RelyingParty Trust... This should open the Add Relying Party Trust Wizard.
  4. Proceed through the Add Relying Party Trust Wizard as follows:
    • Welcome (Page 1): Leave as is and click Start.
    • Select Data Source (Page 2)
    • Specify Display Name (Page 3)
      • Enter "Sourcegraph" as the display name (any value will do) and click Next.
    • Choose Issuance Authorization Rules (Page 4)
      • Ensure Permit everyone is selected (the default) and click Next.
    • Ready to Add Trust (Page 5)
      • Click Next.
    • Finish (Page 6)
      • Click Close.

If the last step did NOT open the Edit Claim Issuance Policy or Edit Claim Rules window,right-click the item ("Sourcegraph" or whatever you set as the display name) in the Relying PartyTrusts list and click Edit Claim Issuance Policy. In the "Issuance Transform Rules" tab of thiswindow, add the 2 following rules:

Claim Rule 1: Send User Info

Click Add Rule... and proceed through the "Add Transform Claim Rule Wizard" as follows:

  • Choose Rule Type (Page 1)
    • Claim rule template: Send LDAP Attributes as Claims
    • Click Next
  • Configure Claim Rule (Page 2)
    • Claim rule name: Send User Info (any value is OK)
    • Attribute store: Active Directory
    • Mapping of LDAP attributes to outgoing claim types:
      E-Mail-Addresses -> E-Mail Address
      Display-Name -> Common Name
      SAM-Account-Name -> Name (optional, username will be derived from email if omitted)
    • Click Finish.

Claim Rule 2: Email to NameID

Click Add Rule... and proceed through the "Add Transform Claim Rule Wizard" as follows:

  • Choose Rule Type (Page 1)
    • Claim rule template: Transform an Incoming Claim
    • Click Next.
  • Configure Claim Rule (Page 2):
    • Claim rule name: Email to NameID
    • Incoming claim type: E-Mail Address
    • Outgoing claim type: Name ID
    • Outgoing name ID format: Persistent identifier
    • Select Pass through all claim values.
    • Click Finish.

Click OK to apply the new claim rules and close the window.

2. Add the SAML auth provider to Sourcegraph site config

Add a SAML auth provider that points to your ADFS server's SAML metadata URL. Thistypically contains the path /federationmetadata/2007-06/federationmetadata.xml. Example:

{
  // ...
  "externalURL": "https://sourcegraph.example.com",
  "auth.providers": [
    {
      "type": "saml",
      "configID": "ms_adfs"
      "identityProviderMetadataURL": "https://adfs.example.com/federationmetadata/2007-06/federationmetadata.xml"
    }
  ]
}

Authenticate to Sourcegraph using ADFS

All configuration is now complete. Let's test that it works.

  1. Visit https://sourcegraph.example.com. (If you were already signed in, sign out ofSourcegraph before doing so.)
  2. Sign into Sourcegraph using ADFS. If ADFS is the only auth.provider entry, you should beautomatically redirected to the sign-in page. Otherwise, click on the SAML sign-in button.
  3. After signing into ADFS, you should be redirected back to Sourcegraph and signed in.

Troubleshooting

When troubleshooting, we recommend setting the env var INSECURE_SAML_LOG_TRACES=1 on thesourcegraph/server Docker container (or the sourcegraph-frontend pod if Sourcegraph is deployedto a Kubernetes cluster). This logs all SAML requests and responses.

Add Relying Party Trust fails on Select Data Source page

This section covers troubleshooting options if the "Import data about the relying party publishedonline or a local network" option fails on the Select Data Source page of the Add RelyingParty Trust Wizard.

First, check that the Federation metadata address value (which should look likehttps://sourcegraph.example.com/.auth/saml/metadata) is accessible by navigating to it in your webbrowser. If this fails, then something is likely misconfigured in Sourcegraph. Check that you haveat most 1 SAML auth provider configured (auth.providers in siteconfig) or contact support for further guidance.

If the endpoint works in your browser, it downloads a metadata XML file. This indicates theendpoint is working, but is inaccessible from ADFS (likely due to a firewall issue or ADFS notrespecting Sourcegraph's TLS certificate due to it being self-signed or from an unrecognizedCertificate Authority). If this is the case, you have a few options:

  • Select "Import data about the relying party from a file" on the "Select Data Source" page andupload the metadata XML file manually.
  • Select "Enter data about the relying party manually" on the "Select Data Source" page. Do thefollowing on the subsequent pages of the wizard:
    • Specify Display Name: Sourcegraph
    • Configure Certificate: Leave as is
    • Configure URL: Check "Enable support for the SAML 2.0 WebSSO protocol". Set the "Relying partySAML 2.0 SSO service URL" to: https://sourcegraph.example.com/.auth/saml/acs
    • Configure Identifiers: Add https://sourcegraph.example.com/.auth/saml/metadata as a relyingparty trust identifier.
      IMPORTANT: ensure your externalURL is set to exactly the root URL of the relying partytrust identifier, (including the URL scheme)
    • For the remaining pages in the wizard, follow the normal steps.
  • Fix the connectivity issue from ADFS to Sourcegraph by adding the appropriate firewall rule or byauthorizing Sourcegraph's TLS certificate on the Windows Server host running ADFS.

Error prefetching SAML service provider metadata

If you notice Error prefetching SAML service provider metadata errors in the Sourcegraph logs,this indicates that Sourcegraph cannot fetch the URL specified in the identityProviderMetadataURL field of the ADFS SAML auth provider config. Navigate to this URL in your web browser. If it errors,check the URL for typos, or there might be an issue with the accessibility of ADFS.

If it succeeds, it should download a federationmetadata.xml file. This indicates that ADFS isaccessible from your browser, but not from the container running Sourcegraph (probably due to afirewall rule or due to Sourcegraph's host not respecting the TLS certificate of ADFS). You have twooptions:

  • Open the federationmetadata.xml file, transform it into a JSON string (using a tool likehttps://json-escape-text.now.sh), and set it in the identityProviderMetadata field of theauth.provider SAML config. You can then delete the identityProviderMetadataURL field.
  • Fix the connectivity issue from Sourcegraph to ADFS by adding the appropriate firewall rule, orauthorizing the ADFS TLS certificate on the container running Sourcegraph.

Error on ADFS login page

This section covers troubleshooting tips if the following is true:

  • You have completed the requisite SAML config on both ADFS and Sourcegraph without errors.
  • On sign-in, users arrive at an ADFS error page that says something like "An error occurred".
  1. On Windows Server, open Event Viewer.
  2. In the lefthand sidebar, click Application and Services Logs > AD FS > Admin.
  3. Find the event corresponding to the failed login. This should have Level "Error".

The error log message will indicate something about the root cause of the error. A common errormessage is The requested relying party trust '<URL>' is unspecified or unsupported. If this is theerror, double-check the relying party identifiers of the Relying Party Trust entry in ADFS:

  • Open AD FS Management.
  • In the sidebar, click Relying Party Trusts.
  • Right-click the row corresponding to Sourcegraph, click "Properties".
  • In the properties editor popup, click the "Identifiers" tab. Examine the list of relying partyidentifiers to ensure there is an entry that matches the relying party trust URL from the EventViewer error.

Other troubleshooting

See SAML troubleshooting for more tips.