Configure Auth0 for SAML SSO¶
Introduction¶
Auth0 is a Cloud-based Identity and Access Management solution that can be used for SAML Single Sign-On (SSO) with the CIS SecureSuite Platform.
This guide explains how CIS SecureSuite Platform System Admins can configure Auth0 as their organization's identity provider for SSO.
Steps¶
1. Create SAML application.
2. Configure SAML settings.
3. Configure attribute mappings.
4. Get SAML Metadata URL, file, or information.
5. Connect Auth0 application to the CIS SecureSuite Platform.
Additional Considerations
Tip
We recommend opening the CIS SecureSuite Platform and going to the IdP page in Admin. You will need to copy/paste values from the IdP to the CIS SecureSuite Platform and vice versa.
Create SAML Application¶
Start by creating and configuring the SAML application in Auth0.
1. Log in to Auth0.
2. From the navigation bar, go to Applications > Applications.
2. Select Create Application.
3. Enter a descriptive, user-friendly name for the application, select Regular Web Applications and Create.
Configure SAML Settings¶
Next, configure the SAML settings for the application.
1. Go to the Settings tab.
2. Configure the following settings:
- Application Login URI: Copy and paste the Redirect URI from the IdP page in the CIS SecureSuite Platform's Admin area.
- Allowed Callback URLs (Optional): Same as Application Login URI above. This setting is an additional security measure, allowing Auth0 to redirect users only to the specified callback URLs.
3. At the bottom-right of the page, select Save Changes.
Enable SAML¶
1. Go to the Addons tab and select SAML2 WB APP.
2. Go to the Settings tab, scroll down and select Enable to finish creating the application.
Configure Attribute Mappings¶
Next, configure the attribute mappings. They allow for the identity and authorization data to be properly carried between Auth0 and the CIS SecureSuite Platform.
1. From the left navigation, go to Actions > Library.
2. On the Custom tab, select Create Action and then Build from scratch.
3. Enter a name for the action (e.g., UserDataMappers) and keep the other fields as the defaults.
4. Select Create.
5. Copy the following script and paste it into the editor in order for Auth0 to send the needed attributes as part of the SAML assertion post login.
/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
api.samlResponse.setAttribute(
'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier',
event.user.user_id
);
if (event.user.email) {
api.samlResponse.setAttribute(
'email',
event.user.email
);
} else if (event.user.user_metadata.email) {
api.samlResponse.setAttribute(
'email',
event.user.user_metadata.email
);
}
if (event.user.username) {
api.samlResponse.setAttribute(
'username',
event.user.username
);
} else if (event.user.user_metadata.username) {
api.samlResponse.setAttribute(
'username',
event.user.user_metadata.username
);
} else if (event.user.name) {
// Use the name as the username if there is no username in the event or user metadata
api.samlResponse.setAttribute(
'username',
event.user.name
);
}
if (event.user.given_name) {
api.samlResponse.setAttribute(
'firstName',
event.user.given_name
);
} else if (event.user.user_metadata.given_name) {
api.samlResponse.setAttribute(
'firstName',
event.user.user_metadata.given_name
);
} else if (event.user.nickname) {
// Use the nickname as the first name if there is no given name in the event or user metadata
api.samlResponse.setAttribute(
'firstName',
event.user.nickname
);
}
if (event.user.family_name) {
api.samlResponse.setAttribute(
'lastName',
event.user.family_name
);
} else if (event.user.user_metadata.family_name) {
api.samlResponse.setAttribute(
'lastName',
event.user.user_metadata.family_name
);
} else if (event.user.nickname) {
// Use the nickname as the last name if there is no family name in the event or user metadata
api.samlResponse.setAttribute(
'lastName',
event.user.nickname
);
}
};
7. From the left navigation, go to Actions > Triggers.
8. Select post-login.
9. Under Add Action, select Custom.
8. Drag the created action into the Auth0 login flow between the Start and Complete flows.
9. Select Apply to finish configuring the required attributes.
Get SAML Metadata URL, File, or Information¶
To establish the connection between the Auth0 SAML application and the CIS SecureSuite Platform, you need the SAML application's metadata. This metadata can be brought into the CIS SecureSuite Platform through a URL, file, or manual input.
Note
Using the URL or file will auto-populate most of the configuration fields in the CIS SecureSuite Platform, reducing the chance of human error and setup time.
Get Metadata URL¶
1. Go to the Settings tab.
2. Scroll down and select Advanced Settings.
3. Go to the Endpoints tab and copy the URL from SAML Metadata URL to use when configuring the IdP in the CIS SecureSuite Platform.
Note
In case the Auth0 SAML metadata URL does not import the information into the CIS SecureSuite Platform, enter the metadata URL in a browser and save its contents in a file. You can then upload the file to the CIS SecureSuite Platform as a SAML metadata file to auto-populate most of the fields.
Get Metadata File¶
1. Copy the SAML metadata URL.
2. Paste the URL in a new browser tab and save the metadata to use when configuring the IdP in the CIS SecureSuite Platform.
Get Metadata Information¶
Tip
If inputting the SAML metadata manually into the CIS SecureSuite Platform, consider having Auth0 and the CIS SecureSuite Platform open to copy/paste the values.
1. From the left navigation, go to Applications > Applications and select the created SAML application.
2. On the Addons tab, select SAML2 WB APP.
Warning
Ensure this setting is not toggled off.
3. Copy or note down the value for Issuer to enter into the IdP Entity ID field on the CIS SecureSuite Platform's IDP configuration page in Admin.
4. Copy or note down the value for Identity Provider Login URL to enter into the SSO Service URL field field on the CIS SecureSuite Platform's IdP page in Admin.
5. Select Download Auth0 Certificate, save and open the certificate file.
6. Copy or note down the certificate to enter into the SAML Signing Certificate field on the CIS SecureSuite Platform's IDP configuration page in Admin.
Connect Auth0 Application to the CIS SecureSuite Platform¶
With the SAML metadata URL, file, or information, finish setting up SSO with Auth0 by connecting the IdP to the CIS SecureSuite Platform.
1. Open the CIS SecureSuite Platform.
2. Go to Admin > IdP.
3. From the External Identity Provider dropdown, select SAML.
4. Fill the fields by providing the metadata URL, uploading the metadata file, or entering the information into the fields.
Tip
Refer to the Connect with SAML procedure for detailed instructions on this step.
5. Select Submit to establish the connection.
Add First and Last Name to Auth0 Users¶
By default, Auth0 does not have fields for a user's first and last name. If the user does not have an associated first and last name, the CIS SecureSuite Platform will display the user's nickname, which Auth0 automatically constructs using the first portion of the user's email address (i.e., text before the @ sign).
If you would like your users to have first/last name in the CIS SecureSuite Platform, add that information to the user's metadata in Auth0:
1. From the left navigation, go to User Management > Users and select the user.
2. Enter the following in User Metadata (user_metadata):
3. Select Save to apply the change.