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.

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.

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