This menu is used to manage API keys and client certificates for securing 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.

• An API key is a simple encrypted string that identifies a third-party product such as a Service Apps app. This key enables an API, like the Self Help API to identify users with the relevant rights for 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 associated with a certified public key and a private key that is held only by the entity to which the certificate is issued. 

Operating principle between Service Apps and Self Help

A user runs a Service Apps app by logging in to Service Apps. This app includes a Self Help portal and/or a virtual agent that requires access to the Self Help server. To do this, the user must authenticate in Self Help.

• Authentication is managed using an API key:
  • The user will be identified automatically in Self Help based on the credentials used to log in to Service Apps.
  • If the user does not have an account in Self Help, an account with User access will automatically be created. This account authorizes the user to run Self Help) project procedures in a Web browser.

• Authentication is not managed using an API key:  
  • The user must log in a second time to Self Help using Self Help credentials.
  • If the user does not have an account in Self Help, access to Self Help will not be authorized.

Notes

• Only server administrators are authorized to access the Authentication menu.
• One API key is defined for a given Self Help server.   See Best Practice.
• The client certificate can be a public certificate or an X.509 public key certificate generated using the tool integrated in the Online Studio.
   

API keys used in Service Apps -  See the procedure

• API keys are used by connectors:
  • Self Help connectors authorize access to Self Help projects.
  • Service Bots connectors authorize access to virtual agents.

Caution

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

• The client certificates and the associated private keys generated by the tool are not stored.

Best Practice

• In a Service Apps app, you can use the same API key for both Self Help and Service Bots connectors if all of the 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.

Description of screens

API Keys sub-menu

This displays the list of API keys defined on the Self Help server.

Access: Administration > Authentication > API Keys menu

• You can sort the list of API keys by clicking one of the column headers.
• You can group keys using a specific criterion by clicking the Group By link at the top of the list.
• You can apply a filter to the names of keys by clicking the Filter link at the top of the list.

• Click the name of an API key to see its details.
  • Click Copy to retrieve the key ID.
  • Click Download clientCertificate.cer to download the client certificate in CER format.
             

Functionalities available in the toolbar

• Create a new API key.  See the procedure.

• Modify an API key.

• Duplicate an API key.

• Delete an API key.
  Caution: If you delete an API key used by a connector, Service Apps apps will no longer be able to use this key to authenticate in Self Help.

Cert Tools sub-menu

This is used to access the tool for generating X.509 certificates.

Access: Administration > Authentication > Cert Tools menu

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

Procedures

How to create an API key

Note: Only for server administrators.

Step 1: Create the new API key.

1. Select Administration > Authentication > API Keys in the menu.

2. Click + Create a new API Key.
The Properties window of the key will appear.
         

Step 2: Specify the information on the key and the 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 certificate generation tool. To do this, click Generate Certificate.   See How to create a client certificate using the certificate generation tool.

3. Specify the validity end date of the key.

4. (optional) Select the Can Create User Accounts and Can Init Session options to give these rights to third-party products using this key to authenticate.

5. Click Add.
 The information identifying the API key will appear.

Step 3: Retrieve the information required 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 key secret.

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. Create a Self Help connector.

2. Tick the Cross Service Authentication box.

3. 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: Check that access to Self Help is authorized.

Check access to the Self Help portal
1. Run the app and log in 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. In the Online Studio, select Users > Users list in the menu.

  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. Create a Service Bots connector.

2. Tick the Cross Service Authentication box.

3. 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: Check that access to Self Help is authorized.

Check access to the Self Help portal
1. Run the app and log in 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. In the Online Studio, select Users > Users list in the menu.

  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

Note: Only for server administrators.

Step 1: Create the new certificate.

1. Select Administration > Authentication > Cert Tools in the menu.

The Properties window of the certificate will appear.
         

Step 2: Specify the information on the client certificate.

1. Enter the name of the certificate.

2. Select the encryption algorithm in the Key Type field. By default, it is RSA.

3. Select the size of the key (in bytes) in the Key Size field. By default, it is 2048.

4. Click Generate Certificate.
 The certificate and the private key will be generated.
         

Step 3: Retrieve the information required for creating the API key.

Caution: The client certificate and the associated private key generated by the tool 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.