OneLogin - SAML integration
This is a quick guide to help integrate OneLogin with Zentral.
In Zentral, identity providers (IdP) are configured using realms. There are three kinds of realm: SAML, OIDC, and LDAP. In this case, we will use a SAML realm.
We will start by setting up an OneLogin application. We will then configure a Zentral realm for this application. Finally, we will update the OneLogin application configuration, and configure the Zentral mappings.
Create a OneLogin application
SAML application
In OneLogin, from the Administration > Applications
view, click on the Add App
button.
Select the SAML Custom Connector (Advanced)
type.
Pick a name and save the app.
In the Info
view, click the More Actions
button and download the metadata.
IMPORTANT those metadata are only temporary ones! Once the configuration is done, you will need to download a new version of the metadata.
Roles
Go to the Users > Roles
section. Make sure there are Default
and Admin
roles for the app you have just created, with the correct user mappings.
Create the Zentral realm
In Zentral, go to Setup > Realms
, click on Create realm
and select SAML realm
.
Fill up the form:
- Pick a name
- Select
Enabled for login
if you want to use this realm as login realm - Pick a login session expiry (can be left empty, see help text)
- Use
username
,email
,first_name
,last_name
for the claims - Leave
Full name claim
empty - Upload the metadata file that you have just saved (see previous section)
- If you want to allow logins initiated by the IDP, tick the box
Update the OneLogin application
We will use the information displayed in the Zentral realm detail page to finish configuring the OneLogin app.
Configuration
Set the following values in the Configuration
tab of the OneLogin app:
OneLogin attribute | Zentral realm value |
---|---|
RelayState | Default relay state Only available if IdP initiated login is checked. Make sure there are no whitespaces! |
Audience (EntityID) | Entity ID |
Recipient | Assertion Consumer Service URL |
ACS (Consumer) URL | Assertion Consumer Service URL |
SAML initiator | OneLogin |
SAML nameID format | |
SAML issuer type | Generic |
SAML signature element | Assertion |
Parameters
Set the following fields in the Parameters
tab of the OneLogin app:
SAML Custom Connector (Advanced) Field | Value |
---|---|
first_name | First Name |
last_name | Last Name |
roles | User Roles |
username | Email name part |
Update and test the Zentral realm
Update the realm metadata
IMPORTANT Download the OneLogin app metadata again! Click the More Actions
button and save the file.
In Zentral, click on the Update
button in the realm detail view, and upload the metadata file.
Configure the group mappings
We need to map the Default
and Admin
OneLogin application roles to Zentral groups.
In Zentral, go to Setup > Groups
and make sure you have two groups corresponding to the two roles in OneLogin. Set the permissions of each group in Zentral according to your requirements. You could of course add more roles in OneLogin and map them to more Zentral groups.
Go back to the realm detail view. For each role in OneLogin, we need to create a realm group mapping in Zentral:
Zentral group mapping attribute | Value |
---|---|
Claim | roles |
Separator | ; |
Value | name of the application role in OneLogin |
Group | Zentral group |
Test the realm
Use the 🕶️ Test
button in the Zentral realm detail view to test the mapping of the claims/parameters and roles/groups. It will redirect you to OneLogin and then display the OneLogin information sent to Zentral, and the mappings.