Microsoft Entra ID: Cloud Platform SSO Configuration Guide

Table of Contents:

• Step 1. Access your SAML settings in CanIPhish
• Step 2. Create an Enterprise Application in Entra ID
• Step 3. Configure SSO in CanIPhish
• Step 4. Update the Entra ID App to support IdP-initiated SSO
• Step 5. Assign the CanIPhish Application to users or groups in Entra ID
• Step 6. Provision a role for users in CanIPhish
• Appendix A: Additional Guidance For Common Issues

To setup SAML-based single sign-on within Entra ID, please follow the below steps:

Step 1. Access your SAML settings in CanIPhish

1.1. Login to your CanIPhish Cloud Platform account and traverse to the Platform Settings page. 

1.2. Click on Authentication Settings > Platform Single Sign-On to show your SSO configuration.

1.3. Make a note of both the Single Sign-On URL and Audience URI values (we'll need these in the following step).

Step 2. Create an Enterprise Application in Entra ID

2.1. Login to Microsoft Azure with an admin account and visit the administrator dashboard (i.e. https://portal.azure.com/).

2.2. In the Azure dashboard click on the search bar (up the top) and run a search for "Enterprise applications", clicking on the "Enterprise applications" service that is returned.

2.3. Click the "New application" button.

2.4. Click the "Create your own application" button.

2.5. Give the app a display name of your choosing (e.g. CanIPhish Cloud Platform), ensure the option "Integrate any other application you don't find in the gallery (Non-gallery)" is selected and click Create.

2.6. Click on the "Single sign-on" menu item on the left side of the page.

2.7. Select SAML as the single sign-on method.

2.8. Click Edit on the "Basic SAML Configuration" tile.

2.9. Enter the following information into the respective fields, leave all other fields blank, and then click Save:

Identifier (Entity ID): Audience URI (SP Entity ID) copied from CanIPhish earlier

Reply URL (Assertion Consumer Service URL): Single Sign-On URL copied from CanIPhish earlier

2.10. Click Edit on the "Attributes & Claims" tile.

2.11. Remove the "Additional claims" for all but the top claim which is for email addresses. This can be done by clicking the "..." and then clicking Delete. The below screenshot depicts the only claim that should remain.

When viewing the claim in the claim editor, it should look as follows:

IMPORTANT NOTE: Please make a note of the claim name and namespace. This claim is used later to map your email address from Entra ID into CanIPhish. The claim namespace and claim name are aggregated by Microsoft, and the full claim should be as follows: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

2.12. Click the "SAML-based Sign-on" breadcrumb menu-item to get back to the SAML configuration page.

2.13. Within the "SAML Certificates" tile, click the Download button next to the "Federation Metadata XML" field. Make a note of the downloaded file, as we'll need it in the next step.

2.14. (Optional) Upload the CanIPhish logo. Click on the Properties menu item on the left side of the page. Download the CanIPhish Logo. Click where it says "Select a file" and then select the CanIPhish logo you downloaded. Finally, click Save.

Step 3. Configure SSO in CanIPhish

3.1. Jump back into the CanIPhish Cloud Platform and traverse to the Platform Single Sign-On section.

3.2. Under the "Configuration For CanIPhish" section, upload the Metadata Document downloaded earlier from Google Workspace. When the file is specified, click the Upload Document button.

3.3. Once successfully uploaded, you can view the document by clicking the metadata.xml text that appears.

3.4. In the "SAML Attribute Mapping (Email)" field, paste the Attribute field name we configured earlier in Entra ID (Step 2.11).

This should be: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

3.5. (Optional) Enter the email address of an existing CanIPhish user who should still be allowed to login to CanIPhish directly using an email address and password (i.e. without SSO). We recommend adding at least 1 user. In the event there is an issue with the SSO config, you won't be entirely locked out of your tenant.

3.6. Click Activate SSO!

3.7. Confirm that "SSO Status" field has changed from Inactive to Active. If there are any issues, a small popup should appear notifying you of the issue.

3.8. You will notice a new field called "SSO Relay State" has appeared under the "Configuration For The Identity Provider" section. Make a note of this value as it will be used in Step 4.

Step 4. Update the Entra ID App to support IdP-initiated SSO

4.1. Jump back into the newly created "CanIPhish Cloud Platform" Entra ID Enterprise Application and then click on the "Single sign-on" menu item on the left side of the page.

4.2. Click the "Edit" button within the "Basic SAML Configuration" section:

4.3. Paste the "SSO Relay State" value copied in Step 3.8 into the "Relay State (Optional)" field, and then click Save.

Step 5. Assign the Entra ID App to Users or Groups

5.1. While still in your Entra ID App, click "Users and groups" menu item on the left-side of the page:

5.2. Click on the "Add user/group" menu button towards the top of the page.

5.3. Under the "Users and groups" menu item, click the "None Selected" hyperlink.

5.4. Depending on whether you want to assign specific Groups or Users the application, click on the respective sub-heading, select the relevant users/groups, and then click the Select button.

5.5. Click on the Assign button on the bottom left side of the page.

Step 6. Provision a role for users in CanIPhish

6.1. Jump back into your CanIPhish Cloud Platform account and traverse back to the "Platform Settings" page (scrolling to the top to see "User Management").

6.2. If there are any users who you've assigned the "CanIPhish Cloud Platform" Application to who don't yet have a role within your CanIPhish tenant, click on the "Add New User" button. If everyone already has a role, you can skip Step 6.

6.3. In the respective field, provide the users First & Last Name, Email Address, and Role of their account (i.e. Platform Admin, Platform User, or Platform Reporter). Once complete, click the Save button.

6.4. The user will be sent an email notification inviting them to finalize the creation of their new account and login using single sign-on. You're all done. SSO has been successfully configured!

Appendix A: Additional Guidance For Common Issues

Receiving A Generic Authentication Error From CanIPhish

Please confirm that under step 2.11 the additional claim name exactly matches the SAML Attribute Mapping listed in CanIPhish. If there is a mismatch or this additional claim doesn't exist, email addresses won't flow through correctly. The value should be as follows:

• http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Once this is correct, please Deactivate the SSO configuration and then Reactivate the SSO configuration. This resets SSO accounts on our end and will allow you to login.

Receiving A RelayState Error

If you've just setup SSO or have made any changes within the Entra ID app, please wait up to 5 minutes for the configuration to flow through Microsoft's systems. If the issue is still occurring 5 minutes after the last configuration update was made, please contact the CanIPhish Support Team for assistance.