Peer-to-Peer Communication API

Peer-to-Peer Communication API offers you STUN Service and TURN Service to expand your WebRTC app’s possibilities. And we also offer management tools that can be used directly by developers and administrators of your WebRTC application.

Services
Quick Start
Management Tools
Samples
Specifications

Services

Peer-to-Peer Communication API has two services:

STUN Service

STUN Service supports basic STUN functionality.
STUN Service does NOT authenticate your app’s end users.

TURN Service

TURN Service supports basic TURN functionality, offering UDP and TCP for protocols between TURN client and TURN server, and UDP for relaying protocol.
TURN Service also supports long-term credential mechanism to authenticate your app’s end users.
- The value obtained when authenticating and authorizing end user by Authorization Code Grant is used as authentication information of TURN.
- Authorization Code Grant requests must be made from the server. It is to hide the authentication information of your application which is required for authentication. See Authorization Code Grant for more details.

Quick Start

This section is designed to show you how to get started with STUN Service and TURN Service. Note that you need a RICOH Account for Step 1. To create one, see Get Started for detailed instructions. Please also refer to Video Chat Sample in Samples. Using Video Chat Sample, you can try video chat via TURN server.

Note: You can skip Step 1 and Step 2 if you want to use only STUN Service.

Step 1: Create an API Client

Create an API client for Peer-to-Peer Communication API at Management Console. You need to register the redirect_uri to be used for Authorization Code Grant. See Get Started for detailed instructions. After you successfully finish the procedure, you can check your Client ID and Client Secret at Dashboard.

Note: You can skip this step if you want to use only STUN Service or if you already have an API client for Peer-to-Peer Communication API.

Step 2: Obtain TURN Credentials

Obtain TURN credentials by using your server application to authenticate your end user’s TURN requests. TURN credentials is the end user Identifier (sub) and access token obtained as a result of Authorization Code Grant.

Note: You can skip this step if you want to use only STUN Service.

Implement Authorization Code Grant in Your Server Application

By referring to Authorization Code Grant, you will implement end user authentication in your server application. When you incorporate Authorization Code Grant into your implementation, end user will be able to log in to your app with a RICOH Account. You use Client ID and Client Secret obtained in Step 1. At the end of the Authorization Code Grant procedure, you obtain a response with access token (access_token) and ID token(id_token) like the following example:

{
  "id_token": "eyJ0eXAiOiJKV1Q.iLCJhbGci.OiJSUzI1Ni",
  "access_token": "eyJ0eXAiOiJK.8sDrK37ELI.YAAOBSg",
  "token_type": "Bearer",
  "expired_at": 1479364030
}

You should validate the ID token as described in Authorization Code Grant.

Note: We strongly recommend that server applications support TLS to ensure secure communication between server applications and browsers.

Extract End User Identifier

Decode the ID token to extract end user’s identifier. The ID token is represented as a JSON Web Token (JWT). The identifier is stored as the sub field of the ID token payload. To manage end users or to utilize Management Tools, you should store the end user identifier in your application.

Send TURN Credentials to Your WebRTC Application

Please safely pass the identifier to the WebRTC application. If the server application is compliant with TLS, it can be safely passed as a response to HTTPS request. After Authorization Code Grant’s token request, the server application returns a response to the browser to redirect it to the WebRTC application. To pass it at that redirect, set the access token and end user identifier to the query parameter of the redirect URL. In this way, the WebRTC application can obtain TURN credentials from query parameters.

Step 3: Try Peer-to-Peer Communication API

Set values on your app’s RTCPeerConnection configuration and try your app to check if it uses Peer-to-Peer Communication API.

Configuration Values

Configure your app’s RTCPeerConnection configuration with the values below in accordance with the service you wish to use. You can use STUN Service and TURN Service at the same time if you set all the values.

Property	Value	STUN	TURN
STUN URI	`'stun:stun.api.ricoh:3478'`	✓
TURN URI	`'turn:turn.api.ricoh:3478?transport=udp'`		✓
username	`sub` in `ID Token`		✓
credential	`Access Token`		✓

Configuration Example

The following example demonstrates how to set your app’s RTCPeerConnection configuration to use both STUN Service and TURN Service:

const configuration = {
  iceServers: [{
    urls: "stun:stun.api.ricoh:3478"
  },{
    urls: "turn:turn.api.ricoh:3478?transport=udp",
    username: "<sub in ID Token>",
    credential: "<Access Token>"
  }]
};
const pc = new RTCPeerConnection(configuration);

Note: The example above does NOT force your app to relay TURN because apps try to choose a better ICE candidate and relay candidates are usually the last choices. If you wish to force your app to relay any TURNs, you need to configure your NAT or other configuration values.

Checking ICE Candidates

Visit chrome://webrtc-internals on Chrome or about:webrtc on Firefox and check ICE candidates to see if your app uses Peer-to-Peer Communication API.

Management Tools

There are the functions for application developers and administrators. You can get records such as end users using TURN in your app. In order to use functions for application developers and administrators, it is necessary to perform client authentication by Client Credentials Grant. You need to use the same client ID and client secret as used for end user authentication. For details on client authentication see Client Credentials Grant. In the functions for application developers and administrators, end user is expressed as sub (it is the same value as end user identifier obtained from ID token shown in Step 2 of Quick Start). Therefore, in order to make full use of the functions for application developers and administrators, we recommend using sub to store and manage information related to your end users.

Check Usage

Using the REST API, you can get records that end users used TURN in your app. STUN usage records are not provided. By specifying the client ID and duration, you can get all usage records that your end user did during that period. Regardless of the start and end time, if the end user is using that period, it will be included in the result. Usage records can obtain usage start and end times, sub etc. Below is a request and response example.

GET /v1/sessions?from=2017-05-30T13%3A02%3A05Z&to=2017-06-30T13%3A02%3A05Z HTTP/1.1
Authorization: Bearer <Access Token>
Host: api-turn.api.ricoh

HTTP/1.1 200 OK
Content-Type: application/json

{
  "from": "2017-05-30T13:02:05Z",
  "to":"2017-06-30T13:02:05Z",
  "sessions":[
    {
      "session_id":"6005c7de-939a-11e7-bb1c-0a481fa19f66_000000000000000001",
      "started_at":"2017-09-20T05:55:54Z",
      "closed_at":"2017-09-20T06:32:04Z",
      "duration":37,
      "sub":"user01",
      "user_plan":"turn_free"
    },
    {
      "session_id": "2246e734-939a-11e7-bcd8-06f44c5bd1f2_000000000000000002",
      "started_at":"2017-09-20T05:55:54Z",
      "closed_at":"2017-09-20T06:32:05Z",
      "duration": 37,
      "sub":"user02",
      "user_plan":"turn_free"
    }
  ],
  "total":4,
  "nextPage":"https://api-turn.api.ricoh/v1/sessions?page=2&pageSize=2&from=2016-09-01T00%3A00%3A00Z&to=2017-09-30T23%3A59%3A59Z"
}

Please refer to the API Reference for a detailed explanation of each parameter and the value obtained by the response.

Samples

Video Chat Sample

Specifications

Conforms to RFCs 5766 over UDP, TCP.

Docs / RICOH Cloud API