Configuring SAML with Okta

1. Add a SAML application in Okta

1. Navigate to the "Classic UI" in the Okta Admin site. In the upper left-hand corner, it should say "Classic UI". If it says "Developer Console", click it and select "Classic UI".
2. Go to the Applications tab. Click "Add Application" and then "Create New App". Select "Web" as the choice of Platform and "SAML 2.0" as the Sign on method. Then click "Create".
3. Give your app a name ("Sourcegraph") and click "Next".
4. Set the following values in the SAML Settings (replacing https://sourcegraph.example.com with your Sourcegraph URL):

• Single sign on URL: https://sourcegraph.example.com/.auth/saml/acs
  (Check the box for "Use this for Recipient URL and Destination URL")
• Audience URI (SP Entity ID): https://sourcegraph.example.com/.auth/saml/metadata
• Attribute statements::
  email (required): user.email
  login (optional): user.login
  displayName (optional): user.firstName
  

1. Click "Next".
2. Select "I'm an Okta customer adding an internal app" and click "Finish".
3. In the Settings panel on the next page, find the "Identity Provider metadata" link and record its URL.
4. Grant users or groups sign-in access in the "Assignments" tab. You can do other users later, but at the very least, grant your own Okta user access to the application, or else you won't be able to sign in.

2. Add the SAML auth provider to Sourcegraph site config

1. In Sourcegraph site config, ensure externalURL is set the same Sourcegraph URL you used in the previous section (i.e., what you replaced https://sourcegraph.example.com with). Be mindful to use the exact same scheme (http or https), and there should be no trailing slash.
2. Add an item to auth.providers with type "saml" and identityProviderMetadataURL set to the URL you copied from the "Identity Provider metadata" link in the previous section. Here is an example of what your site configuration should look like:

{
 // ...
 "externalURL": "https://sourcegraph.example.com",
 "auth.providers": [
   {
     "type": "saml",
     "identityProviderMetadataURL": "https://okta.example.com/app/8VglnckX0yyhdkp0bk00/sso/saml/metadata"
   }
 ]
}

Confirm there are no error messages in the sourcegraph/server Docker container logs (or the sourcegraph-frontend pod logs, if Sourcegraph is deployed to a Kubernetes cluster). The most likely error message indicating a problem is Error prefetching SAML service provider metadata. See SAML troubleshooting for more tips.