Steps to configure Pinpoint
Note you will require the Company Manager role within Pinpoint to complete these steps
1. On the left hand side, in the menu under Settings, click Integrations
2. Click the 'Apps' tab, find the SAML integration and click 'Add'
3. Make a note of the Entity ID, Consumer URL and Login URL
Steps to configure Azure Active Directory
Login to Azure and navigate to 'Enterprise Applications'
Click 'New Application' and find the Azure AD SAML Toolkit application
3. Click the tile enter a name and hit create
4. You should be redirected to your new enterprise application in Azure, once you are select 'Single sign-on' in the left hand menu and then select 'SAML'
5. Click 'Edit' under 'Basic SAML Configuration'
6. Add the Entity ID from the Pinpoint Integration into the Identifier (Entity ID) input (ensuring that you tick default and remove the existing https://samltoolkip.azurewebsites.net entry)
7. Add the Consumer URL from Pinpoint into the Reply URL input
8. Add the Login URL from Pinpoint into the Sign on URL
9. Hit save
10. Download the Federation Metadata XML
11. Click 'Users and Groups' in the left hand menu for the enterprise application, and add the users and groups that you want to be able to use the single sign on
Back over to Pinpoint
Back on the Pinpoint integration page copy the contents of the Federation Metadata XML into the Metadata XML field and hit save. It's easiest to open this file in a basic text editor (like TextEdit) and copy it from there. Be careful if you open it in an internet browser that you don't end up with lots of other unrelated things in your clipboard.
2. Toggle the switch at the top of the page to 'Enabled' and users will be able to sign in using their Azure Active Directory account!
Additional configuration in Pinpoint
You have several additional options in Pinpoint that you can choose to enable
Enforce Login - This will disable other login methods including the ability to login with an email / password combination and force all users to sign into Pinpoint via Azure.
Enforce For external recruiters - Will do the same as enforce login but specifically for external recruiters you add into your Pinpoint account. This option exists separately because most companies do not invite external recruiters to join their Azure and issue them with a company email.
Automatically redirect login - If this is toggled on when a user attempts to login to your companies Pinpoint (when they go to yoursubdomin.pinpointhq.com/users/sign_in) they will be automatically redirected to Azure to login that way. This can avoid confusion and unnecessarily forcing users to click a button when they hit the Pinpoint login page.
Additional configuration in Azure Active Directory
When configuring the integration in Azure you will have seen a section for attributes and claims. These are the fields sent to Pinpoint when a user successfully signs into Azure that enables us to then sign them into Pinpoint.
The user is found based on the Unique User Identifier (Name ID). By default Azure will use the user principal name which in most cases is correct and is the user's default email address.
In some cases (when users are migrated from one tenant to another for instance) the user principal name may be an old email address. In that case the Unique User Identifier can be changed so that it sends the correct email address to Pinpoint.
For example. Pinpoint users usually have @pinpointhq.com email addresses. If we migrated in users from a hooli tenant they might have @hooli.com email addresses. In this case the User principal name would be username@hooli.com, but we want want to send the users new email so we could change the field in Azure to use the email username@pinpointhq.com. This way it would sign in username@pinpointhq.com in Pinpoint itself, otherwise we may not be able to find the username@hooli.com user.
