Single Sign On support is a feature only available on the Enterprise plan. To enable this function on your account, reach out to your personal Customer Success Manager (CSM) for details!
A Step-by-step guide on how to configure SAML2.0 using Azure AD
Initial Set Up
Reach out to your Customer Success Manager and ask them to provide you with Entity ID and ACS URL. Let us know if you want to identify yourself using your email or some other value that cannot be changed.
If you choose to identify yourself with your email address then it will become your identifier on our end. That means that in case your email address has changed, a new user will be created the next time you login as the identifier has changed.
If you choose to identify yourself with something other than your email address then regardless what email address you choose it will always carry your identifier, which means that we will match the identifier instead of the email address. If your email address changes, we will accept it based on the identifier and automatically update it for you on our end.
Log in to your Azure portal
Navigate to All Services -> Enterprise Applications (under Identity)
Click on “New application” and then “Create your own application”:
Name your app and click on “Create”.
Go to “Set up Single Sign On” method page and select “SAML”:
From here you will be able to configure your SSO in 4 steps:
1). Basic SAML Configuration:
Enter the Entity ID and the ACS URL (previously provided to you by your CSM) in the relevant fields and click on “Save”.
2). User Attributes & Claims:
Choose “Add new claim”:
Map the following Detectify values to the source attributes in Azure:
// Detectify name -> Azure Source attribute
User.Email -> user.mail
User.FirstName -> user.givenname
User.LastName -> user.surname
User.MemberOf -> user.groups (needs to be set up as a "group claim")
***If you don’t identify yourself with your email, add User.Identifier attribute as well. In our example we mapped it to Azure’s user.objectid, however you are free to choose any other user unique attribute:
User.Identifier -> user.objectid
You can also reuse the “Additional claims” instead of creating new ones, however if you do so remember to leave the “namespace” field empty, e.g:
3). Now it’s time to add the certificate to your application!
Here you can upload or create a new certificate. Once you’ve done that, send over the Base64 certificate to us.
Together with your certificate, send over your Login URL, Azure AD Identifier and Logout URL (optional).
4). Before you test out your application, go to “Groups” and add a new group with a test user to it.
Groups
Go to All Services -> Identity -> Groups
Add a new group
Group type: leave it as it is
Group name: choose the name for your group. It is entirely up to you how the group will be named, however to make it easier to distinguish the groups we suggest the following naming convention:
detectify.admin.TEAM-NAME
detectify.user.TEAM-NAME
detecity.guest.TEAM-NAME
“Guest”, “user” and “admin” are the different permission levels. You can read more about the admin/user/guest permissions in our KB article here.
Members: add users to your group and click on “Select” -> “Create”
Go to your newly created group and copy its Object Id
Send over the Object Id to your Customer Success Manager and explain which team and which permission level users coming with this particular Object Id should be assigned to.
It is also possible to grant all members of a particular group access to all the Detectify teams with a specific permission level - all members of this particular group will then join all company’s teams with e.g. user credentials.
Access Priority
If the user is added to the groups that have been mapped to two different permission levels for the same team, the one offering highest permissions will be selected:
detectify.user.TeamA
detectify.admin.TeamA
= the user will join TeamA with admin credentials
If a user has been assigned admin access to all of the teams as well as user access to one particular team, the more specific configuration will always have priority over wildcards:
detectify.user.TeamA
detectify.admin.*
= the user will join TeamA with use credentials
Provisioning of New Users
With each login attempt through SSO we update the permissions/team access based on the information we receive together with your login request.
If a user is not part of any groups or the groups’ Object Ids have not been sent over to us and mapped to any team on our end, when logging in via the Azure Login URL he or she may end up in their own, “personal” team instead of the company ones.
Should that happen, you can simply add the user to the right Azure group/-s and/or send over the Object Id to us. The next time the user logs in, the permissions and the team access will be adjusted according to the new information received with your login request.
Common Issues
- SSO Login attempt fails :
If you’re a new user the first login attempt needs to be done via the Azure Login URL. The next time you log in you can go directly to https://detectify.com/login.
If you already have an account with us set up under the same email address and now want to switch to another login method we need to permanently remove your account from our system first. In this way the login method will not be predefined and you will be able to set it anew to SAML via the Azure link.
If your application does not support ”?” in the Entity ID, reach out to your Customer Success Manager and we’ll change the format for you.
2. I did not join my company’s teams:
The most common causes are:
while setting up your group claims and attributes, “Additional claims” have been reused, however the “namespace” field hasn’t been cleared out and is polluting your login request
no user assignment to the Groups
the Object Id has not been sent over to us and thus has not been mapped to any team and permission level on our end
Check and correct any errors and try logging in again. If the issue persists reach out to support@detectify.com and we’ll be happy to take a look at it!