Recognize provides Single Sign-On SAML v2.0 capabilities. Companies can connect via identity providers such as Azure/EntraID, Okta, Google, and OneLogin. If you need assistance implementing any of these, you can find more information about each below:
- Setting up Single Sign-on (SSO) with Azure via Azure Gallery
- Setting up Single Sign-on (SSO) Using Active Directory with ADFS and SAML
- Setting up single sign on (SSO) with Azure Active Directory (manual app)
- Configuring Okta SSO with Recognize
To enable single sign on in Recognize, access your settings in the admin portal by going to Menu > Company Admin > Settings.
What is the Recognize "IDP" page?
IDP stands for "Identity Provider". The IDP page is a landing page which presents user's with choices on how to login. The choices shown can be enabled or disabled by the company admins depending on which "identity providers" you would like to allow user's to login with. This can include: Microsoft, Google, Username/Pass, and SSO. This url is https://recognizeapp.com/<youraccount>/idp.
Some organizations will only allow one identity provider such as their Single Sign On IDP, but others may permit several. If your organization permits several identity providers, this is a great landing page to direct users to log in to Recognize.
What does "Force SSO" do?
If a user enter's their email on the Recognize homepage and the Force SSO setting is enabled, the user will be "forced through SSO". If the Force SSO setting is NOT enabled, then the user will be redirected to the IDP page described above.
Some companies will enable Force SSO, which keeps end users away from the IDP page, but they will train administrators on the IDP page which may contain alternate backup login mechanisms as a failsafe in case the SSO configuration were to stop working.
What is the difference between Microsoft OAuth login and SSO if I use Azure?
The difference here is mostly technical and transparent to users. For end users, ultimately the login mechanism will validate in the same way as they will be routed through Azure. However, if a user initiates login with the "Sign in with Microsoft" button which routes through the OAuth protocol, the first time they do this they will be presented with a consent screen to access their account. This gives Recognize a token to read their profile and sync their avatar image. We are unable to sync avatar images with SSO unless a separate "User sync" connection is established by an admin.
Setting up single sign on (SSO) with Azure (via Azure Gallery)
NOTE: if you are using ADFS, see this article: https://recognize.zendesk.com/hc/en-us/articles/226678267-Setting-up-single-sign-on-using-Active-Directory-with-ADFS-and-SAML
Single Sign-on With Recognize and Azure AD
In this tutorial, you learn how to integrate Recognize with Azure Active Directory (Azure AD).
Integrating Recognize with Azure AD provides you with the following benefits:
- You can control in Azure AD who has access to Recognize
- You can enable your users to automatically get signed-on to Recognize (Single Sign-On) with their Azure AD accounts
- You can manage your accounts in one central location - the Azure portal
If you want to know more details about SaaS app integration with Azure AD, see what is application access and single sign-on with Azure Active Directory.
Prerequisites
To configure Azure AD integration with Recognize, you need the following items:
- An Azure AD subscription
- A Recognize single sign-on enabled subscription
- An admin account in both Azure AD and Recognize
Note
To test the steps in this tutorial, we do not recommend using a production environment.
To test the steps in this tutorial, you should follow these recommendations:
- Do not use your production environment, unless it is necessary.
- If you don't have an Azure AD trial environment, you can get a one-month trial here: Trial offer.
Scenario description
In this tutorial, you test Azure AD single sign-on in a test environment. The scenario outlined in this tutorial consists of two main building blocks:
- Adding Recognize from the gallery
- Configuring and testing Azure AD single sign-on
Adding Recognize from the gallery
To configure the integration of Recognize into Azure AD, you need to add Recognize from the gallery to your list of managed SaaS apps.
To add Recognize from the gallery, perform the following steps:
-
In the Azure portal, on the left navigation panel, click Azure Active Directoryicon.
-
Navigate to Enterprise applications. Then go to All applications.
-
To add new application, click New application button on the top of dialog.
-
In the search box, type Recognize.
-
In the results panel, select Recognize, and then click Add button to add the application.
Configuring and testing Azure AD single sign-on
In this section, you configure and test Azure AD single sign-on with Recognize based on a test user called "Britta Simon".
For single sign-on to work, Azure AD needs to know what the counterpart user in Recognize is to a user in Azure AD. In other words, a link relationship between an Azure AD user and the related user in Recognize needs to be established.
In Recognize, assign the value of the mail in Azure AD as the value of the NameID to establish the link relationship. UserPrincipalName is supported, please contact Recognize Support team if you wish to link based on UPN.
To configure and test Azure AD single sign-on with Recognize, you need to complete the following building blocks:
- Configuring Azure AD Single Sign-On - to enable your users to use this feature.
- Creating an Azure AD test user - to test Azure AD single sign-on with Britta Simon.
- Creating a Recognize test user - to have a counterpart of Britta Simon in Recognize that is linked to the Azure AD representation of user.
- Assigning the Azure AD test user - to enable Britta Simon to use Azure AD single sign-on.
- Testing Single Sign-On - to verify whether the configuration works.
Configuring Azure AD single sign-on
In this section, you enable Azure AD single sign-on in the Azure portal and configure single sign-on in your Recognize application.
To configure Azure AD single sign-on with Recognize, perform the following steps:
-
In the Azure portal, on the Recognize application integration page, click Single sign-on.
-
On the Single sign-on dialog, select Mode as SAML-based Sign-on to enable single sign-on.
-
On Step 1 section, click Edit:
- Delete any sample values.
- In a new tab or browser, visit Recognize's Company Admin portal and visit Settings > User management and scroll to Single Sign On section. It is here that you will retrieve the settings necessary to enter into section 1, Basic SAML Configuration.
- Copy the appropriate settings from Recognize into the SAML Configuration.
-
a. In the Identifier textbox, type a URL using the following pattern:
https://recognizeapp.com/<your-domain>/saml/metadata
b. In the Reply URL textbox, type a URL using the following pattern:https://recognizeapp.com/<your-domain>/saml/acsb. In the Sign-on URL textbox, type a URL using the following pattern: /saml/sso"
https://recognizeapp.com/<your-domain>/saml/sso -
Click Save button. This completes the configuration Recognize's settings on the Azure side. Now you need to obtain the Azure settings for entry on the Recognize side.
-
On the SAML Signing Certificate section, click Certificate (Base64) and then save the certificate file on your computer.
-
On the Recognize Configuration section, click Configure Recognize to open Configure sign-on window. Copy the Sign-Out URL, SAML Entity ID, and SAML Single Sign-On Service URL from the Quick Reference section.
-
Perform the following steps on SSO Settings section.
a. As Enable SSO, select ON.
b. In the IDP Entity ID textbox, paste the value of SAML Entity ID which you have copied from Azure portal.
c. In the Sso target url textbox, paste the value of SAML Single Sign-On Service URL which you have copied from Azure portal.
d. In the Slo target url textbox, paste the value of Sign-Out URL which you have copied from Azure portal.
e. Open your downloaded Certificate (Base64) file in notepad, copy the content of it into your clipboard, and then paste it to the Certificate textbox.
f. Click the Save settings button.
Testing
In order to test the configuration, you will need an AzureAD user assigned to the Enterprise Application and you will need a corresponding user provisioned in Recognize.
Assigning the Azure AD test user
In this section, you enable Britta Simon to use Azure single sign-on by granting access to Recognize.
To assign Britta Simon to Recognize, perform the following steps:
-
In the Azure portal, open the applications view, and then navigate to the directory view and go to Enterprise applications then click All applications.
-
In the applications list, select Recognize.
-
In the menu on the left, click Users and groups.
-
Click Add button. Then select Users and groups on Add Assignment dialog.
- On Users and groups dialog, select Britta Simon in the Users list.
- Click Select button on Users and groups dialog.
- Click Assign button on Add Assignment dialog.
Testing single sign-on
Now that the configuration is complete and you have a corresponding test user in Recognize that is assigned to this AzureAD application, this section will show you the best practices for testing the configuration. You will need to be able to sign in as the test user.
NOTE: It is recommended to do this in a separate browser or private browser mode, while you retain your original browser session that is logged into AzureAD and Recognize in a secondary tab.
- To test the initial connection, simply visit https://recognizeapp.com/<yourdomain.com/saml/sso. If you are presented with your Azure AD sign on page, then the initial connection is working properly.
- Then proceed to sign in. If the connection is successful, you will be redirected back to Recognize and signed in to Recognize.
Setting up single sign-on using Active Directory with ADFS and SAML
Recognize supports single sign-on (SSO) logins through SAML 2.0. A SAML 2.0 identity provider (IDP) can take many forms, one of which is a self-hosted Active Directory Federation Services (ADFS) server. ADFS is a service provided by Microsoft as a standard role for Windows Server that provides a web login using existing Active Directory credentials.
Please note this instructions are for ADFS v3.0 and up.
Requirements
To use ADFS to log in to your Recognize account, you need the following components:
- An Active Directory instance where all users have an email address attribute.
- A Recognize account with one of our paid packages.
- A server running Microsoft Server 2012 or 2008. This guide uses screenshots from Server 2012R2, but similar steps should be possible on other versions.
- A SSL certificate to sign your ADFS login page and the fingerprint for that certificate.
After you meet these basic requirements, you need to install ADFS on your server. Configuring and installing ADFS is beyond the scope of this guide, but is detailed in a Microsoft KB article.
When you have a fully installed ADFS installation, note down the value for the 'SAML 2.0/W-Federation' URL in the ADFS Endpoints section. If you chose the defaults for the installation, this will be '/adfs/ls/'.
Step 1 - Adding a Relying Party Trust
At this point you should be ready to set up the ADFS connection with your Recognize account. The connection between ADFS and Recognize is defined using a Relying Party Trust (RPT).
Select the Relying Party Trusts folder from AD FS Management, and add a new Standard Relying Party Trust from the Actions sidebar. This starts the configuration wizard for a new trust.
- In the Select Data Source screen, select the last option, Enter Data About the Party Manually.
- On the next screen, enter a Display name that you'll recognize in the future, and any notes you want to make.
- On the next screen, select the ADFS FS profile radio button.
- On the next screen, leave the certificate settings at their defaults.
- On the next screen, check the box labeled Enable Support for the SAML 2.0 WebSSO protocol. The service URL will be https://recognizeapp.com/domain/saml/acs, replacing domain with your Recognize domain. Note that there's no trailing slash at the end of the URL.
- On the next screen, add a Relying party trust identifier of recognizeapp.com.
- On the next screen, you may configure multi-factor authentication but this is beyond the scope of this guide.
- On the next screen, select the Permit all users to access this relying party radio button.
- On the next two screens, the wizard will display an overview of your settings. On the final screen use the Close button to exit and open the Claim Rules editor.
Step 2 - Creating claim rules
Once the relying party trust has been created, you can create the claim rules and update the RPT with minor changes that aren't set by the wizard. By default the claim rule editor opens once you created the trust.
- To create a new rule, click on Add Rule. Create a Send LDAP Attributes as Claims rule.
- On the next screen, using Active Directory as your attribute store, do the following:
1. From the LDAP Attribute column, select E-Mail Addresses.
2. From the Outgoing Claim Type, select E-Mail Address.
- Click on OK to save the new rule.
- Create another new rule by clicking Add Rule, this time selecting Transform an Incoming Claim as the template.
- On the next screen:
1. Select E-mail Address as the Incoming Claim Type.
2. For Outgoing Claim Type, select Name ID.
3. For Outgoing Name ID Format, select Email.
Leave the rule to the default of Pass through all claim values.
- Finally, click OK to create the claim rule, and then OK again to finish creating rules.
Step 3 - Adjusting the trust settings
You still need to adjust a few settings on your relying party trust. To access these settings, select Properties from the Actions sidebar while you have the RPT selected.
- In the Advanced tab, switch from SHA-256 to SHA-1.
- In the Endpoints tab, click on add SAML to add a new endpoint.
- For the Endpoint type, select SAML Logout.
- For the Binding, choose POST.
- For the Trusted URL, create a URL using:
1. The web address of your ADFS server
2. The ADFS SAML endpoint you noted earlier
3. The string '?wa=wsignout1.0'
The URL should look something like this: https://sso.yourdomain.tld/adfs/ls/?wa=wsignout1.0. - Confirm you changes by clicking OK on the endpoint and the RPT properties. You should now have a working RPT for Recognize.
Step 4 - Configuring Recognize
After setting up ADFS, you need to configure your Recognize account to authenticate using SAML. You'll use your full ADFS server URL with the SAML endpoint as the SSO URL, and the login endpoint you created as the logout URL. The certificate will be the token signing certificate installed in your ADFS instance.
You can get the certificate by running the following PowerShell command on the system with the installed certificate:
C:\> Get-AdfsCertificate -CertificateType Token-Signing
The certificate needs to be the base64 encoded version, the DER encoded certificate. See these articles:
- https://blogs.technet.microsoft.com/adhall/2014/02/19/how-to-export-the-ad-fs-token-signing-certificate-with-powershell/
- https://mssec.wordpress.com/2014/03/06/what-is-the-difference-between-the-formats-der-encoded-and-base64-encoded-when-exporting-a-certificate/
After you're done, the SSO Settings page in the Recognize Company Admin should look similar to this:
You should now have a working ADFS SSO implementation for your Recognize account.
Attribution credit to Zendesk for their great article on SAML setup here: https://support.zendesk.com/hc/en-us/articles/203663886-Setting-up-single-sign-on-using-Active-Directory-with-ADFS-and-SAML-Professional-and-Enterprise-
Setting up single sign on (SSO) with Azure Active Directory (manual app)
In order to setup SSO with Recognize and your Azure Active Directory, you will need to set up an application Azure Active Directory. Please follow the instructions here: https://blogs.technet.microsoft.com/enterprisemobility/2015/06/17/bring-your-own-app-with-azure-ad-self-service-saml-configuration-now-in-preview/
1. Select "Microsoft Azure AD Single Sign-On"
2. Enter identifier and reply url.
Identifier and reply url are found in the Recognize Company Admin > Settings > SSO settings section. Identifier is also known as the "Service Provider Metadata Url". Reply url is also known as the ACS (Consumer) Url.
3. Download the certificate in Base64 format
4. Copy the settings into the Recognize SSO Advanced configuration
IDP Entity ID - use the Issuer URL
SSO Target URL - use the Single Sign On Service Url
SLO Target URL - use the Single Sign out Service Url
Name Identifier - Most common configurations leave this alone
Certificate - You will need to open the base 64 certificate you downloaded in step 3 in a text editor and copy and paste the entire contents of the file including the "BEGIN CERTIFICATE" and "END CERTIFICATE" lines.
5. Back in Azure AD, click "Confirm that have you configured Single Sign On..." and submit the form to save your SSO configuration.
Setup is now complete!
Test your configuration by visiting the following url in a different or incognito/private browser: https://recognizeapp.com/<recognize-tenant-domain>/saml/sso
Configuring Okta SSO with Recognize
1. Recognize's Okta SSO integration can be installed starting from the Okta App Integration Catalog
2. Search for "Recognize"
3. This will take you the app listing. Click on "Add Integration"
4. You may customize the Application Label such as to "Recognize SSO". The important part is to add in the "Domain Name" which is the "domain" or account identifier of your Recognize account. In most cases, this corresponds to your main company web domain. You can find this by logging into Recognize and looking at the url. Whatever appears after "https://recognizeapp.com/" is your account domain.
Please NOTE: there is an error in the Okta documentation where it says that if your account domain is "Acme.com" to enter just "Acme". This is incorrect and you should enter the entire domain "acme.com".
5. After your application is created, you will be taken to this page. Please click on "Sign On".
6. On the Sign On page, you will see the following. Scroll down until you see "Metadata Url".
7. Copy the Metadata URL into your clipboard
8. Go to your Recognize account and visit the Company Admin > Settings > User Management > SSO Settings. Paste the Metadata URL into this section. *Please note you will need an account on Recognize that has a Company Admin System Role to access this page and section to enter this url.
9. Toggle "Enable SSO" to ON.
10. Test your SSO sign-in:
If Force SSO is enabled, test by replacing the bolded section of the URL below with your Recognize Company domain: https://recognizeapp.com/insertdomainhere.com/saml/sso
If Force SSO is not enabled, test by replacing the bolded section of the URL below with your Recognize Company domain: https://recognizeapp.com/insertdomainhere.com