Microsoft Entra

Connect Microsoft Entra ID as a SAML SSO provider so members of your organization authenticate with Entra ID and access your ReadMe projects.

---

Create an Entra Enterprise Application

Start by creating a new enterprise application in Entra for ReadMe.

1. In Entra ID, go to Enterprise applications > All applications > New application.

2. Name it. A name like ReadMe SSO works well.

3. Click Create to create your app.
4. Find your app under All applications and open it to confirm it's set up as a SAML app.

5. Select Single sign-on from the left menu, then choose SAML as the sign-on method.

---

Configure SAML Settings

Next, exchange configuration values between ReadMe and Entra.

6. Go to Teammates in your ReadMe group dashboard.

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

8. Record your Identifier (Entity ID) value to use in your Entra configuration.

9. Record your Single Sign-On URL to use in your Entra configuration.

10. From Entra, open your app's Single sign-on page and click the edit icon in the first section.

11. Fill out the Basic SAML Configuration form: enter your ReadMe Identifier in the first field and your ReadMe Single Sign-On URL in the second field, then save your changes.

---

Certificate and Login URL

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

12. On the same page in Entra, download your Certificate (Base64) and record the Login URL.

13. Back in your ReadMe SSO configuration page, enter the login URL you recorded into the Single Sign-On URL field.

14. 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. Save your changes.

---

Attributes and Claims

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

15. In your ReadMe SSO configuration page, note the values in the Attribute Statements section. You'll need these for the Attributes & Claims section in Entra.

16. Back in Entra, open Single sign-on for your app and configure the Attributes & Claims section to match. At minimum, you should have:
    • email = user.mail
    • name = user.givenname
    • username = user.userprincipalname

17. Save your changes.

---

Add Users to the Entra App

Finally, assign the Teammates who should have access.

18. In your Entra app, click Users and groups in the left nav, then click Add user/group.

19. Select the users you want to give access to, then save your entry.

20. Confirm the users appear in the Users and groups section of your app.

For example, Owlberto's record shows type User and role User.

Click into a user's record to see which applications are assigned to them.

Your Teammates can now access the Entra app tile and log in to ReadMe.