ℹ️ Info
Part of the Getting Started guide, Before you begin.
Connect revel8 to Microsoft Entra ID so your team signs in with their Microsoft accounts. You work in two tabs side by side: the Microsoft Entra admin center, and revel8 under Settings → Access Controls (in Identity & access).
1. Open single sign-on for the revel8 app in Entra
In the Microsoft Entra admin center, open the Enterprise application for revel8.
Click Single sign-on, then choose SAML.
2. Copy the revel8 identifiers into Entra
In Entra, click Edit next to Basic SAML Configuration.
In revel8, open Settings → Access Controls. The Identity provider card shows the two values Entra needs, each with a copy button.
Paste them into Entra:
revel8 Entity ID goes into Identifier (Entity ID).
revel8 ACR URL goes into Reply URL (Assertion Consumer Service URL).
Click Save in Entra.
3. Upload the Entra metadata to revel8
In Entra, under SAML Certificates, download Federation Metadata XML.
In revel8, under Metadata file, click Upload and select the XML file.
The Identity provider card now shows Active instead of Not configured.
4. Check the claims Entra sends
The default claims of an Entra SAML app already include what revel8 reads. Open Attributes & Claims only to confirm them:
Claim | revel8 uses it for | Needed |
| Email address | Required |
| First name | Recommended |
| Last name | Recommended |
| Group-to-role mapping (step 6) | Only if you map groups |
revel8 does not read the name claim, so you can leave it as it is.
5. Assign users and groups
In Entra, open Users and groups, click Add user/group, and add the people who should sign in to revel8. By default, Entra only lets assigned users and groups sign in to the app.
6. Map Entra groups to revel8 roles (optional)
Instead of setting each person's role by hand, revel8 can assign roles from Entra group membership at sign-in.
In Entra, under Attributes & Claims, click Add a group claim and choose which groups to send.
In revel8, under Group-to-role mapping, click Add mapping.
Under SAML group, enter the group exactly as Entra sends it. Under Role, choose
EMPLOYEE,EDITOR,CISOorDIRECTOR. You can only map to roles up to your own.Repeat for each group, then click Save Mappings.
⚠️ Warning
By default, Entra sends each group's Object ID, not its name. Enter the Object ID under SAML group, or change the group claim to send names. A mapping that does not match exactly what Entra sends never applies.
7. Require single sign-on (optional)
Once single sign-on works, you can turn off password sign-in for everyone. On the Identity provider card, switch on Require single sign-on. The switch becomes available once the card shows Active.
Members then sign in only through Entra. The Password policy and Two factor authentication settings no longer apply, and revel8 greys them out.
🚫 Important
Test a full sign-in through Entra before you switch this on. With it on, a broken single sign-on configuration locks every member out.
Check that it works
Open revel8 in a private browser window and sign in with single sign-on, using an account you assigned in step 5. If you set up group mappings, confirm the account received the expected role.