Skip to main contentIBM Video Streaming Developers

Native app support

Overview

Native and mobile apps cannot store secrets in a secure way. Consequently, it’s not recommended to use the standard authorization code flow, since it requires a client secret when exchanging the authorization code for an access token on the token endpoint. By selecting the “Native application” option on the IBM Video Streaming dashboard, PKCE (https://tools.ietf.org/html/rfc7636) protocol can be forced to secure the authorization flow. PKCE is a technique for public clients to mitigate the threat of having the authorization code intercepted. Clients need to create a secret, then use that secret again when exchanging the authorization code for an access token. This way if the code is intercepted, by a malicious application it won’t be able to use it because the token request relies on the initial secret.

Generate a code verifier and code challenge

Apps must generate a unique code verifier for every authorization request. This value must be transformed to a code_challenge, which is sent to the authorization server to obtain the authorization code. A code_verifier is a high-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / - / . / _ / ~, with a minimum length of 43 characters and a maximum length of 128 characters. The code verifier should have enough entropy to make it impractical to guess the value.

Supported methods for generating a code challenge
METHODDESCRIPTION
plainThe code challenge is the same value as the code verifier generated above. code_challenge = code_verifier
S256The code challenge is the Base64URL (without padding) encoded SHA256 hash of the code verifier. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

Send a request to the auth server

To obtain user authorization, send a request to the authorization server at https://authentication.video.ibm.com/authorize. This endpoint handles active session lookup, authenticates the user, and obtains user consent. The authorization server supports the following additional query string parameters for installed applications:

PARAMETERIMPORTANCEDESCRIPTION
code_challengeREQUIREDSpecifies an encoded code_verifier that will be used as a server-side challenge during authorization code exchange
code_challenge_methodOPTIONALDefaults to plain. Must be used with code_challenge. Supported values: plain, S256

Exchange authorization code for refresh and access tokens

To exchange an authorization code for an access token, call the token endpoint (https://video.ibm.com/oauth2/token) and set the following parameters:

PARAMETERTYPEIMPORTANCEDESCRIPTION
grant_typestringREQUIREDMUST be authorization_code in this case.
client_idstringREQUIRED40-character long string, provided by IBM Video Streaming
codestringREQUIREDThe authorization code received from the authorization endpoint
code_verifierstringREQUIREDCode verifier that has been created
redirect_uristringREQUIREDThe redirect URI used by the authorization server to return the authorization response

Example

The following is an example with the authorization code flow using PKCE.

1 - The client opens a browser with the authorization endpoint:

https://authentication.video.ibm.com/authorize
?response_type=code
&client_id=AAAAAAAAAABBBBBBBBBBCCCCCCCCCCDDDDDDDDDD
&redirect_uri=https://example.com/get_auth_code
&scope=broadcaster
&state=XYZ
&code_challenge=bWl6dQ
&code_challenge_method=S256

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
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&client_id=AAAAAAAAAABBBBBBBBBBCCCCCCCCCCDDDDDDDDDD&code=19d8dbb3ebac55f110c3b526e38bcfdfbf46d659&redirect_uri=http://example.com/get_access_token&code_verifier=asdf

4 - The response of the 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","refresh_token":"cb345cdef123ef1267890abcdef04567890abcd1","token_type":"bearer", "expires_in":86400}