ℹ️ Info
Part of the Getting Started guide, Before you begin.
Connect revel8 to Google Workspace so your team signs in with their Google accounts. You work in two tabs side by side: the Google Admin console, and revel8 under Settings → Access Controls (in Identity & access).
1. Create a custom SAML app in Google Admin
In the Google Admin console, open Apps → Web and mobile apps.
Click Add app → Add custom SAML app.
Name the app
revel8. A logo and description are optional. Click Continue.
2. Upload the Google metadata to revel8
On the next page, Google Identity Provider details, click Download metadata.
In revel8, open Settings → Access Controls. Under Metadata file, click Upload and select the file.
The Identity provider card now shows Active instead of Not configured.
3. Copy the revel8 identifiers into Google
In Google Admin, click Continue to reach Service provider details.
From the revel8 Identity provider card, copy the two values into Google:
revel8 ACR URL goes into ACS URL.
revel8 Entity ID goes into Entity ID.
Click Continue.
4. Map the attributes
On Attribute mapping, add these mappings, then click Finish:
Google Directory attribute | App attribute | Needed |
Primary email |
| Required |
First name |
| Recommended |
Last name |
| Recommended |
revel8 does not read a name attribute, so you do not need to map Primary email a second time.
5. Turn the app on for your users
Google turns new custom SAML apps off. Until you turn it on, nobody can sign in to revel8 through Google.
In Google Admin, open the revel8 app and click User access.
Set Service status to ON for everyone, or turn it on only for the organizational units that should sign in.
Click Save.
6. Map Google groups to revel8 roles (optional)
Instead of setting each person's role by hand, revel8 can assign roles from Google group membership at sign-in.
In the revel8 app in Google Admin, open Attribute mapping. Under Group membership, choose the Google groups to send, and set App attribute to:
http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
In revel8, under Group-to-role mapping, click Add mapping.
Under SAML group, enter the Google group's name exactly. Under Role, choose
EMPLOYEE,EDITOR,CISOorDIRECTOR. You can only map to roles up to your own.Repeat for each group, then click Save Mappings.
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 Google. The Password policy and Two factor authentication settings no longer apply, and revel8 greys them out.
🚫 Important
Test a full sign-in through Google 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 the app is turned on for. If you set up group mappings, confirm the account received the expected role.