Merge pull request #1097 from Bandwidth/GRAVITY-1030

GRAVITY-1030 Add documentation for the authentication of WebRTC In-AppCalling

site/docusaurus.config.js

@@ -241,4 +241,8 @@ module.exports = {
     ],
     "docusaurus-plugin-sass",
   ],
+  markdown: {
+    mermaid: true,
+  },
+  themes: ['@docusaurus/theme-mermaid'],
 };

site/global-guides/voice/authentication.mdx

@@ -0,0 +1,70 @@
+---
+id: inAppAuthGuide
+title: Authentication for Global In-App Calling
+slug: /voice/guides/inAppCalling/authentication
+description: Authentication In-App Calling (WebRTC)
+keywords:
+  - bandwidth
+  - voice
+hide_title: false
+image: '@site/static/img/bw-icon.svg'
+---
+## Retrieving an access token
+
+:::caution
+
+The token should be retrieved from a server running in a secure environment and securely provided to clients. Client-side javascript does not have a mechanism for hiding these credentials so **DO NOT** place these directly in your client-side code.
+
+Bandwidth accepts no responsibility for the loss of account credentials and any resulting network traffic, fraud, or undesired account access that results from failing to manage account access credentials in a completely secure manner.
+:::
+
+
+The process to retrieve an access token requires you to have your [WebRTC Credentials](./inAppGuide.mdx#generating-credentials-for-an-access-token) (ie. ClientID and ClientSecret), generated from the [Global Portal](https://login.voxbone.com/login). You will then be able to make a call to our token endpoint with these credentials.
+
+```mermaid
+sequenceDiagram
+    Application->>In-App Calling AuthServer: GET /api/v1/oauth2/token?scope=voice.webrtc <br> Headers: { Authorization: Basic PEJhc2ljIEF1dGggVXNlcm5hbWU+OjxCYXNpYyBBdXRoIFBhc3N3b3JkPg== }
+    In-App Calling AuthServer->>In-App Calling AuthServer: Validate credentials
+    In-App Calling AuthServer->>Application: 200 OK <br> {"access_token": "...", "access_token_id": "...", "token_type": "Bearer", "expires_in": 600}
+```
+### Request
+In order to retrieve the token, you will use Basic Authentication `ClientID:ClientSecret`. Below is a sample request:
+
+```sh
+curl --request POST \
+  --url https://id.voxbone.com/api/v1/oauth2/token \
+  --header 'Authorization: Basic PEJhc2ljIEF1dGggVXNlcm5hbWU+OjxCYXNpYyBBdXRoIFBhc3N3b3JkPg==' \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --data grant_type=client_credentials \
+  --data scope=voice.webrtc
+```
+Now that we've shown the request, let's break down the parts of the API call.
+
+- **url** `https://id.voxbone.com/api/v1/oauth2/token` - This is the In-App Calling AuthServers's `token_endpoint`.
+- **Headers**
+  - **Authorization** - Authentication is required. You **MUST** provide your `ClientID` and `ClientSecret` using a Base64-encoded header with the `Basic` authentication scheme. The header value before encoding should take the form `Basic <ClientID>:<ClientSecret>`.
+  - **Content-Type** - You **MUST** use `application/x-www-form-urlencoded`. This will URL encode (aka percent-encode) the parameters making them into `key=value` pairs which will be separated by an ampersand `&`.
+- **Body**
+  - `grant_type` Currently, we only support `client_credentials` OAuth2 `grant_type`.
+  - `scope` You **MUST** pass the value of `voice.webrtc` to have permissions for the WebRTC Gateway.
+
+### Response
+An example response is:
+```
+{
+	"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFsb2hvbW9yYSJ9.e30.kl3HYFQIcP4xZd78wUkdXxntxBu1d7b5ZCt99qVObC-gUZd5KSq2J7Q5rDb2LjP1_WVndcLQSqCoq3Anvp03hJWM6mamZL3dWHxjGLwkrIlzmNx9ZFGhTGIEsYLyaQqy8MonWYw2mJ4Z0APEfTVbTBHNIGrm_9GT6rIkdOwQFM-XgH1Tau4JbpFJun3n6o15WTgjzdEj9fIwd385CPwL-pAmOiozbYWUEzgqkXjSGHI11hiLDu-tv_8Ds06Cx4iCnL1F6_dFrnpD3CF0i6JJYVrvLmi6vgzoxp9YEIRBwaOZTSuYuYt03SQfbMZy8L2Z71sRKLLGt3TrxgtwyjefpQ",
+	"access_token_id": "a5xA3xMKEggGwvpSLtk2lRb",
+	"token_type": "Bearer",
+	"expires_in": 600
+}
+```
+
+Let's see what each item in the response object is meant for:
+- `access_token`: This is the JSON Web Token (JWT) that will be passed in the Authorization header of the requests to the In-App Calling API. **NOTE:** The example above does not contain a valid token and cannot be used to actually authenticate.
+- `access_token_id`: This will be the ID of the access token to prevent tokens from being re-used. It will be the same as the `jti` claim within the access token.
+- `token_type`: This is used to identify the type of token and also the prefix to be used in the Authorization header.
+- `expires_in`: This is the length of time, in seconds, before a token expires. In the example above the value is `600`. This means the token will be valid for 600 seconds (10 minutes) before it expires. You should use the token until 10-30 seconds before expiration, at which point you **MUST** request a new token in the same manner as described above.
+
+### Using the Access Token
+
+Once you have obtained the token you can perform authenticated requests to the WebRTC Gateway using the [Bandwidth WebRTC SDK](./inAppGuide.mdx#sdks).

site/global-guides/voice/inAppGuide.mdx

@@ -91,17 +91,13 @@ The following steps can be followed to generate your credentials:
 
 ![Generating WebRTC Credentials](@site/static/img/docs-diagrams/voice/in-app-credentials.png)
 
-Once you have generated your credentials you can call our identity services endpoint. Please refer to here for more information.
+Once you have generated your credentials you can retrieve an access token from our token API.
 
 :::note
-The scope must be **voice.webrtc** to generate an access token to use for in-app calling.
+The token **MUST** contain the scope **voice.webrtc** to use for in-app calling.
 :::
 
-As the token will be visible within your application we strongly advise to only use this scope. The token should be fetched from a server running in a secure environment, and provided to clients in a secure manner.
-
-We recommend regenerating the token every 30 seconds before expiry. It is not advisable to regenerate the token for every in-app voice call as this will create an unnecessary delay in the call being connected.
-
-Bandwidth accepts no responsibility for the loss of account credentials and any resulting network traffic, fraud, or undesired account access that results from failing to manage account access credentials in a completely secure manner. Minting of tokens is not included as a client SDK capability for the above reason.
+Please refer to the documentation on [how to retrieve an access token](./authentication.mdx) for more information.
 
 ## Resources
 
@@ -257,4 +253,4 @@ Once a call has been established, this method could be used to mute the audio.
 
 #### activeCall.isLocalHold() 
 
-Returns a boolean value indicating whether the call is currently held as the result of an activeCall.hold(true) action.
+Returns a boolean value indicating whether the call is currently held as the result of an activeCall.hold(true) action.

site/package.json

@@ -20,6 +20,7 @@
     "@docusaurus/core": "^2.4.1",
     "@docusaurus/plugin-google-gtag": "^2.4.1",
     "@docusaurus/preset-classic": "^2.4.1",
+    "@docusaurus/theme-mermaid": "^2.4.1",
     "@types/react": "^17.0.0",
     "bandwidth-redoc": "^1.4.0",
     "buffer": "^6.0.3",

site/sidebarsGlobalGuides.js

@@ -10,6 +10,7 @@ module.exports = {
       label: "Voice",
       items: [
         "voice/inAppGuide",
+        "voice/inAppAuthGuide"
       ]
     }
   ]