How to set up SAML SSO for Detecitfy using Okta? (Detectify App)

Single Sign On support is a feature only available on the Enterprise plan. Reach out to your Customer Success Manager (CSM) if you would like to have this functionality enabled for your account. 


A Step-by-step guide on how to configure SAML2.0 using Detectify pre-built solution for Okta:


The pre-built Detectify app for Okta is the fastest way to set up the connector, however if that for any reason does not work for you (e.g. you use a script that modifies the Okta attributes that we extract the information from) check out this article to see how to set up a custom solution.


All screenshots were taken from the Okta Classic UI.


Set Up


  1. Navigate to “Applications” and search for “Detectify”



2. Add the application to your Okta


3. Fill in the information under General Settings and click on “Done”



4. Navigate to the “Sign On” Tab -> “View Setup Instructions”




5. Extract the following information:

- SAML issuer ID
- Single sign-on URL
- X.509 Certificate or similar


6. Send over this information to your Customer Success Manager.


7. Go to Settings and click on “Edit”




8. Make sure that the “Teams” attribute starts with “detectify” and click on “Save”



The Name Attributes as well as the Entity ID and ACS have automatically been configured in the application for you. 


9. Go to Directory -> Groups:


 and add the following ones:


  • detectify.admin.TEAM-IDENTIFIER

  • detectify.user.TEAM-IDENTIFIER

  • detecity.guest.TEAM-IDENTIFIER

Example:



Everything that starts with “detectify” as a group attribute will be sent over to us with your login request as a memberOf attribute. You will join these teams with specified permission levels provided that they are a part of your company Detectify account.


“Guest”, “user” and “admin” are the different permission levels. You can read more about the admin/user/guest permissions in our KB article here


TEAM-IDENTIFIER could be your team name (make sure you spell it in the same way as in your account, spaces included) or an immutable team token provided by us.


or empty string will affect ALL teams accessible for the SAML connection. 

Example: detectify.user.* will give all users that join using SAML user-access to all teams.


Please remember that changing the team name will block access.

10. Assign members to each group:


Access Priority

If the user is added to the groups that contain a team token or team name with 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

More specific names will always have priority over wildcards:

detectify.user.TeamA
detectify.admin.*

= the user will join TeamA with use credentials


11. You're done!


There is no need to add the groups that you have just created to your Detectify app. As specified in your SAML Settings, we will listen to all the groups which names start with “detectify”.

You’re good to go ahead and sign up via your Single Sign on URL. If everything went well, moving forward you will be able to log in by going to https://detectify.com/login and choosing the Single Sign On option.



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, when logging in via the Okta Sign On URL he or she will end up in their own, “personal” team instead of the company ones.


Should that happen, you can simply adjust the permissions for the user in the detectify Okta groups. 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


  1. SSO Login attempt fails :


If you’re a new user the first login attempt needs to be done via the OKTA Single Sign On 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 Okta link.


  1. I did not join my company’s teams:


The most common causes are:

  • wrong/misspelled attribute names in your Okta

  • wrong/misspelled group names in your Okta 

  • no user assignment to the teams in the Okta Groups

  • The “Teams” group attribute set to something else than “detectify”, eg. detectify.admin.MyTeam - this setup does not let all the users join the company’s teams as admins. The teams’ names as well as the user permission level need to be set in the Okta Groups.


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!