Auth0 SAML SSO
Learn how to create a custom Auth0 SAML 2.0 application for Doppler Single Sign-On.
Requirements
- Verified domain for your workplace (Settings page)
- Auth0 Account with access to create custom application integrations
1. Initial Doppler SAML SSO Configuration
Go to the Doppler dashboard and from the menu click Team, then select the Roles tab from the top menu. Choose the Default Roles for users who login via SSO.
The Workplace Role controls the initial permissions a user will receive when their account is created. We recommend keeping it at Collaborator access to follow the principle of least privilege. The Project Role is the role granted to a user when they're added to a project, so set this to the role most commonly used. Users with the Owner role can adjust these after the user has logged in once. If you scroll down further on the Roles page, you'll see a breakdown of what permissions each Role has.
After setting the Default Roles, we need to enable SAML SSO in Doppler to get access to the URLs needed to configure the third party SAML SSO application.
Select the SSO tab from the top menu and scroll down to the SAML Single Sign-On section. Click the Add SAML button.
Next, choose a verified domain from the dropdown menu and click Save.
SAML SSO configuration requires having a domain associated with it because users login using their email address and the domain of that address is mapped back to your SAML SSO login. Verification is required when you add the domain to your account to confirm your ownership of the domain.
The domain you selected should show up now in the Inactive state. Click on the three dot menu and choose the Edit option.
Copy the ACS URL and Entity ID URLs in the edit drawer that appears for use when configuring the third party SAML SSO application.
2. Create SAML Application
In a separate window, browse to your Auth0 dashboard and select Applications from the main menu on the left, then click the Create Application button.
Provide a name for the application, select Regular Web Applications as the application type and then click Create.
3. Auth0 SAML Configuration
Now click on the Settings tab for the application and scroll down to the Application Properties section. Paste in the following URL for the Application Logo (or feel free to upload to a location of your choosing and use that URL instead):
https://user-images.githubusercontent.com/133014/107730990-80225400-6d40-11eb-8141-8ec29c79c85e.png
Next scroll down to the Application URIs section.
Populate the form with the URLs obtained from the Doppler SAML Single Sign-On setup page in Step 1 above. They will look similar to the following:
Parameter | Value |
---|---|
Allowed Callback URLs | https://dashboard.doppler.com/login/sso/callback/$UUID |
Application Login URI | https://dashboard.doppler.com/login/sso/saml/metadata/$UUID |
These are example URLs only and will not work in your setup. You need to use the URLs obtained from the Doppler SAML Single Sign-On setup page referenced in Step 1 above.
Scroll to the bottom of the page and click Save Changes. Now scroll back to the top of the page, click the Addons tab, and enable the SAML2 Web App option.
Click on the Download link next to Identity Provider Metadata to download the IDP metadata XML we'll need later on to finish configuring SAML in Doppler.
Next click on the Settings tab. The Application Callback URL should already be populated, but if not, paste in the callback URL you used previously. In the Settings text field, paste in the following JSON (be sure to replace the URLs with the ones you obtained from your Doppler SAML config page):
{
"audience": "https://dashboard.doppler.com/login/sso/saml/metadata/$UUID",
"recipient": "https://dashboard.doppler.com/login/sso/callback/$UUID",
"destination": "https://dashboard.doppler.com/login/sso/callback/$UUID",
"nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
"nameIdentifierProbes": [
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
],
"mappings": {
"name": "name"
}
}
Then scroll down to the bottom of the dialog and click Enable.
4. Update Doppler SAML SSO Configuration
Navigate to the Doppler Team page and click on the SSO tab.
Scroll down to the SAML Single Sign-On section, click on the three dot menu, and choose the Edit option. Paste in the IDP XML metadata, check the Enabled field, then click the Save button.
You're now ready to test the Auth0 application!
5. Testing
As an Auth0 administrator, it's presumed you'll know how to sufficiently test a new Auth0 application, but here is a general guide.
Test sign-in flow using incognito window
Be sure to stay signed in to the Doppler dashboard until you've verified the Auth0 sign-in flow from an incognito window.
Staying signed in to the dashboard will allow you to update the SAML settings or disable SAML SSO in the event of misconfiguration.
Test the Doppler SAML sign-in flow by opening an incognito window and browse to the Doppler Login page. Enter the email address of the test user and click the Log In button. This should redirect you to the Auth0 login page.
Enter the test user's login credentials and click Continue.
You should then be redirected to the Doppler dashboard for the assigned user.
Once you've verified the Doppler SAML application is configured correctly, you can then apply your standard organization policies for people and groups assignment.
Troubleshooting
Here are some general troubleshooting tips:
- Double-check that the Single sign in URL and Audience URI values match exactly what is displayed in the Doppler SAML section.
- Check that the JSON settings for the SAML2 Web App add-on has the correct URLs.
If you're still running into issues, the error page should present you with a requestId
value that can be used by our support team for further diagnosis.
Awesome Work!
Your custom Auth0 Doppler SAML 2.0 application is now set up!
Updated 11 months ago