Perfecto SSO for external IdP

Single sign-on (SSO) authentication means that you can use a single set of credentials to log into several different applications/services. This is especially useful in a corporate setting where you want your employees to be able to access a variety of applications using their company credentials.

Many corporations use different Identity Providers (IdP) to manage their SSO systems. The most commonly used third-party IdPs are ADFS 2.0/3.0, PingFederate/PingOne, Okta, CA, and Azure-based Active Directory. Perfecto supports SSO with any IdP that supports SAML 2.0.

To implement SSO authentication, you need to work closely with Perfecto Support.

Limitations

The following limitations apply:

  • SSO is not supported in the public cloud or with subscription plans.

  • SSO with Perfecto is an authentication method, not an integration. It does not sync the individual accounts in a user store to the Perfecto Lab.

  • Perfecto supports role-based access control (RBAC) with IdPs, but Perfecto's SSO provider cannot handle a scenario where the validation fails because the user does not have the required authorization role assigned and access is denied. In this case, instead of displaying the proper error message, the browser starts redirecting to the IdP login page continuously. If this happens, contact your IdP or your IT department for proper access.

  • SAML role mapping is currently not supported.

  • Safari browser users may face login issues. To avoid this, under Safari > Settings, on the Privacy tab, clear the Prevent cross-site tracking checkbox.

IdP requirements

The IdP you select must support the following:

  • SP-initiated SSO

  • SAML 2.0

SSO flow with Perfecto

The following diagram provides a high-level overview of the Perfecto SSO sign-in flow.

  1. A user accesses the Perfecto cloud, such as https://mycloud.perfectomobile.com/.

  2. Perfecto forwards the request to the IdP, and the user is redirected to the IdP login page.

  3. The user logs in with the company credentials.

  4. The IdP validates the user against the user store.

  5. The IdP sends SAML (Security Assertion Markup Language) assertion back to Perfecto. At a minimum, the SAML assertion response from the IdP must contain the desired username for the Perfecto cloud (if it is not the user's email, the cloud should be configured accordingly). The response typically also includes the email address, given name, and last name attributes as parameters, but they are not required to enable SSO. 

  6. The user is authenticated and logged into the Perfecto Lab session.

SSO setup steps

Setting up SSO with Perfecto is a process that involves close cooperation between your company and Perfecto Support. It consists of the following steps:

  1. Discover: After finalizing IdP selection, Perfecto and the IdP need to replace SAML 2.0 metadata. See What Perfecto needs from your IdP below for instructions on how to obtain your IDP metadata. When you acquire the metadata, make sure it is validated against the SAML 2.0 XSD (for example, you can use this login validation tool: https://www.samltool.com/validate_xml.php).

  2. Initial setup: Open a ticket with  Perfecto Support that includes your IdP metadata. A member of the Perfecto Support team then sets up the connection from Perfecto (the SP) to your IdP.

    Similarly, on your end, you need to set up the connection from your IdP to Perfecto using the Perfecto metadata file. See What you need from Perfecto to set up your connection below for details.

    Important: You need to provide your IdP metadata to Perfecto before Perfecto can provide the Perfecto metadata file. However, if needed, you can create your IdP metadata manually using the following fields:

    • Single sign-on URL/Endpoint URL:

      https://auth<x>.perfectomobile.com/auth/realms/<cloud-name>-perfectomobile-com/broker/<cloud-name>-idp/endpoint

      For example: https://auth<x>.perfectomobile.com/auth/realms/<cloud-name>-perfectomobile-com/broker/<cloud-name>-idp/endpoint

    • Entity Id/Vendor ID:  

      https://auth<x>.perfectomobile.com/auth/realms/<cloud-name>-perfectomobile-com

      For example: https://auth<x>.perfectomobile.com/auth/realms/<cloud-name>-perfectomobile-com

    where:

    • <cloud-name> is the name of your cloud, as shown in the examples.

    • <x> is your tenant's SSO number. To find your tenant's SSO number, access your cloud in a browser and extract it from the URL.

  3. Test: Verify the SSO connection between the Perfecto cloud and your IdP with one or two users. After accessing the Perfecto URL, these users should be redirected to your IdP login page, where they enter their IdP user credentials. When the IdP provider accepts their credentials, they should be logged in to the Perfecto cloud.

    Important: This step takes 30-60 minutes. During this time, affected users cannot log in to the Perfecto cloud. 

  4. Production setup: During this step, Perfecto enables the IdP configuration and migrates all users. The migration path depends on the type of usernames you use:

    Important: This step takes 30-60 minutes. During this time, affected users cannot log in to the Perfecto cloud.

    • Email usernames:  Both your IdP and the Perfecto cloud use email usernames. In this case, Perfecto automatically migrates all cloud users to the new configuration during this session. For automated testing, you can either provide automation users in advance to be skipped or replace their security token after the session.

    • ID usernames: Your IdP uses ID usernames and your Perfecto cloud uses email usernames. In this case, Perfecto renames the email to an ID. You need to set up a comma-separated mapping file that correlates a user's email address in the Perfecto system with the user ID in the IdP system. For example:

      Copy 
      johod@test.com,jdoe
      johod1@test.com,jdoe1
      johod2@test.com,jdoe2

      For more details about creating new users, see New users.

New users

When a new user gets added to the IdP system and passes identification, Perfecto automatically adds the user if it does not exist. For details, see Just-in-time (JIT) user provisioning. If you want to control a user's access to the Perfecto cloud, you can do this through the IdP authorization (by assigning the user to your Perfecto application within your IdP). You can also turn off JIT entirely by sending a request to Perfecto Support.

By default, all new users get created without assigned roles and device tokens. You can opt to configure roles and tokens globally if required. If you want to change role and token assignments for individual users, your admin can do this manually.

Important: User management in the Perfecto cloud is not connected to the user management of the IdP system. Therefore, when deleting/retiring a user from the IdP, you need to do the same on the Perfecto side even though the user can no longer log in.

What you need from Perfecto to set up your connection

You need to obtain the Perfecto metadata file for your installation. Contact Perfecto SSO support personnel to supply the file. The file is in XML format and includes your installation license.

Copy

Sample Perfecto Metadata file

<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://https://auth<x>.perfectomobile.com/auth/realms/<cloud-name>-perfectomobile-com"> 
    <SPSSODescriptor AuthnRequestsSigned="true" 
            protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol urn:oasis:names:tc:SAML:1.1:protocol http://schemas.xmlsoap.org/ws/2003/07/secext"> 
        <KeyDescriptor use="signing"> 
            <dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"> 
                <dsig:X509Data> 
                    <dsig:X509Certificate> 
eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiIxMjdmMWVlZS0zYzIwLTRkYjAtYTE2NC00M2ZkMjMzZWM4M2IiLCJleHAiOjAsIm5iZiI6MCwiaWF0IjoxNDk5MDc5OTUxLCJpc3MiOiJodHRwczovL2F1dGguYXdzLXN0Zy5wZXJmZWN0b21vYmlsZS5jb20vYXV0aC9yZWFsbXMvbWNtLXNzby1wZXJmZWN0b21vYmlsZS1jb20iLCJhdWQiOiJvZmZsaW5lLXRva2VuLWdlbmVyYXRvciIsInN1YiI6IjhhNjk4YmJjLWY3MWItNDk2YS04MWM1LTFhNWMzMTlmZjU2NiIsInR5cCI6Ik9mZmxpbmUiLCJhenAiOiJvZmZsaW5lLXRva2VuLWdlbmVyYXRvciIsInNlc3Npb25fc3RhdGUiOiI2OGU3MTEzYy1hNjQyLTQ3NDQtODE3MC05ZTQ3YzczMDE2YzciLCJjbGllbnRfc2Vzc2lvbiI6IjI2ZDg3M2MwLWZhZGItNGFkNS04MTUyLWVlMzg0NWRlYzc3NiIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJ2aWV3LXByb2ZpbGUiXX19fQ.oZjhXTA9dFq1WF-gKEjyX4cTRuUVBcT6dPGAU0Wrx2ltX1-siRm4gbUIp5O9jatBflYIogCcga3xgo0C57MxprTmnw9-ZFzgBlLu6qUZyDyQTs3KJYjAsEd36cP6I9EfbQhlUde_RNMgBOt1W0yaw5wQmKNhT93-BOqYAZ7MaEdO_SUf80PO6cO1mPwsLGhzIBLJp73Vw-VDquXOKrIb4HP1g4Rm1xAaBKC2fGSpmKQGkX3zL6meAniDxQbb1JdvcVwxoJDXb_s2GFOzV7C8v8qG6KKtUahZL5FFucHbKov3F_jKA_xazT3PnSvLZ-EQTPhYrDBWbNG7flD-BwDJPA 
                    </dsig:X509Certificate> 
                </dsig:X509Data> 
            </dsig:KeyInfo> 
        </KeyDescriptor> 
        <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://auth<x>.perfectomobile.com/auth/realms/<cloud-name>-perfectomobile-com/broker/mycloud-ca/endpoint"/> 
        <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent </NameIDFormat> 
        <AssertionConsumerService 
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://auth<x>.perfectomobile.com/auth/realms/<cloud-name>-perfectomobile-com/broker/mycloud-ca/endpoint" 
                index="1" isDefault="true" /> 
    </SPSSODescriptor> 
</EntityDescriptor>

What Perfecto needs from your IdP

You need to supply the IDP metadata file to Perfecto. In addition, Perfecto requires that you configure:

  • NameID Policy Format to unspecified (optional but recommended)

  • Audience Restriction/Audience URI to empty or to our entity ID, which is
    https://auth<x>.perfectomobile.com/auth/realms/<cloud-name>-perfectomobile-com

    where:

    • <cloud-name> is the name of your cloud

    • <x> is your tenant's SSO number. To find your tenant's SSO number, access your cloud in a browser and extract it from the URL.

  • The following SAML user attributes:

    • NameID

    • email

    • firstName

    • lastName

      Copy

      SAML response example

      <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">jhon.doe@mycloud.com</saml2:NameID>
      ...   
       <saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
            <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
              <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">jhon.doe@mycloud.com</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="firstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
              <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Jhon</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="lastName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
              <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Doe</saml2:AttributeValue>
            </saml2:Attribute>
          </saml2:AttributeStatement>

    • Destination

      Copy

      SAML response example

      <samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                      ID="_97c7a054-a5e5-4761-92e8-829d9b8fc995"
                      Version="2.0"
                      IssueInstant="2021-03-08T11:19:02.139Z"
                      Destination="https://auth<x>.perfectomobile.com/auth/realms/<cloud-name>-perfectomobile-com/broker/CLOUD-idp/endpoint"
                      InResponseTo="ID_add6bd08-724a-4ac8-b931-e324eecd2acc"

You also need to assign your IdP users to the Perfecto application within your IdP.

Consider contacting your IdPto:

  • Extract the SAML 2.0 metadata file 
  • Assign users (also for optimal IdP configuration and setup).

Below are high-level instructions on how to do the above for some of the common IdPs. These instructions serve as a reference only. Make sure to verify them with your specific IdP.

  1. Register a new OKTA app:

    Click the profile name > your org > Admin > Applications > add application > create new app > SAML 2 > enter a name, and click Next.

  2. For Single sign-on URL, enter the following: 

    https://auth<x>.perfectomobile.com/auth/realms/<cloudname>.perfectomobile.com/broker/<cloud-name>-okta/endpoint

    where:

    • <cloud-name> is the name of your Perfecto cloud instance.

    • <x> is your tenant's SSO number. To find your tenant's SSO number, access your cloud in a browser and extract it from the URL.

    For Audience URI (SP Entity ID), enter the IDP name.

  3. Click Next. Then select I'm an Okta customer adding an internal app.
  4. Click the Identity Provider metadata link to download the IDP metadata.
  5. Save the downloaded metadata file and supply it to Perfecto Support personnel.
  6. To integrate users with Perfecto applications, go to the created application (Admin > Applications > Perfecto application) and click Assign. The user is attached to the Perfecto application.
  1. Go to Apps > add an app > can't find your app link.
  2. In the wizard that opens, do the following:
    1. in the Basic info field, enter a display name, for example Perfecto.
    2. Click Download IDP metadata. Then click Continue.
    3. Use the Perfecto metadata file and upload it to the current wizard step.
    4. Finish the wizard with defaults.
  3. To have users integrated with Perfecto applications, CA has to have at least one department. If you do not have a department, create one:
    1. Click Admin > Organization.
    2. Select Departments.
    3. Enter a name and click Add.
  4. Click Rules.
  5. Add the department of the user as a rule to assign the application to the user.
  1. Go to the Azure classic portal, select the Active Directory sub menu, and select the active directory you want to use for SSO.
  2. In the top navigation bar, go to Applications.
  3. At the bottom of the screen, click Add.
  4. Select Add an application from the gallery.
  5. Select Custom > Add an unlisted application my organization is using and enter Perfecto as the application name. Click the check button when done.
  6. Select Configure single sign-on > Microsoft Azure AD Single Sign-On.

  7. Place the identifier and Reply URL information that the Perfecto SSO team provided for you in the corresponding fields, as follows:

    Identifier:  https://auth<x>.perfectomobile.com/auth/realms/<cloud-name>-perfectomobile-com

    Reply URL:  https://auth<x>.perfectomobile.com/auth/realms/<cloud-name>-perfectomobile-com/broker/<cloud-name>-idp/endpoint

    where:

    • <cloud-name> is the name of your Perfecto cloud instance.

    • <x> is your tenant's SSO number. To find your tenant's SSO number, access your cloud in a browser and extract it from the URL.

  8. On the Download Metadata (XML) page, select the option to confirm that you have configured SSO and click Next.

  9. Enter the email address to use for notifications about maintenance issues.
  10. When you are back on the applications main page, navigate to Attributes.
  11. Under SAML Token Attributes, hover over the line where TYPE is user attribute (nameid) (usually the first one) and click the pencil icon to edit.
  12. Change the attribute value to user.mail and click the check button.
  13. At the bottom of the screen, click Apply Changes.
  14. Add users to the Perfecto application in Azure.

For other or custom IdPs, contact your IdP directory to assist with obtaining the metadata file.

Also in this section