DOCUMENTATION
Page tree
Skip to end of metadata
Go to start of metadata

Last updated: Jan 19, 2021 10:02

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.

Note: 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.

Limitation: SSO is not supported in the Public Cloud or with subscription plans.

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. 

On this page:

  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.

    Note: 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.perfectomobile.com/auth/realms/<CLOUDNAME>-perfectomobile-com/broker/<CLOUDNAME>-idp/endpoint
      For example: https://auth.perfectomobile.com/auth/realms/mycloud-perfectomobile-com/broker/mycloud-idp/endpoint
    • Entity Id/Vendor ID:  
      https://auth.perfectomobile.com/auth/realms/<CLOUDNAME>-perfectomobile-com
      For example: https://auth.perfectomobile.com/auth/realms/mycloud-perfectomobile-com

    where <CLOUDNAME> is the name of your cloud, as shown in the examples.

  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:

      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. 

Sample Perfecto Metadata file 
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://auth.perfectomobile.com/auth/realms/mycloud-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.perfectomobile.com/auth/realms/mycloud-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.perfectomobile.com/auth/realms/mycloud-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.perfectomobile.com/auth/realms/CLOUDNAME-perfectomobile-com
    where CLOUDNAME is the name of your cloud

  • The following SAML user attributes:
    • NameID
    • email
    • firstName

    • lastName
      SAML response example:

      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>

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

We recommend that you contact your IdP to:

  • 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.


OKTA
  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.perfectomobile.com/auth/realms/<CQLab-name>.perfectomobile.com/broker/<CQLab-name>-okta/endpoint
    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. 
CA (formerly CA SiteMinder)
  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 given 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 don't 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. 
Azure-based Active Directory
  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.perfectomobile.com/auth/realms/<cloud-name>-perfectomobile-com
    Reply URL: https://auth.perfectomobile.com/auth/realms/<cloud-name>-perfectomobile-com/broker/<cloud-name>-idp/endpoint
    where <cloud-name> is the name of your Perfecto cloud instance.
  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:

Related articles: