How do I use co-host token authentication?

Co-host authentication enables you to authenticate whether a user has the privilege to publish streams in a live streaming channel. This feature helps ensure that only authorized users publish streams and prevents illegal users from exploiting business vulnerabilities or stealing tokens to bomb a live broadcast room.

You deploy a token server and generate tokens with the required privileges; the Agora server verifies the tokens you generate.

Note

• Using co-host authentication requires app logic changes. Ensure that you read this article before enabling this function.

• Co-host authentication applies to scenarios where the channel profile is set to Live Broadcasting.

Before proceeding, ensure that your app meets the following requirements:

• Uses the Agora Video SDK v2.1.0 or later.
• Uses only token-based authentication on all app clients to authenticate users. For details, see Upgrade authentication mechanism.

This section shows you how to set the role parameter when generating a token using AccessToken2. The following code uses C++ as an example but the principles and steps remain the same if you use another programming language to build your token server.

_43

#include <cstdlib>

_43

#include <iostream>

_43

_43

#include "../src/RtcTokenBuilder2.h"

_43

_43

using namespace agora::tools;

_43

_43

int main(int argc, char const *argv[]) {

_43

(void)argc;

_43

(void)argv;

_43

_43

// Get the value of the environment variable AGORA_APP_ID. Make sure you set this variable to your App ID obtained from Agora Console

_43

const char *env_app_id = getenv("AGORA_APP_ID");

_43

std::string app_id = env_app_id ? env_app_id : "";

_43

// Get the value of the environment variable AGORA_APP_CERTIFICATE. Make sure you set this variable to your App Certificate obtained from Agora Console

_43

const char *env_app_certificate = getenv("AGORA_APP_CERTIFICATE");

_43

std::string app_certificate = env_app_certificate ? env_app_certificate : "";

_43

// Replace channelName with the channel name you want to join

_43

std::string channel_name = "channelName";

_43

// Fill in your actual user ID

_43

uint32_t uid = 2882341273;

_43

// Token expiration time in seconds

_43

uint32_t token_expiration_in_seconds = 3600;

_43

// Privilege expiration time for all permissions in seconds

_43

uint32_t privilege_expiration_in_seconds = 3600;

_43

std::string result;

_43

_43

std::cout << "App Id:" << app_id << std::endl;

_43

std::cout << "App Certificate:" << app_certificate << std::endl;

_43

if (app_id == "" || app_certificate == "") {

_43

std::cout << "Need to set environment variable AGORA_APP_ID and "

_43

"AGORA_APP_CERTIFICATE"

_43

<< std::endl;

_43

return -1;

_43

}

_43

// Generate Token

_43

result = RtcTokenBuilder2::BuildTokenWithUid(

_43

app_id, app_certificate, channel_name, uid, UserRole::kRolePublisher,

_43

token_expiration_in_seconds, privilege_expiration_in_seconds);

_43

std::cout << "Token With Int Uid:" << result << std::endl;

_43

_43

return 0;

_43

}

Parameter	Description
role	The publishing privilege of the user: kRolePublisher (1): (Default) The user has the the privilege to publish streams. kRoleSubscriber (2): The user does not have the privilege to publish streams.

Refer to the following steps to authenticate whether a user has the publishing privilege in scenarios where an audience member wants to become a host:

1. Before joining a channel, the app client applies for a token with the privilege of a subscriber. The app server generates a token and passes it to the app client.
2. The app client calls joinChannel and passes the token generated with kRoleSubscriber privilege to the SDK.
3. Before changing the user role from audience to host, the app client applies for a token with the privilege of kRolePublisher. The app server generates a second token, and passes it to the app client.
4. The app client calls renewToken and passes the new token to the SDK.
5. The app client calls setClientRole to change the user role from an audience member to a host. The Agora server authenticates the token when the app client calls setClientRole. If the token is generated with the privilege of kRolePublisher, the app client can publish streams.

Note

• If the user wants to switch from a host to an audience member, repeat steps 3 to 5. Apply for a token with the privilege of kRoleSubscriber, call renewToken on the app client, and then call setClientRole.

• When the token expires, you generate a new token on the app server and call renewToken to pass the fresh token to the SDK. The new token also has a service validity period.

Refer to the following steps to enable co-host authentication in Agora Console:

1. Log in to Agora Console. Under Projects, choose a project for which you want to enable co-host authentication, click the Edit icon, and enter the Edit Project page.
2. In the All Features area, click Co-Host authentication.
3. Follow the on-screen instructions to know more about this function, and click Enable Co-host authentication. Co-host authentication takes effect in 5 minutes.

1. Suppose a user takes the role of broadcaster. After I enable co-host authentication, will the user be able to publish streams?

   Answer: Yes. After the token expires, you need to generate a new token with the privilege of kRolePublisher, and call renewToken to pass the new token to the SDK.

2. Suppose a user takes the role of audience. After I enable co-host authentication, what should I do if this user wants to switch to broadcaster and publish streams?

   Answer: Once co-host authentication is enabled, a user needs to meet both of the following requirements to publish streams:

   • The user role in setClientRole is set as Broadcaster.
   • The user joins the channel with a token generated by setting the role parameter in the buildToken method to kRolePublisher.

   To summarize, for an audience member to become a host and publish streams, you need to follow steps in Modify the app logic, generate a token with the privilege of a publisher, call renewToken to pass the new token to the SDK, and then call setClientRole to change the user role to broadcaster.