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.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
  • OBO App Permissions
  • Getting Started
  • Application Manifest Bundle File Sample:
  • Implementing OBO Authentication
  • Perform the Intended OBO workflow

Was this helpful?

Export as PDF
  1. Extension Apps
  2. App Authentication

OBO Authentication

Last updated 3 months ago

Was this helpful?

OBO or On-Behalf-Of authentication allows an authenticated extension app to perform the following operations on behalf of a given user:

  • List the streams of a given user

  • Initiate connection requests to and determine connection status with other users

  • Get the presence state of other connected users

  • Initiate IMs with other users

  • Send messages and attachments

  • Set the context user's own presence

For a full list of OBO-Enabled endpoints, click .

OBO use cases differ from bot use cases in that activities are performed as if end users had initiated actions directly from within Symphony themselves.

For OBO apps, authentication is a two-fold process:

  1. The app itself must be authenticated using its RSA public Key. The app authenticates only if it is enabled for the pod and its key is trusted. Upon successful OBO app authentication, the app receives an app sessionToken.

  2. The app must request to authenticate on behalf of a particular user, using its app sessionToken. The app authenticates only if it is installed for the user and its app sessionToken is valid. Upon successful OBO user authentication, the app receives the user's sessionToken.

Once the app has obtained the user's sessionToken, it can make REST API calls with this sessionToken to perform activities on behalf of the session user.

OBO App Permissions

Before proceeding, check out the OBO App permissions required for a given workflow:

Category

Permission

Description

On Behalf Of

ACT_AS_USER

Required. This required permission allows an application to act on behalf of a user via any of the other permissions. Note: This permission does not display to administrators on the Admin Portal because all apps can act on behalf of a user and therefore have the ACT_AS_USER permission by default.

Messaging

SEND_MESSAGES

The application can send messages for the logged-in user.

Messaging

SUPPRESS_MESSAGES

The application can suppress messages for the logged-in user.

Get Connections

GET_USER_CONNECTIONS

The application can get connection requests for the logged-in user.

Send Connections

REQUEST_USER_CONNECTIONS

The application can send connection requests for the logged-in user.

Get Presence

GET_PRESENCE

The application can only get presence for the logged-in user.

Set Presence

SET_PRESENCE

The application can only set presence for the logged-in user.

Primary User Identity

GET_BASIC_USER_INFO

The application can get information about the logged-in user.

Primary Contacts Access

GET_BASIC_CONTACT_INFO

The application can get information about other users through user look-up and search.

List User's Streams

LIST_USER_STREAMS

The application can list the streams in which the logged-in user is a member.

Getting Started

  1. In order to perform an OBO operation, you need to first create an extension application manifest bundle.json file and upload to the Pod.

Application Manifest Bundle File Sample:

{
  "applications": [
    {
      "type": "sandbox",
      "id": "hello",
      "name": "Hello World",
      "blurb": "This is a hello world app with a few example extension API invocations!",
      "publisher": "Symphony",
      "url": "https://localhost:4000/controller.html",
      "domain": "localhost",
      "icon": "https://localhost:4000/icon.png"
    }
  ]
}

Parameter

Type

Required

Description

type

String

Required

This field should be set to sandbox, which indicates that this is a standalone app, embedded within Symphony's client.

id

String

Required

The unique identifier for your app. Note: Do not use a colon (:) in this field, or you will receive a 401 Unauthorized error.

name

String

Required

The name of your app, which will be displayed in the Symphony Market.

blurb

String

Optional

Applied for Developer Mode. Field for display in the Symphony Market and Admin Portal.

publisher

String

Optional

The publisher of your app, which will be displayed in the Symphony Market.

url

String

Optional

URL which the pod will call to send pod information to the application

domain

String

Required

The domain for your app, which should match the controller file URL.

icon

String

Optional

An icon for your app (32x32 px), which will be displayed in the Symphony Market.

  1. Upload the manifest bundle.json to the Admin Portal -> App Management -> Add Custom App -> Import Application Bundle File

  2. Add your App Backend's (Bot) RSA public key in the Authentication section under App Management.

  3. Give your Application the following Permissions:

  4. ACT_AS_USER

Note: Give your extension application the appropriate permissions corresponding to your OBO workflow. For example, if you Bot will perform an OBO workflow to list a user's streams, grant your application with the LIST_USER_STREAMS permission.

  1. Once your App is created, make sure that it is enabled:

  2. Admin Portal -> App Settings -> Locate your App and toggle its 'Global Status' to be 'Enabled'

  3. Toggle 'Visibility' to be 'Visible'

  4. Toggle 'Installation' to be 'Manual'

  5. The last step is to make sure that the application is installed for the appropriate users. If the installation is set to 'Manual', make sure end-users install the extension application manually via the Symphony Marketplace. If not, make sure Symphony Admin installs this application on behalf of a given list of users.

Implementing OBO Authentication

The BDK makes it super simple to create an OBO based workflow, To do so, simply, simply instantiate an OBO Session in your Bot project. The BDK allows you to instantiate your OBO session from a username or user ID.

public class BotApplication {

  /** The Logger */
  private static final Logger log = LoggerFactory.getLogger(BotApplication.class);

    public static void main(String[] args) throws BdkConfigException, AuthInitializationException, AuthUnauthorizedException, Exception {

        // Initialize BDK entry point
        final SymphonyBdk bdk = new SymphonyBdk(loadFromClasspath("/config.yaml"));

        final AuthSession oboSessionUsername = bdk.obo("user.name");
        final AuthSession oboSessionUserId = bdk.obo(123456789L);

        // finally, start the datafeed read loop
        bdk.datafeed().start();
  }
}

Perform the Intended OBO workflow

In the following code snippet, the Bot authenticates on behalf of a given user and then prints a list of Streams (Type = ROOM) that the user in context is apart of:

public class BotApplication {

    private static final Logger log = LoggerFactory.getLogger(BotApplication.class);

    public static void main(String[] args) throws BdkConfigException, AuthInitializationException, AuthUnauthorizedException, Exception {

        // Initialize BDK entry point
        final SymphonyBdk bdk = new SymphonyBdk(loadFromClasspath("/config.yaml"));

        final AuthSession oboSessionUsername = bdk.obo("user.name");

        // list streams OBO user "user.name"
        List<StreamAttributes> x = bdk.streams().listStreams(oboSessionUsername, new StreamFilter());
        System.out.println(x);
        List<StreamAttributes> y = x.stream()
                .filter(item -> item.getStreamType().getType().toString().equals("ROOM"))
                .collect(Collectors.toList());
        System.out.println(y);

        // finally, start the datafeed read loop
        bdk.datafeed().start();
  }
}

here