Getting started
Introduction
Viewer Authentication API lets you implement a custom authentication process. This prevents live and recorded videos on your account from being accessed until the viewer authenticates. The authentication process is based on JSON Web Token (JWT) standards (JWE and JWS).
Flow
To implement viewer authentication flow you need to create an application that includes the following:
- Screens your viewers need to go through to authenticate
- Backend code that validates these authentication requests
- The process to redirect back to / or embed IBM Video Streaming components (player, QnA, Chat) with authentication token
Embed with Token
If you have protected pages where you want to use our embedded components, you can pass the authentication token directly to the embed URL in the vt query parameter.
Redirect Flow
If you embed the player to an unprotected page or use IBM’s channel page, the player will redirect the viewer to your authentication endpoint. You need to redirect back to the ref URL (passed in query parameter) with authentication token in the vt query parameter.
Viewer Authentication Settings
You can enable viewer authentication via API.
Generate an RSA key pair with 2048 bits key size
Set the public key and authentication URL to the content (channel or video) via API. See more
- and store the private key in your system secure way
We recommend using different key pairs for every content.
By default, every video inherits these settings from the channel but if you want to use different authentication for a video you can set it. See more
Example to key generation:
ssh-keygen -t rsa -b 2048 -E SHA512 -m PEM -P "" -f content_1234567.keyopenssl rsa -in content_1234567.key -pubout -outform PEM -out content_1234567.key.pub
Viewer Authentication Token
Viewer Authentication Token token is an encrypted JWT (JWE) that contains a signed JWT (JWS) with the following mandatory claims:
- sub: Subject, the token subject (identifier of the viewer, we recommend e-mail address)
- iat: Issued at, Unix timestamp in seconds when the token was generated. We will accept the token in the next 60 seconds from this timestamp. (We don’t accept tokens with future issued at timestamps)
The JWS is signed with your private key that you set to the content. The JWE is encrypted with Video Streaming’s public key that you can get from the API. See more
Viewer Authentication Token Lifecycle
- You can use the same token for the different components (Player, Chat, QnA)
- You can use every token once for a component: when the component embeds reloaded (eg: viewer reload the page) you need to generate a new token.
- The token lifetime is 60 seconds after issued
Token generation method
