Authenticating with the Client SDK
RingCentral Video REST API and Client SDKs are in beta
The RingCentral Video REST API and Client SDKs are currently in beta. Developers should be aware of the following:
- Their feature sets are not reflective of the full scope currently planned.
- Backwards compatibility is not guaranteed from one release to the next during the beta period. Changes can be introduced at any time that may impact your applications with little notice.
What is a Client ID and Client Secret used for?
Each app you build must first be registered in the RingCentral Developer Console. Upon doing so, you will receive a Client ID and Client Secret that together uniquely identify your application on our platform. You only need to create one app in our console regardless of how many companies or meeting participants that app will be supporting.
What authentication methods are supported by the Video Client SDK?
Each instance of the Client SDK must establish a session on behalf of each participant or host that will be joining a meeting. These sessions are created by authenticating them via the SDK. We support a number of different modes of authentication. Each is discussed below.
RingCentral auth code
Using a RingCentral auth code, obtained through an OAuth flow, offers end users with the best and easiest-to-use authentication option. For this reason, we recommend this method be used in production. If you are familiar with OAuth grant types and flows, the process is relatively straight-forward.
Start the process by initiating the RingCentral auth code grant type flow. When the user is redirected back to your application after logging in, you will receive an auth code from RingCentral. Provide this auth code to the Client SDK and it will complete the auth process for you.
Guest authentication
Using an auth code to authenticate a user presumes the user has a RingCentral account. However, many video client applications are made available to a much large audience of people who do not have a RingCentral account. Consider for example a doctor's office. The doctor may very well be a RingCentral customer and can authenticate accordingly. However, the doctor's patients would not typically be a RingCentral customer, so they would need a way to authenticate in order to join a meeting. We call this auth mode "guest auth."
Guest auth is accomplished by providing no credentials (apart from the app's Client ID and Client Secret), and by providing a name for the user so that other participants can see the name of the person speaking.
Guest authentication is disabled by default
Be advised that this method is disabled by default. If you require guest authentication, please contact RingCentral support to enable this feature of your account.
import React, { useEffect, useState } from 'react';
export default function App({ config }) {
useEffect(() => {
const initRingCentralSdk = () => {
const { clientId, clientSecret } = config
const RingCentralSdk = (window as any).RingCentral.SDK;
return new RingCentralSdk({
server: RingCentralSdk.server.production,
clientId,
clientSecret,
});
}
const login = async (rcsdk) => {
const { jwt } = config
await rcsdk
.login({ 'jwt': jwt })
.then((response) => {
return response.json()
})
.catch((e) => {
const msg = `Login fails: ${e.message}.`
alert(msg)
});
}
const initSDK = async () => {
const rcsdk = initRingCentralSdk();
await login(rcsdk);
}
initSDK()
}, [])
}
JWT credential
A JWT credential can be input into the SDK to authenticate a user. JWT credentials are currently obtained through the RingCentral Developer Console and are associated with an individual user. JWT credentials are an ideal way to authenticate to the RingCentral REST API for scheduling meetings, but they do not necessarily offer the best user experience in client applications because the current process of obtaining a JWT through the Developer Console may intimidate a casual end-user. That being said, many developers consider them ideal to use during development because they are quick and easy for developers to generate, and it avoids having to implement a more complex authentication flow just to get started.
The following code sample shows how JWT authentication is accomplished across our three SDKs.
import React, { useEffect, useState } from 'react';
export default function App({ config }) {
useEffect(() => {
const initRingCentralSdk = () => {
const { clientId, clientSecret } = config
const RingCentralSdk = (window as any).RingCentral.SDK;
return new RingCentralSdk({
server: RingCentralSdk.server.production,
clientId,
clientSecret,
});
}
const login = async (rcsdk) => {
const { jwt } = config
await rcsdk
.login({ 'jwt': jwt })
.then((response) => {
return response.json()
})
.catch((e) => {
const msg = `Login fails: ${e.message}.`
alert(msg)
});
}
const initSDK = async () => {
const rcsdk = initRingCentralSdk();
await login(rcsdk);
}
initSDK()
}, [])
}
// Place your personal JWT or username and password
let options = RcvOauthOptions.create()
options?.setGrantType(RcvGrantType.jwt)
options?.setJwt(PersonalJwt)
RcvEngine.instance().authorize(options)
// Replace your token pair string here for testing
let TokenJsonStr = #"""
{
"access_token": "{access token}",
"token_type": "bearer",
"expires_in": 3600,
"refresh_token": "{refresh token}",
"refresh_token_expires_in": 604800,
"scope": "Meetings",
"owner_id": "{owner id}",
"endpoint_id": "{endpoint id}"
}
"""#
package com.ringcentral.video.quickstart
import android.app.Application
import com.ringcentral.video.GrantType
import com.ringcentral.video.OauthOptions
import com.ringcentral.video.RcvEngine
class SampleApplication: Application() {
override fun onCreate() {
super.onCreate()
/*
* Creating the RCV engine instance with the client ID and client secret, the client ID and
* client secret must be provided when integrating with the RingCentral video client SDK,
* otherwise, the video service will not work properly.
*/
RcvEngine.create(this.applicationContext,
getString(R.string.clientId),
getString(R.string.clientSecret)
)
/*
* There are two options to do the authentication.
* (1) Using the JWT OAuth flow,
* (2) Passing the access key acquired separately directly to the SDK
*/
val oauthOptions = OauthOptions.create()
// (1) Using the JWT flow
oauthOptions.grantType = GrantType.JWT
oauthOptions.jwt = getString(R.string.personalJwt)
RcvEngine.instance().authorize(oauthOptions)
// (2) You already have the auth token pair, pass it to the SDK as below.
// RcvEngine.instance().setAuthToken(getString(R.string.ringcentral_video_auth_token), true)
}
}
Can I provide my own authentication layer?
The default assumption of the RingCentral Video Client SDK is that all the meeting participants joining a meeting via the SDK are RingCentral customers who possess RingCentral login credentials. What if, on the other hand, you want to build an app intended to be used primarily by non-RingCentral users? In this modality, applications should authenticate meeting participants independently, and employ the guest auth mode to pass into the SDK the user's name from the authentication provider.