Overview

Service accounts are provided for the purpose of connecting external systems, not users, to Conga application APIs for integration purposes. This document is intended for administrators of the Application Portal who will create, update, and delete service accounts. The separate document External API Authentication and Authorization Using Service Accounts explains how to request access tokens using a service account.

To begin, navigate to Environment Management in the ADMIN menu, then select the environment in the environments list on the left. Then select the Service Accounts tab.

Create a Service Account

Each service account requires a name for easy reference. The service account is also assigned a system-generated ID, used when requesting access tokens.

Service accounts require an asymmetric RSA key pair, with a minimum key length of 2048 bits. Your organization creates and keeps the private key secure, and the corresponding public key must be provided to the Portal service account in PEM format. See the Appendix of this document for methods of creating or extracting public keys.

A public key in PEM format appears similar to this example, including the BEGIN and END lines:

-----BEGIN PUBLIC KEY-----MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwXcKB5Fp9qFR9qeaV5Sb
KXmOveOYzor3FoSaJ9mG4MkMzFhDP2ipFEiON+E9QzRui/h+DivIWEFfUhy9SAHq 4c2ZdUkDSX/Jhp+ng3u4w5hOluuafYCFHQ8LqNLL778dt1OikhJjfGb7JOoolS1d juZM//O08OzEUwNJ+E8KISevXH7bb7e8m/gnrIMAkJ8TtKusI1gkvm59r3v1c/iI vW1sb8s2s9JTMxjDg63HwmnZ723qOeoAtIxStFsFNLeZrfhno7Ep/+yG2c4MAbD/ NA6j6JtYeYV2DDnvBPH/6MIDskFwrHdGRT7mGyNN2oMMV36A+WwSNsSzNYJKohQ7 lQIDAQAB
-----END PUBLIC KEY-----

Authorize Conga Applications to the Service Account

A service account is authorized to call Conga application APIs only if that Conga application is assigned to the service account. A service account may also be assigned specific roles for each assigned application, which can limit or elevate what API functions the account is authorized to perform. Please refer to the specific Conga application or service API documentation to determine the required roles (if any).

ASSIGN APPLICATIONS AND THEIR ROLES

To authorize access to a Conga application, select the application from the drop-down list and click the Assign button.

Locate the target application in the table. If the application supports roles, select zero or more role(s) from the application's Roles drop-down to grant the service account the corresponding capabilities.

Example: User ID in Conga Price Management is 1546af4b-7ac5-42d6-831d-4364a2a5ed24 for a service account with ID urn:pros:portal:acct:1546af4b-7ac5-42d6-831d-4364a2a5ed24.

Key Rotation with Zero Downtime

Should you want to replace your current public/private key pair, you can do so without downtime*. Each service account supports up to two (2) public keys. Follow this general procedure:

1. Generate or locate the new RSA key pair.
2. Upload the new public key in PEM format to the Application Portal service account's Public Key 2 configuration field. Do not alter or replace the existing key in the Public Key 1 field.
3. Update calling systems which use this service account with the new private key.
4. Once all systems have been updated to use the new key pair, delete the old public key (Public Key 1) from the Portal service account.

*Requires rolling-update capabilities in the external systems that use the service account

Please refer to the tech note External API Authentication and Authorization Using Service Accounts on how to request access tokens using a service account.

Appendix

CREATE A NEW RSA KEY PAIR IN PEM FORMAT USING OPENSSL

1. Create a new key pair:

   openssl genrsa -out privatekey.pem 2048

   The generated "privatekey.pem" file contains both your private key and your public key. You will need the private key to authenticate access to the service account. Keep this file, and secure it from unauthorized access. Do not share this file outside your organization.

2. Extract only the public key:

   openssl rsa -in privatekey.pem -pubout -out publickey.pem

3. The "publickey.pem" file contains the PEM formatted public key to set in the Public Key1 or

   Public Key2 fields of the service account in the Application Portal.

EXTRACT THE PUBLIC KEY FROM AN EXISTING X.509 CERTIFICATE USING OPENSSL

Certificates contain the public key and additional data, but do not contain private keys. You will need access to the corresponding private key to authenticate access to the service account.

1. Locate or download the X.509 certificate file. This example uses the file name "certificate_filename.crt".
2. Use OpenSSL to extract the public key:

openssl x509 -in certificate_filename.crt -noout -pubkey -out publickey.pem

The "publickey.pem" file contains the PEM formatted public key needed by Conga Portal. This file can be shared with other parties, if necessary.

CREATING KEY PAIRS FOR COMMON CRM PLATFORMS

Dynamics 365

Follow the instructions to Create a new RSA key pair in PEM format using OpenSSL (above).

Salesforce

Create and download a self-signed certificate in Salesforce Certificate and Key Management. Salesforce will store the private key. Certificates signed by a recognized Certificate Authority (CA) are also acceptable but not required. Portal does not rely on the certificate, only its corresponding public key which establishes an explicit trust.

Next, follow the instructions to Extract the public key from an existing X.509 certificate using OpenSSL (above).