Authentication Overview

Overview

IBM Video Streaming allows third-party clients to access IBM Video Streaming users' resources (data) via a HTTP-based (RESTful) API. It also provides a Broadcaster Library that is capable of broadcasting to a user's channel. Both the REST API and the Broadcaster Library uses the OAuth 2.0 protocol for authentication and authorization.

Basic workflow

The basic workflow of a third-party Client is the following:

1. Authorize the user: Obtain and validate the user's credentials (username and password). The client must never store these credentials, only pass it to the server for authorization.
2. Obtain an access token: If the user's credentials were entered correctly, the third-party client can obtain an access token. Once this token is received, it can be used to access the user's resources until the token expires or the user revokes it on the IBM Video Streaming website.
3. Access the user's resources: The client can use IBM Video Streaming's REST API or the IBM Video Streaming Broadcasting Library to access the user's resources (data) or to broadcast to the user's channel. The client authorizes itself using the access token, with methods described by the OAuth 2.0 Protocol Draft.

Authorization Flows

The OAuth 2.0 protocol provides several flows (workflows) for the first two phases. It depends on the type and architecture of the client which flow is the most suitable. The following flows are supported:

• Implicit flow: Suitable for standalone, native clients (desktop / mobile). The user enters its credentials to a secure login webpage. After logging in, the browser is redirected to a special URL (defined by the client), passing the access token in the URL.
• Authorization code flow: Suitable for third-party websites which contain a client and a server component. The user enters its credentials to a secure login webpage. After logging in, the browser is redirected to a special URL (defined by the client), passing an authorization code in the URL. The third-party server obtains the access token with another HTTP request in the background, using the authorization code. This method is more secure than the implicit flow if the third-party client has a client+server model. See the OAuth2 Draft for details.
• Client credentials flow: Best choice for users developing server-side applications to manage their content / settings. Read more

Endpoints

The webpages and HTTP services invoked in during this authorization process are called endpoints. IBM Video Streaming has the following endpoints:

• Authorization endpoint: this is the webpage where the user enters his/her credentials.
• Token endpoint: this is the HTTP service where the access token can be obtained in an authorization code flow (when using the implicit flow, the access token can be obtained directly from the authorization endpoint).

Access tokens

There are two types of access tokens: Bearer tokens and MAC tokens. They are equivalent in the sense that they can access the same resources on the IBM Video Streaming REST API. The difference is that while bearer tokens can be only used on encrypted channels (HTTPS), MAC tokens are suitable on non-encrypted channels as well.

If the client uses the IBM Video Streaming Broadcasting Library, it must use MAC tokens: the broadcasting is done on the RTMP protocol, which is unencrypted. If the client only uses the REST API, the bearer tokens are preferred because their usage is very simple and lightweight.

Bearer tokens and MAC tokens can be obtained in the same way: the authorization endpoint has a token type parameter, so the client can specify what kind of token it wants to create.

Token scopes, expiration

By default, access tokens have a limited lifetime (they expire in a day) and can access only a limited amount of resources. In the authorization process the client can request extra permissions (scopes) from the user to overcome these limitations. These requests are shown to the user on the authorization endpoint. IBM Video Streaming currently supports the following scope:

• Broadcaster scope: If this scope is enabled, the access token can be used for broadcasting with the IBM Video Streaming Broadcasting Library. This scope can only be used with MAC tokens.

OAuth2 authorization server endpoints

Authorization endpoint

The Authorization endpoint is a secure web page that contains a login form. The client should show this page to the user in an embedded browser. When the user completes the login process, the browser is redirected to a special URL. The client can capture this redirect call, and obtain the authorization code or access token (depending on the flow type).

The parameters below specify the behavior of the authorization endpoint. They have to be set in GET or POST HTTP parameters.

Supported OAuth 2.0 standard parameters

IBM Video Streaming specific extra parameters

Result

The result values below are appended to the redirect_uri as HTTP GET parameters. If the response_type parameter is "code", the following values are returned:

MAC tokens are currently not implemented for Authorization Code Flow.

If the response_type is "token" and token_type is "bearer" (or not set), the following values are returned:

If the response_type is "token" and token_type is "mac", the following values are returned:

Error handling

If the authentication was not successful, there is no HTTP redirection: the User can stay on the Authorization Endpoint page until the correct credentials are entered. It is also possible to sign up a new user, or to request a password reset if the password is forgotten.
If the User authenticates correctly, but presses "Deny" on the authorization page, the browser is redirected to the redirect_uri with the following parameters:

Token Endpoint

Authorization Code flow

When the Client receives the Authorization Code, the server-side component of the Client calls this Endpoint to return the Access Token. The parameters below must be set as HTTP POST parameters.

The Token Endpoint currently works for Bearer Tokens only.

In addition to the parameters above, the Client has to provide its Client secret (provided along with the Client key) to authenticate itself. The authentication is done with HTTP Basic authorization method. Example HTTP Header:

Authorization: Basic bc345abc45d6789abcdef0123aef0126789def01

Response

The response of the Token Endpoint is a JSON object. JSON response on success (for Bearer Tokens):

Resource Owner Password Credentials flow

The server-side component of the Client calls this Endpoint to return the Access Token using resource owner's credentials (username and password). The parameters below must be set as HTTP POST parameters.

In addition to the parameters above, the Client has to provide its Client secret (provided along with the Client key) to authenticate itself. The authentication is done with HTTP Basic authorization method. Example HTTP Header:

Authorization: Basic bc345abc45d6789abcdef0123aef0126789def01

Response

Client credentials flow

There are several API resources which aren't connected to any user. Those are resources implemented for the API client (application). Hook management is a good example for that. Those resources needs the clients to identify themselves. For that purpose we implemented the Client Credentials OAuth2 Flow which provides your app a client access token. With normal user level tokens these resources dedicated to clients are inaccessible, however a client token can access the application owner user's resources.
The parameters below must be set as HTTP POST parameters.

In addition to the parameters above, the Client has to provide its Client secret (provided along with the Client key) to authenticate itself. The authentication is done with HTTP Basic authorization method. Example HTTP Header:

Authorization: Basic bc345abc45d6789abcdef0123aef0126789def01

Response

Error responses for Authorization Code, Password, and Client Credentials token flows

If there is an error, the Token Endpoint returns a JSON object with the following format:

{
    "error": "ERROR_VALUE"
}

It also sends a HTTP status code indicating the error. Possible error responses:

Examples

Authorization Code Flow

1. The Client opens a browser with the Authorization Endpoint:

   https://authentication.video.ibm.com/authorize
   ?response_type=code
   &client_id=AAAAAAAAAABBBBBBBBBBCCCCCCCCCCDDDDDDDDDD
   &redirect_uri=http://example.com/get_access_token
   &device_name=My%20Device
   &scope=broadcaster
   &state=XYZ

2. The User enters his/her credentials and presses the Allow button. The browser is redirected to the following URL:

   http://example.com/get_access_token?code=19d8dbb3ebac55f110c3b526e38bcfdfbf46d659&state=XYZ

3. The page handler at http://example.com/get_access_token retrieves the Access Token using the Token Endpoint:

   POST /oauth2/token HTTP/1.1
       Host: video.ibm.com
       Authorization: Basic xxxxxxxxxxyyyyyyyyyywwwwwwwwwwzzzzzzzzzz
       Content-Type: application/x-www-form-urlencoded
       grant_type=authorization_code&client_id=AAAAAAAAAABBBBBBBBBBCCCCCCCCCCDDDDDDDDDD
       &code=19d8dbb3ebac55f110c3b526e38bcfdfbf46d659&redirect_uri=http://example.com/get_access_token
       

4. The response of Token Endpoint contains the Access Token:

   HTTP/1.1 200 OK
       Cache-Control: no-store
       Content-Type:application/json; charset=UTF-8
       {"access_token":"ab345cdef123ef1267890abcdef04567890abcd1", "token_type":"bearer", "expires_in":86400}
       

Implicit Flow, requesting for MAC tokens on a mobile-optimized authorization page

1. The Client opens a browser with the Authorization Endpoint:

   https://authentication.video.ibm.com/authorize
   ?response_type=token
   &token_type=mac
   &client_id=AAAAAAAAAABBBBBBBBBBCCCCCCCCCCDDDDDDDDDD
   &redirect_uri=http://example.com/token
   &device_name=My%20Device
   &scope=broadcaster
   &state=XYZ
   

2. 1. The User enters his/her credentials and presses the Allow button. The browser is redirected to the following URL:

      http://example.com/token
      ?access_token=1a446888dfaa921e189479409d638d680dfdbf77
      &token_type=mac
      &mac_key=dfc337d39b0941650b67051a622885cb0eb67a51
      &mac_algorithm=hmac-sha-1
      &created_at=1310000546
      &state=XYZ
      

   2. The user cancels the authorization page or presses Deny after authentication. The browser is redirected to the following URL:

      http://example.com/token?error=access_denied&state=XYZ

Testing API from command line (with curl)

Get an access token

https://authentication.video.ibm.com/authorize
?response_type=token
&client_id=057ce944b015ec9fdf546dfbbe1b7af4b19e8158
&redirect_uri=https://video.ibm.com/oauth2/redirect
&device_name=MyDevice
&state=XYZ

After logging in, the browser is redirected to a special URL (defined by the Client), passing the Access Token in the URL. As you can see in the examples below, you should use Authorization HTTP header with token in the requests: "Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950"

Creating a channel (POST)

curl \
    -i \
    -X POST \
    -H "Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950" \
    -d "title=Whatever+Test+1234" \
    https://api.video.ibm.com/users/self/channels.json

HTTP/1.1 201 CREATED
Server: nginx/1.2.6
Date: Tue, 15 Jan 2013 13:08:06 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 123
Connection: keep-alive
Vary: Host
X-Powered-By: PHP/5.3.20-1~dotdeb.0
Cache-Control: no-store
Accept-Ranges: bytes
X-Varnish: 703443498
Age: 0
Via: 1.1 varnish
{"channel":{"id":"13091307","title":"Whatever Test 1234","url":"whatever-test-1234","tiny_url":"http://ustre.am/SVE7"}}