OAuth 2.0を使った認証

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:

Ustream 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:

(NOTE: 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 for Authorization Code

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.

NOTE: 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):

Token for Resource Owner Password Credentials

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:

Token for Client

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://www.ustream.tv/oauth2/authorize
?response_type=code
&client_id=AAAAAAAAAABBBBBBBBBBCCCCCCCCCCDDDDDDDDDD
&redirect_uri=http://example.com/get_access_token
&device_name=My%20Device
&scope=offline+broadcaster
&display=touch
&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: www.ustream.tv
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://www.ustream.tv/oauth2/authorize
?response_type=token
&token_type=mac
&client_id=AAAAAAAAAABBBBBBBBBBCCCCCCCCCCDDDDDDDDDD
&redirect_uri=http://example.com/token
&device_name=My%20Device
&scope=offline+broadcaster
&display=touch
&state=XYZ
				

2/a. 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/b. 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://www.ustream.tv/oauth2/authorize
?response_type=token
&client_id=057ce944b015ec9fdf546dfbbe1b7af4b19e8158
&redirect_uri=https://www.ustream.tv/oauth2/redirect
&device_name=MyDevice
&display=touch
&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"

Acquiring the streamkey for an external broadcasting application

If you wish to use an non-Ustream provided broadcaster application or appliance (like Flash Live Media Encoder, Wirecast, Tricaster, etc., you will need a streamkey to authenticate with Ustream and proving that broadcasting to that particular channel is allowed. Also you should get the ingest point where your device or application should connect.

You can access the streamkey (it is usually the parameter "stream" in the configuration of these devices) the following way. The endpoint requires you to provide the OAuth2 authorization key to complete. The endpoint is at https://api.ustream.tv/channels/CHANNEL_ID/authorizations/broadcasting.json

GET /channels/123456/authorizations/broadcasting.json
Host: api.ustream.tv
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded
			

HTTP/1.1 200 OK
Cache-Control: no-store
{"streaming_key": "kqDlIyGb0H47g8SRSyKjyxAqPmiwTbw3"}
			

Acquiring the channelkey for an external broadcasting application

If you wish to use Flash media live encoder , you will need the channelkey to authenticate with Ustream and proving that broadcasting to that particular channel is allowed. Also you should get the ingest point where your device or application should connect.

You can access the channelkey (it is usually the parameter "stream" in the configuration of these devices) the following way. The endpoint requires you to provide the OAuth2 authorization key to complete. The endpoint is at https://api.ustream.tv/channels/CHANNEL_ID/authorizations/broadcasting/channel_key.json

Example call

GET /channels/123456/authorizations/broadcasting/channel_key.json
Host: api.ustream.tv
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded
			

Example response

HTTP/1.1 200 OK
Cache-Control: no-store
{"channel_key": "kqDlIyGb0H47g8SRSyKjyxAqPmiwTbw3"}