Symphony Messaging Dev Docs
Developer CertificationREST API
  • Start Your Developer Journey
  • Bots
    • Building Bots
    • Planning Your Bot
      • Conversational Bot
      • Interactive Bot
      • Headless Bot
    • Getting Started
      • Getting Started with BDK
      • Creating a Service Account
      • Configuration
      • Truststores
    • Overview of REST API
      • REST API Architecture
      • Overview of Pod API
      • Overview of Key Manager API
      • Overview of Agent API
      • Bot Permissions
      • REST API Reference
    • Authentication
      • RSA Authentication Workflow
      • Certificate Authentication Workflow
    • Datafeed
      • Real-Time Events
      • Overview of Streams
    • Messages
      • MessageML
        • MessageML Basics
          • Content Grouping
          • Text formatting and semantics
          • Tables
          • Images
          • Tags and mentions
            • Enhanced tags notice
          • Style Attributes
          • Special Characters
          • Emojis
        • Elements Interactive Forms
          • Buttons
            • Icon set for Buttons
          • Text Field
          • Masked Text Field
          • Text Area
          • Checkbox
          • Radio Button
          • Dropdown Menu
          • Person Selector
          • Room Selector
          • Date Picker
          • Time Picker
          • Timezone Picker
          • Table Select
          • Regular Expressions - Regex
        • Extensibility UI Actions
          • OpenChat
          • Dialog
        • Entities
          • Standard Entities
          • Custom Entities
      • PresentationML
    • Bots Best Practices
    • Open Source Code Samples
  • Extension Apps
    • Building Extension Apps
    • Planning Your App
    • Getting Started
      • Getting Started with ADK
      • Application Manifest Bundle
      • Add an Extension App to a Symphony Pod
    • Overview of Extension API
      • Initialization
      • Register and Connect
      • Extension API Services
        • Service Interface
        • Register and Subscribe
        • Modules Service
        • Entity Service
          • Entity Advanced Templating
          • Message Format - ExtensionML
        • Applications-Nav Service
        • Share Service
        • Commerce Service
        • Dialogs Service
        • UI Service
          • Receiving Conversation and User Information
          • Filter Function
    • App Authentication
      • Circle of Trust Authentication
      • OBO Authentication
  • Developer Tools
    • Symphony Messaging Generator
    • Bot Developer Kit for Java
      • Build a Conversational Bot
      • Build an Interactive Bot
      • Build a Headless Bot
      • Integrate a Bot with an Identity Provider
    • Bot Developer Kit for Python
    • App Developer Kit
      • Build a Basic Extension App
      • Build an Extension App with App Views
        • Add Buttons and Handlers to an Extension App
        • Add BDK to an Extension App for Circle of Trust
      • Build an Extension App with Message Renderers
    • Postman
    • UI Style Guide
      • Colors
      • Form Elements
      • Buttons
  • Embedded Modules
    • Symphony Messaging URI
      • Symphony Messaging URI for Mobile (deprecated)
    • Desktop interoperability
      • FDC3 intents
        • Message format
      • Configuration guide
        • Configure Interop.io
        • Configure Here Core
        • Configure Finsemble
        • Configure with Embedded Mode
        • Troubleshooting
      • Change log
    • Embedded Mode
      • Get started
      • Configuration parameters
      • Open a chat
      • Send a message
      • Create a room
      • Pin a message
      • Notifications
      • Support for extension applications
      • Open an app
      • Embedded Mode with Sponsored Access
      • Pricing tiers
      • Logout
    • Universal Webhook
      • User guide
        • Example with Splunk
      • Installation guide
  • Symphony REST API
    • Messaging REST API
    • Federation
    • Sponsored Access API
    • Enhanced Directory API
  • Developer Certification
    • Developer Certification
  • Mobile Frameworks
    • Blackberry
    • MobileIron
  • Admin Guides
    • Change Logs
      • API Agent
        • Agent - 25.5
        • Agent - 25.3 (LTS)
        • Agent - 24.12 (LTS)
        • Agent - 24.9 (LTS)
        • Agent - 24.6 (LTS)
        • Archives
          • Agent - 24.11
          • Agent - 24.10
          • Agent - 23.9 (LTS)
          • Agent - 24.8
          • Agent - 24.3 (LTS)
          • Agent - 24.2
          • Agent - 24.1
          • Agent - 23.12 (LTS)
          • Agent - 23.11
          • Agent - 23.10
          • Agent - 23.7
          • Agent - 23.6 (LTS)
          • Agent - 23.4
          • Agent - 23.3 (LTS)
          • Agent - 23.1
          • Agent - 22.12 (LTS)
          • Agent - 22.11
          • Agent - 22.10
          • Agent - 22.9 (LTS)
          • Agent - 22.8
          • Agent - 22.7
          • Agent - 22.6 (LTS)
          • Agent - 20.14
          • Agent - 20.13
          • Agent - 20.12
          • Agent - 20.10
          • Agent - 20.9 (2.62)
          • Agent - 20.7 (2.61)
          • Agent - 20.6 (2.60)
          • Agent - 20.5 (2.59)
          • Agent - 20.4 (2.58)
      • SBE (Pod API)
        • SBE - 24.1
        • SBE - 20.16
        • SBE - 20.15
        • Archives
          • SBE - 20.14
          • SBE - 20.13
          • SBE - 20.12
          • SBE - 20.10
          • SBE - 20.9 (1.62)
          • SBE - 20.7 (1.61)
          • SBE - 20.6 (1.60)
          • SBE - 20.5 (1.59)
          • SBE - 20.4 (1.58)
      • Client 2.0 APIs
        • Client 2.0 - 25.05
        • Client 2.0 - 25.03
        • Client 2.0 - 24.12
        • Client 2.0 - 24.05
        • Client 2.0 - 23.02
        • Client 2.0 - 22.11
        • Archives
          • Client 2.0 - 20.4
          • Client 2.0 - 20.5
          • Client 2.0 - 20.6
          • Client 2.0 - 20.7
          • Client 2.0 - 20.9
          • Client 2.0 - 20.10
          • Client 2.0 - 20.12
          • Client 2.0 - 22.8
          • Client 2.0 - 22.10
      • Universal Webhook
        • Univ Webhook - 2.6
        • Univ Webhook - 2.4
        • Univ Webhook - 2.2
        • Univ Webhook - 2.1
        • Univ Webhook - 2.0
    • API Change Management
    • Global Throttling
    • Agent Guide
      • Network Topology
      • Agent Download
      • Agent Installation
      • Agent Configuration Fields
      • Agent Server High Availability
      • Agent Performance Tuning
Powered by GitBook
On this page
  • Overview of Certificate-Based Authentication
  • Summary
  • 1. Upload a Signing Certificate or Root Certificate
  • 2. Generate a Client Certificate
  • 3. Authenticate

Was this helpful?

Export as PDF
  1. Bots
  2. Authentication

Certificate Authentication Workflow

Last updated 2 months ago

Was this helpful?

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:

  • Session Auth:

  • Key Manager Auth:

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 Messaging 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 Messaging 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

  1. The Admin upload a Signing certificate or Root certificate using the Admin portal.

  2. The Admin provides to the developer a child client certificate derived from the Signing or Root certificate

  3. The developer authenticates the Bot using the client certificate.

Note: It is also possible to directly upload a Client certificate in the Admin portal instead of a Signing or Root certificate.

1. Upload a Signing Certificate or Root Certificate

Please note the below steps can only be performed by a Symphony Messaging Pod Administrator as they will have the necessary administrator privileges to access the Administration Portal.

The certificate should be concerted to a CER or PEM format before it is uploaded

Once you have obtained a copy of your Root Certificate Authorities (CA) Public "Signing Certificate", you can upload it using the following steps:

  1. Once logged in click the Manage Certificates button then select Import

  2. Drag and drop your Certificate file into the popup window:

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

2. Generate a Client Certificate

You can use the following commands to generate the service account certificate. The certificate must use 4096 bits length.

$ openssl genrsa -aes256 -passout pass:$PASSWORD -out admin-key.pem 4096
$ openssl req -new -key admin-key.pem -passin pass:$PASSWORD -subj "/CN=$USERNAME/O=Symphony Communications LLC/OU=NOT FOR PRODUCTION USE/C=US" -out admin-req.pem
$ openssl x509 -req -sha256 -days 2922 -in admin-req.pem -CA $CA_CERT -CAkey $CA_KEY -passin pass:$CA_PASSWORD -out admin-cert.pem -set_serial 0x1
$ openssl pkcs12 -export -out admin.p12 -aes256 -in admin-cert.pem -inkey admin-key.pem -passin pass:$PASSWORD -passout pass:$OUTPUT_PASSWORD
  • 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

Email

admin@bots.symphony.com

Locality

London

State / Province

London

Country

GB

Key Size

2048 bits

Creation of the service user in the Admin Portal

The Symphony Messaging Admin then creates a service user with a username that matches the Common Name of the certificate, as you can see in the example below:

3. Authenticate

$ curl --cert bot.user1.p12:mypassword
https://${symphony.url}/sessionauth/v1/authenticate
-X POST

A successful response:

{
  "name":"sessionToken",  
  "token":"SESSION_TOKEN"
}
$ curl --cert bot.user1.p12:mypassword
https://${symphony.url}/keyauth/v1/authenticate
-X POST

A successful response:

{
  "name":"keyManagerToken",
  "token":"KEY_MANAGER_TOKEN"
}

Pass the Session Token and Key Manager Token as headers for all subsequent API requests.

Navigate to the Symphony Admin Console for your Pod (e.g. ), then log in with your credentials

To authenticate on the Pod the bot must call the Session Auth endpoint: . Pass along the client certificate provided in the TLS session, returning a Session Token:

To authenticate on the Key Manager, the bot must call the Key Manager Auth endpoint: . Pass along the client certificate provided in the TLS session, returning a Key Manager Token:

https://developers.symphony.com/restapi/main/bot-authentication/session-authenticate
https://developers.symphony.com/restapi/main/bot-authentication/key-manager-authenticate
Configure your Bot for BDK 2.0 for Java
https://mypod.symphony.com/?admin
https://developers.symphony.com/restapi/main/bot-authentication/session-authenticate
https://developers.symphony.com/restapi/main/bot-authentication/key-manager-authenticate