Auth0

Connect Auth0 as a SAML SSO provider to allow members of your organization to authenticate with Auth0 and access your ReadMe projects.

Create an Application

Start by creating a new application in Auth0 for ReadMe.

1. In the Auth0 dashboard, go to Applications > Applications and click Create Application.

2. Enter a name (e.g., ReadMe SSO).

3. Select Regular Web Application for the application type.

4. Click Create to create your app.

---

Configure SAML Settings

Next, exchange configuration values between ReadMe and Auth0.

6. Go to Teammates in your ReadMe group dashboard.

7. Select SAML from the Single Sign-On menu, then click Configure.

8. Record the Single Sign-On URL to use in your Auth0 configuration.

9. Record the Entity ID value to use in your Auth0 configuration.

10. Leave ReadMe's settings open—you'll return to them later.

11. Return to Auth0. From the application settings screen, select the Addons tab.

12. Select the SAML2 Web App option.

13. In the SAML2 Web App config modal, select the Settings tab.

14. Enter the single sign-on URL from step 8 as the Application Callback URL.

15. Enter the entity ID from step 9 as the audience in Settings, formatted as a JSON object.

16. Click Enable.

---

Certificate and Login URL

With the basic configuration saved, bring your certificate and login URL back to ReadMe.

17. Select the Usage tab in Auth0's SAML2 Web App config modal.
18. Click the Download Auth0 certificate link to save a copy of the cert to your local machine.
19. Copy the Identity Provider Login URL.
20. Back in your ReadMe SSO configuration settings, enter the login URL from the previous step in the Single Sign-on URL field.
21. Open the downloaded certificate file in a plain text editor, copy its contents exactly, and paste them into the Public Key Certificate field in ReadMe.

22. Click Save.
23. Click Exit to close the open modal.
24. Click Save to confirm your SAML settings changes in ReadMe.

---

Attributes and Claims

Now match the attribute names ReadMe expects to the claims Auth0 sends.

23. In Auth0, return to the Settings tab in Auth0's SAML2 Web App config modal.

24. At a minimum, you need to send us email, name, and username to sign a teammate into ReadMe. Provide this data as a mappings object in Settings.

25. Click Save.

---

Add Users via Roles

Finally, assign the teammates who should have access to ReadMe.

26. In the Auth0 dashboard, go to User Management > Roles.

27. Click Create Role.

28. Give the new role a name (e.g., ReadMe Teammates), provide a description, and click Create.

29. Select the Users tab.

30. Click Add Users.

31. Select the users you want to give access to, then click Assign.

Your teammates can now access the Auth0 app tile and log in to ReadMe!