API keys and client certificates are used to secure exchanges between the Self Help server and third-party products, e.g. Service Apps apps or Salesforce, using single sign-on authentication.  See Operating principle

• API keys are used in Service Apps with connectors.
• Cert Tool, integrated in the Online Studio, enables you to generate client certificates.

Definitions

• An API key is a simple encrypted string that identifies a third-party product, e.g. Service Apps app or Salesforce.
  • This key enables an API, like the Self Help API, to identify users with the relevant rights for using the API.
  • To ensure greater security, the key is associated with a certificate.

• A certificate is an authentication method that confirms the identity of an entity, i.e. third-party product or user.
  • It is an electronic document.
  • It is associated with a certified public key and a private key that is held only by the entity to which the certificate is issued.

Principle for Service Apps and Self Help authentication

Users run a Service Apps app by entering their credentials in Service Apps. This app integrates a Self Help portal and/or virtual agent that will request access to the Self Help server. To do this, users must authenticate in Self Help.

• Authentication is managed using an API key:
  • Users are automatically authenticated in Self Help based on their Service Apps credentials.
  • If they do not have a Self Help account, an account with User access will automatically be created. This account authorizes users to run Self Help project procedures in a Web browser.

• Authentication is not managed using an API key:  
  • Users must log in to Self Help a second time using their Self Help credentials.
  • If they do not have a Self Help account, they will not be able to access Self Help.

Notes

• Only domain administrators can access the Integration menu in an on-premises setup (Note: For SaaS-based customers, the administration of Self Help servers is performed by the EasyVista CMC team).
• An API key is defined for only one Self Help server.
• The client certificate can be a public certificate or an X.509 public key certificate.

• API keys are used in Service Apps with connectors.  See How to use an API key in Service Apps
  • Self Help connectors authorize access to Self Help projects
  • Service Bots connectors authorize access to virtual agents

Caution

• If you delete an API key used by a Service Apps connector, apps will no longer be able to use this key to authenticate in Self Help.
• Information on the API key secret and the PEM file containing the private key can only be retrieved during the creation of the key. If you lose this information, you must regenerate a new API key.
• Client certificates generated using the tool integrated in the Online Studio are not stored in the tool.

Best Practice

• In a Service Apps app, you can use the same API key for the Self Help and Service Bots connectors if all Self Help projects used by the app are hosted on the same server. If this is not the case, you must use a different API key for each server.

Menu access

• API keys: Online Studio > Integration > API Keys

• Certificate tool: Online Studio > Integration > Cert Tool

Screens description

API keys

Name: Name of the API key.

Login: Unique ID of the API key.

Description: Description of the API key.

Client Certificate: Client certificate in CER format.

Expiration Date: Validity end date of the API key.

• After this date, authentication between Service Apps and Self Help will longer be managed by the API key.  See Operating principle

Modification Date: Date on which the API key was last modified.

Authorization: Authorizations granted to third-party products authenticating with the API key.

• This can include the rights to create user accounts and sessions.

Cert Tool

      See How to create a client certificate using the certificate generation tool

Key Type: Cryptographic algorithm that encrypts the certificate. 

• RSA by default.

Key Size: Size of the certificate key in bytes. 

• 2048 by default.

Procedures

How to create an API key

Step 1: Create the new API key

1. Select Integration > API Keys in the Online Studio menu.

2. Click + Add.
 

Step 2: Specify the information on the key and client certificate

1. Enter the name and description of the key.

2. Specify the client certificate.

• You can specify an existing public certificate.
• You can create a new certificate using the tool integrated in the Online Studio by clicking Generate.  See the detailed procedure

3. Specify the validity end date of the key.

4. (optional) Grant the relevant permissions to the third-party product authenticating with this key by ticking the Can Create User Accounts and Can Init Session boxes.

5. Click Add.

The information for using the new API key will appear.
 

Step 3: Retrieve the information for using the key

Caution: Information on the API key secret (2) and the PEM file containing the private key (3) can only be retrieved during this step.

1. Click Copy (1) to retrieve the key ID.

2. Click Copy (2) to retrieve the API secret key.

3. Click Download clientCertifcatePrivateKey.pem (3) to retrieve the PEM file containing the private key.

4. Click Download clientCertificate.cer (4) to download the client certificate in CER format.

5. Click  to close the window.
The list of API keys defined on the server will be refreshed.

How to use an API key in Service Apps

Configure access to a Self Help portal

Step 1: Add a connector to Service Apps

1. Go to Service Apps.

2. Create a Self Help connector.

3. Tick the Cross Service Authentication box.

4. Specify the information on the API key.

Step 2: Create a Service Apps app that will call the Self Help portal

      See the detailed procedure

1. Add an EasyVista Self Help data source that will use the Self Help connector.

2. Add a Self Help widget pointing to this data source.

Step 3: Test the authentication process for accessing Self Help

Check access to the Self Help portal
1. Run the app using a User account that does not exist in Self Help.

2. Check that you can access the Self Help portal.
 

Check the creation of the User account in Self Help

• Via the Online Studio

  1. Access the Online Studio and select Users > Users List.

  2. Check that the User account appears in the list.

  3. Click the account and check that the value of the Created by SSO field is Yes. This means that the account was created using the API key.

• Via the Desktop Studio

  1. Access the Desktop Studio in admin mode.

  2. Check that the User account was created.

Configure access to a virtual agent

Step 1: Add a connector to Service Apps

1. Go to Service Apps.

2. Create a Service Bots connector.

3. Tick the Cross Service Authentication box.

4. Specify the information on the API key.

Step 2: Create a Service Apps app that will call the virtual agent

      See the detailed procedure

1. Add an EasyVista Virtual Agent data source that will use the Service Bots connector.

2. Add a Virtual Agent widget pointing to this data source.

Step 3: Test the authentication process for accessing Self Help

Check access to the Self Help portal
1. Run the app using a User account that does not exist in Self Help.

2. Check that you can access the Self Help portal.
 

Check the creation of the User account in Self Help

• Via the Online Studio

  1. Access the Online Studio and select Users > Users List.

  2. Check that the User account appears in the list.

  3. Click the account and check that the value of the Created by SSO field is Yes. This means that the account was created using the API key.

• Via the Desktop Studio

  1. Access the Desktop Studio in admin mode.

  2. Check that the User account was created.

How to create a client certificate using the certificate generation tool

Step 1: Create the new certificate

1. Select Integration > Cert Tool in the Online Studio menu.

2. Specify the information on the client certificate.

3. Click Generate.

The certificate and private key will be generated.

Step 2: Retrieve the information required for creating the API key

Caution: The client certificate and associated private key are not stored when you exit the tool.

1. Click Download apiCertificate.cer (1) to save the CER file corresponding to the client certificate.

2. Click Download apiCertificatekey.pem (2) to save the PEM file corresponding to the private key associated with the certificate.