Skip to main content
ASAPP recommends that customers use SSO to authenticate agents and admin users to our applications. In this scenario:
  1. ASAPP acts as the Service Provider (SP) while the customer serves as the Identity Provider (IDP).
  2. The customer’s authentication system performs user authentication using their existing customer credentials.
  3. ASAPP supports Service Provider Initiated SSO. Customers provide the SSO URL to agents and admins.
  4. The URL points to the customer’s SSO service, which will authenticate the users via their authentication system.
  5. Once ASAPP authenticates the user, the customer’s SSO service sends a SAML assertion with user information to ASAPP’s SSO service.
  6. ASAPP uses the information inside the SAML assertion to identify the user and redirect them to the appropriate application.
The diagram below illustrates the IDP-initiated SSO flow.

​
Configuring Single Sign-On via SAML

​
Environments

ASAPP supports SSO in non-production and production environments. We strongly recommend that customers configure SSO in both environments.

​
Exchange of SAML metadata

Both ASAPP and the customer generate their respective SAML metadata and exchange the metadata files. Each environment requires different metadata, so teams must generate metadata once per environment. Sample metadata file content: 
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
entityID="https://auth.asapp.com/auth/realms/hudson">
    <SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false"
        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="encryption">
     <dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
      <dsig:KeyName>REDACTED</dsig:KeyName>
      <dsig:X509Data>
       <dsig:X509Certificate>REDACTED</dsig:X509Certificate>
      </dsig:X509Data>
     </dsig:KeyInfo>
    </KeyDescriptor>
 <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Location="https://auth.asapp.com/auth/realms/hudson/broker/hudson-saml/endpoint"/>
 <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified
 </NameIDFormat>
 <AssertionConsumerService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
  Location="https://auth.asapp.com/auth/realms/hudson/broker/hudson-saml/endpoint/clients/asapp-saml"
        index="1" isDefault="true" />
     </SPSSODescriptor>
</EntityDescriptor>

​
SAML Profile Configuration

Next, ASAPP and the customer configure their respective SSO services with each other’s SAML profile. Teams can achieve this by importing the SAML metadata into the SSO service (if it supports a metadata import feature).

​
SAML Attributes Configuration

SAML Attributes are key-value fields within the SAML message (also called SAML assertion) that the Identity Provider (IDP) sends to the Service Provider (SP). ASAPP requires the following fields to be included with the SAML assertion
Attribute NameRequiredDescriptionExample
userIdyesuser’s unique identifier used for authentication. Can be a unique readable value such as user’s email or an opaque identifier such as a customer’s internal user ID.[email protected]
firstNameyesuser’s first nameJohn
lastNameyesuser’s last nameDoe
nameAliasyesuser’s display name. Allows an agent, based on their personal preference or company’s privacy policy, to set an alias to show to the customers they are chatting with. If this is not sent then the agent firstName will be displayed.John Doe
rolesyesthe roles the user has within the ASAPP platform. Typically mapped to one or more AD Security Groups on the IDP.representativemanager
The following fields are not required but desired to further automate the agent Desk configuration:
Attribute NameRequiredDescriptionExample
groupsnogroup(s) the user belongs to. This attribute controls the queue(s) that a user is assigned to. Not to be confused with the AD Security Groups (see the roles attribute above)residentialbusiness
concurrencynonumber of concurrent chats the user can handle5
In addition, any custom fields can be configured in the SAML assertion. See the section below for more details.

​
Sending User Data via SAML

ASAPP uses SAML attribute fields to keep user data current in our system. This also allows us to register new users automatically when they log into the ASAPP application for the first time. In addition to the required fields that ASAPP needs to identify the user, customers can send additional fields in the SAML assertion that can be used for other purposes such as Reporting. An example can be the Agent Location. These fields are specific per customers. The name and possible values of these fields need to be agreed upon and configured prior to the SAML implementation.

​
SSO Testing

SSO testing between the customer and ASAPP must be a coordinated effort due to the nature of the IDP-initiated SSO flow. The customer must provide several user accounts to be used for testing. Generally, the test scenarios are as follows:
  1. An agent logs in for the first time. ASAPP observes that a new user record is created and the agent lands on the correct ASAPP application for their role (Desk for a rep, Admin for supervisor/manager).
  2. The same agent logs out and logs back in. The agent observes that the correct application still opens.
  3. Repeat the same test for another user account, ideally with different roles.
Once testing is completed successfully, then the SSO flow is certified for that environment. Setting up SSO in the Production environment should follow the same steps.