Enhanced Conference Access Control

Overview

Dolby.io Communications APIs support the use of conference access tokens, which are used to grant access to protected conferences, and therefore provide additional protection for clients connecting to a conference. Dolby.io Communications APIs allow clients to specify a set of permissions in the conference access token, and the generated token is only allowed to access resources matching the permissions. By limiting the operations that the clients can perform, you can create a protected conference and prevent any unwanted actions that can compromise the conference experience. The conference access token expiration is determined by the maximum duration of the conference and the conference access token can be revoked by updating the permissions.

To support the use of conference access tokens, enhancements have been made to the following Dolby.io Communications API components:

Dolby.io dashboard settings

You can enable the conference access token to improve security through configuration on the Dolby.io dashboard settings page. An application must be enabled with this feature in order to protect conferences. When the "Enhanced Conference Access Control" setting is enabled, you must provide the conference access token in order to connect to a conference. By default, this setting is disabled for backward compatibility purposes.

Conference REST API endpoint

The Conference API includes additional endpoints to manage protected conferences with the use of the conference access token. Applications can now create and terminate conferences, invite users, kick users from a conference, and manage a user's access permissions.

Client SDK

When joining a conference the client must supply a conference access token, which the application server has acquired on behalf of the client through the use of the Conference APIs. The following are updates to the client SDK to support the use of conference access tokens:

  • The Invite method extension allows configuration of conference permissions for new participants. For more information, see the Inviting Participants article.
  • The isExpired parameter is used for access token refresh callback and informs the client if the access token is already expired.
  • The client SDK supports the ability to kick a participant from a conference.
  • The client SDK supports the ability to set and update participant permissions.
  • New permissionsUpdated event for conference permission changes.
  • The client SDK raises a InsufficientPermissionsError exception when the provided conference access token does not have the required permissions for the operations the client is trying to invoke.

Client access token

The client access token is still currently used for session authentication. There are instances where a client does not need to connect to a conference, such as waiting for an invitation, where the client must be authenticated and identified. The client access token and conference access token are both required for accessing a conference with the Enhanced Conference Access Control setting enabled. Whereas the conference access token expiration is determined by the maximum duration of the conference, the client access token expiration is specified by the customer when the token is requested.

For more information on authentication, see the Authentication API.

Conference access token lifecycle

When a protected conference is created, the client SDK receives the conference access token to use for every conference related operation. The conference access token lifecycle is as follows:

  • A protected conference is created and users are invited. The conference access token is issued; the conference access token is associated with the participant's external ID.
  • A participant with adequate permissions can invite new users and grant access to an existing conference.
  • Based on the permissions defined in the conference access token, participants can perform a specific set of actions within the conference.
  • During a conference, a participant with adequate permissions can update another participant's permissions by providing the participant a new conference access token.
  • During a conference, a participant with adequate permissions can kick another participant from the conference. This action revokes the conference access token, so the kicked participant cannot join the conference again.

Common conference workflows

The following are common conference workflows for a conference with Enhanced Conference Access Control enabled:

Client SDK workflows

1. An application user uses the create method, which triggers the application server to create a conference and return the owner's token.

2. The application user invites participants to a conference. If participants have open sessions, they receive the token in their invitations and join the conference. If participants do not have open sessions, they do not receive the conference invitation.

REST APIs workflows

1. An application user uses the create REST API and provides in the API a list of the invited participants. This action triggers the application server to create a conference and return the owner's token and participants’ tokens.

2. The application user invites participants to a conference using one of the following options:

  • The application user can provide the conference access token to other application users who should join the conference. A client's application can pass the participants' tokens to invitees and include the token in the conferenceAccessToken property in JoinOptions or ListenOptions. The invitees can use the join method to join the conference.

  • The inviter can also use the notification option included in the create REST API by setting the notification parameter to true. This action notifies other users about the invitation and provides them the conference access token. If participants have open sessions, they receive the token in their invitations and join the conference. If participants do not have open sessions, they do not receive the conference invitation.

  • The inviter can also use the invite REST API to invite participants to the created conference. The API response includes conference access tokens for participants. A client's application can pass the participants' tokens to invitees and include the token in the conferenceAccessToken property in JoinOptions or ListenOptions. The invitees can use the join method to join the conference.