This document applies to the following versions of Microsoft Active Directory Federation Services (ADFS):
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.
externalURL
in site config meets the following
criteria:
These steps should be completed on the Windows Server instance with ADFS installed.
https://sourcegraph.example.com/.auth/saml/metadata
.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 Party Trusts list and click Edit Claim Issuance Policy. In the "Issuance Transform Rules" tab of this window, add the 2 following rules:
Click Add Rule... and proceed through the "Add Transform Claim Rule Wizard" as follows:
Send LDAP Attributes as Claims
Send User Info
(any value is OK)Active Directory
E-Mail-Addresses
-> E-Mail Address
Display-Name
-> Common Name
SAM-Account-Name
-> Name
(optional, username will be derived from email if omitted)Click Add Rule... and proceed through the "Add Transform Claim Rule Wizard" as follows:
Transform an Incoming Claim
Email to NameID
E-Mail Address
Name ID
Persistent identifier
Click OK to apply the new claim rules and close the window.
Add an entry to auth.providers
that points to your ADFS server's SAML metadata URL. This
typically contains the path /federationmetadata/2007-06/federationmetadata.xml
. Example:
{ // ... "externalURL": "https://sourcegraph.example.com", "auth.providers": [ { "type": "saml", "identityProviderMetadataURL": "https://adfs.example.com/federationmetadata/2007-06/federationmetadata.xml" } ] }
Note: there should 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.
Confirm there are no error messages in the Sourcegraph Docker container logs (or the
sourcegraph-frontend
pod logs, if Sourcegraph is deployed to a Kubernetes cluster).
If there are errors, see Troubleshooting: Error prefetching SAML service provider
metadata or Other
troubleshooting.
See the SAML auth provider documentation for the full set of properties that the SAML auth provider supports.
All configuration is now complete. Let's test that it works.
https://sourcegraph.example.com
. (If you were already signed in, sign out of
Sourcegraph before doing so.)auth.provider
entry, you should be
automatically redirected to the sign-in page. Otherwise, click on the SAML sign-in button.When troubleshooting, we recommend setting the env var INSECURE_SAML_LOG_TRACES=1
on the
sourcegraph/server
Docker container (or the sourcegraph-frontend
pod if Sourcegraph is deployed
to a Kubernetes cluster). This logs all SAML requests and responses.
This section covers troubleshooting options if the "Import data about the relying party published online or a local network" option fails on the Select Data Source page of the Add Relying Party Trust Wizard.
First, check that the Federation metadata address value (which should look like
https://sourcegraph.example.com/.auth/saml/metadata
) is accessible by navigating to it in your web
browser. If this fails, then something is likely misconfigured in Sourcegraph. Check that you have
at most 1 SAML auth provider configured (auth.providers
in site
config) or contact support for further guidance.
If the endpoint works in your browser, it downloads a metadata
XML file. This indicates the
endpoint is working, but is inaccessible from ADFS (likely due to a firewall issue or ADFS not
respecting Sourcegraph's TLS certificate due to it being self-signed or from an unrecognized
Certificate Authority). If this is the case, you have a few options:
metadata
XML file manually.externalURL
is set to exactly the root URL of the relying party
trust identifier, (including the URL scheme)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 is
accessible from your browser, but not from the container running Sourcegraph (probably due to a
firewall rule or due to Sourcegraph's host not respecting the TLS certificate of ADFS). You have two
options:
federationmetadata.xml
file, transform it into a JSON string (using a tool like
https://json-escape-text.now.sh), and set it in the identityProviderMetadata
field of the
auth.provider
SAML config. You can then delete the identityProviderMetadataURL
field.This section covers troubleshooting tips if the following is true:
The error log message will indicate something about the root cause of the error. A common error
message is The requested relying party trust '<URL>' is unspecified or unsupported
. If this is the
error, double-check the relying party identifiers of the Relying Party Trust entry in ADFS:
See SAML troubleshooting for more tips.