Certificate Authentication Workflow
This pages describes the implementation of certificate-based Authentication. For the API reference of Certificate Session Authenticate and Certificate Key Manager Authenticate, see the following API endpoints:
Note: The following authentication sequence is provided out of the box by our dedicated BDK and WDK toolkits. To learn more about authenticating using the SDKs or BDK proceed to one of following configuration guides:
Overview of Certificate-Based Authentication
Symphony allows you to authenticate on the Pod and Key Manager with a client certificate that is signed by a trusted root certificate. When a bot calls the Session Authenticate endpoint, the Pod examines the client certificate provided in the TLS session to identify the bot user and return a Session Token. The same process occurs when a bot authenticates on the Key Manager.
All Symphony network communications take place over TLS-protected HTTP. The network uses authentication methods that require a client-authenticated TLS connection.
Client certificate authentication in TLS is configured at the port level. Two distinct ports are required for client-authenticated and non-client-authenticated connections. The web and mobile endpoints listen on port 443 (the default port number for HTTPS connections). The API endpoints require a separate port, typically port 8444.
Summary
The user generates a certificate for bot authentication.
The admin uploads the certificate into the pod using the Admin Console.
The Bot makes a call the the authentication endpoints. Here, the server client certificate provided against the "Signing Certificate" and returns an authentication token.
1. Generate a Certificate
Upload a copy of your Root Certificate Authorities (CA) Public "Signing Certificate" to the Pod. This would then permit authentication to all child certificates produced by this Signing Authority.
You can use the following commands to generate the service account certificate. The certificate must use 4096 bits length. The CA Cert must be imported on the POD via the Admin Console:
USERNAME = Service account username
PASSWORD = Service account key password
CA_CERT = CA certificate file
CA_KEY = CA key file
CA_PASSWORD = CA key password
OUTPUT_PASSWORD = PKCS12 file password
Creating a Certificate Signing Request (CSR):
The following table shows the information you will need to provide to your PKI team:
The Common Name (CN) value must match the name of the Symphony Service Account you created, this should also use the same case value.
Details | Example Values |
Certificate Type | Single Domain Certificate |
Common Name (CN) | demo-bot1 |
Organization | Excelsior Bank |
Department | Collaboration Services |
admin@bots.symphony.com | |
Locality | London |
State / Province | London |
Country | GB |
Key Size | 2048 bits |
2. Upload your Certificate
Please note the below steps can only be performed by a Symphony Pod Administrator as they will have the necessary administrator privileges to access the Administration Portal.
Once you have received your signed certificate, you will need to upload your public certificate to the Symphony Pod.
The certificate should be concerted to a CER or PEM format before it is uploaded
If you have obtained a copy of your Root Certificate Authorities (CA) Public "Signing Certificate", you can upload it using the following steps:
Navigate to the Symphony Admin Console for your Pod (e.g. https://mypod.symphony.com/?admin), then log in with your credentials
Once logged in click the Manage Certificates button then select Import
Drag and drop your Certificate file into the popup window:
Once you have uploaded the certificate file, click Import. If successful you will receive a confirmation message saying that the certificate has been uploaded successfully.
3. Authenticate
To authenticate on the Pod the bot must call the Session Auth endpoint: https://developers.symphony.com/restapi/main/bot-authentication/session-authenticate. Pass along the client certificate provided in the TLS session, returning a Session Token:
A successful response:
To authenticate on the Key Manager, the bot must call the Key Manager Auth endpoint: https://developers.symphony.com/restapi/main/bot-authentication/key-manager-authenticate. Pass along the client certificate provided in the TLS session, returning a Key Manager Token:
A successful response:
Pass the Session Token and Key Manager Token as headers for all subsequent API requests.
Last updated