Skip to main content
SSO: Setting up Azure AD

How to set up an SSO connection with Azure AD

Daniel Sternegard avatar
Written by Daniel Sternegard
Updated over a week ago

There are three parts to setting up Azure AD, which we'll cover step-by-step:


1. Prepare your Azure account

First, you need to create a new Enterprise Application on the Azure side, of type non-gallery.

In that new application, you should set-up Single Sign-on using SAML. For now, only enable it - we'll fill it out in section 2 below.


2. Input parameters across systems

To set up the SSO connection, there are some values in Planhat you need to input to Azure, and vice versa. Below we will walk through the required parameters, and the Planhat/Azure defines where the value should be input.

Planhat: Initiator

This controls whether users should be able to log-in via IdP-initiated flow only (ie, only log in via Azure Directory), or also SP-initiated (ie, via Planhat's website). It's purely a setting, requiring no other input than a decision from your end on what works best. We recommend to use both (IdP + SP).

Planhat: Identifier (Application ID) - required

Called "Application ID" on Azure's side, found under Overview of the Application page.

____

After this, go into the Single Sign-on page. First, you need to do Basic SAML Configuration using input from Planhat's side.

Azure: Identifier (Entity ID) - required

This you can find in the Instructions under Single Sign-on > Security on Planhat's side. But the general rule is: https://api-[cluster].planhat.com/samlmetadata/[tenant_name]

So if you're Apple on the US cluster, then your Identifier (Entity ID) will be: https://api-us.planhat.com/samlmetadata/apple. You can find out what cluster you are on by looking at the URL when logged into Planhat - for example, it will look like https://app-eu.planhat.com/data.

  • Note that the URL when you are working in Planhat will say "app-us", but in the SSO context we want to use "api-us".

  • Not everyone will have the "-[cluster]", sometimes it's just "app.planhat.com".

Azure: Reply URL (Assertion Consumer Service URL) - required

Again, this can be found on the SSO page in Planhat. The general rule is: https://api-[cluster].planhat.com/samlassert/[tenant_name]

So if you're Apple on the US cluster, then your Identifier (Entity ID) will be: https://api-us.planhat.com/samlassert/apple

____

Planhat: Log-in URL - required

Then on the Planhat side, you should set the Login URL. You find this under the Single Sign-on page on step 4 in Azure.

After setting this, you have a couple of optional parameters to set in Planhat, including Logout URL, Session Length, whether there are any users who can bypass SSO and log-in with a password.

Planhat: Certificate (Base64) - required

Download the Certificate (Base64) and open the file in the Notepad/Text Editor in Windows/Mac, take the full content, and paste it into Planhat.

The content should look something like:

-----BEGIN CERTIFICATE-----
MIIC8DCCAdigAwIBAgIQIPWmK/L1AohJLjFZGk0sXzANBgkqhkiG9w0BAQsFADA0MTIwMAYDVQQD
EylNaWNyb3NvZnQgQXp1cmUgRmVkZXJhdGVkIFNTTyBDZXJ0aWZpY2F0ZTAeFw0yMjA5MDcyMzEw
MDBaFw0yNTA5MDcyMzEwMDBaMDQxMjAwBgNVBAMTKU1pY3Jvc29mdCBBenVyZSBGZWRlcmF0ZWQg
U1NPIENlcnRpZmljYXRlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqPJI95bz6ggt
Dmjv7cqyGYg58ACoarRSaka3/j0dCD4gPIMlQjo2wcENpoFQKP7go5gceP0bIQRVNZdo1QKA4uXG
73ishD6b2X/bqV3qTYONSLs1u3kxZ6CYW/wvhM7sLvzh7RmdgLsP9f3sv6pOjn4UU4XfbrHLOnD1
u5vXj9gUmmJL9kzCEWhhDm2xvhlOODyxnC1VE0bjgceSthXT0pc40pR7ue4HCVd8RaBU73mK6rtJ
DS9cosOR1aHdlWgixHfHxnAmZ0z5hjcTTO8uTJvL4d1B0ZeJoMCC/5/cPBoLU5lOejy1uj1YGdcv
ti8gxEIQSVRwJUBmUbyv8ue91QIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQB383Md47kMOzqCLkCq
LJU1QmpVPZJjktp29KDWGVXGLRZW2Nu3AdilOeCfsT3qQZ0tIeronLSXw4TViBpNbUvrWrQVmz1G
ud0/DQEmiO3je897FYbopHl7g9EC/yC/vZ+FXMA13y8ZFtrnBjsxpbU+b4OcelKmtF+MofrN/v7p
FsvJstMVV5iF9NoRyW1VaUpq0wocCy/EYfkYWb0BlpPUdOttvuVRMRup4giUKwsddpCzllShFuVt
N9WfVM/kMdMqi2KWjGhmdIYk+Ec22FnsLYvfMBmnp7EKNNOLRaqaEU0Eemueen86wqArcuLd5ecM
9MWfOZ3GwLCxOiOg3cHl
-----END CERTIFICATE-----

Planhat: Disable SAML AuthnContext - required

This can typically be set to disabled but if you face the error below when trying out the set-up, then enable the "Disable SAML AuthnContext".

Error: aadsts75011 authentication method x509 multifactor


3. Try it out / common troubleshooting

After everything has been set-up, you can try out the connection on the Azure side on step 5 in the SSO section.

Some common issues:

  • The user who tries to log-in is not created as a User in Planhat

  • The user ID needs to be via email address, that is matching the one used in Planhat

  • The x590 multifactor error code (see the final point on the Set-up section above on how to fix this using the Disable SAML AuthnContext parameter)

Did this answer your question?