youtube api v2.0 - oauth 2.0 authorization - youtube — google developers.pdf

8/21/2019 YouTube API v2.0 - OAuth 2.0 Authorization - YouTube — Google Developers.pdf

1/14

pico.mirandola.cea@gmail.

com

Esci

YouTube API v2.0 - OAuth 2.0 Authorization

Note: The YouTube Data API (v2) has been officially deprecated as of March 4, 2014. Please refer to our deprecation

policy for more information. Please use the YouTube Data API (v3) for new integrations and migrate applications still

using the v2 API to the v3 API as well.

Contents

Overview

Obtain authorization credentials

OAuth 2.0 flows

Server-side web applications

Client-side web applications

Installed applications

Devices

Calling the YouTube Data API

Refreshing an access token

Client libraries

Overview

The YouTube Data API supports the OAuth 2.0 protocol for authorizing access to private user data. The list below explainssome core OAuth 2.0 concepts:

When a user first attempts to use functionality in your application that requires the user to be logged in to a Google

Account or YouTube account, your application initiates the OAuth2 authorization process.

Your application directs the user to Google's authorization server. The link to that page specifies the scope of

access that your application is requesting for the user's account. The scope specifies the resources that your

application can retrieve, insert, update, or delete when acting as the authenticated user.

If the user consents to authorize your application to access those resources, Google will return a token to your

application. Depending on your application's type, it will either validate the token or exchange it for a different type of

token.

For example, a server-side web application would exchange the returned token for an access token and a refresh

token. The access token would let the application authorize requests on the user's behalf, and the refresh token

would let the application retrieve a new access token when the original access token expires.

This section of the API documentation covers the following topics:

The Obtain authorization credentials section points you to instructions for prerequisite steps to using OAuth 2.0 in

your application.

The OAuth 2.0 flows section explains different flows for obtaining OAuth 2.0 access tokens for either server-side

web applications, client-side web applications, installed applications, or devices.

X YouTube Cerca

Prodotti YouTube


2/14

The Calling the YouTube Data API section explains how to use the OAuth 2.0 tokens that your application obtains to

make authorized API requests on a user's behalf.

The Client libraries section describes client library support for OAuth 2.0.

Obtain authorization credentials

Your application must have authorization credentials to be able to use the YouTube Data API. You can obtain credentialsthrough the Google Developers Console by following the instructions for the instructions for the most recent YouTube Data

API version (v3).

The Developers Console associates your credentials with the APIs that you indicate that your application will use. Note that

the Developers Console does not allow you to select the YouTube Data API (v2). However, authorization credentials for the

v3 API will also work for the v2 API.

If possible, you should actually use YouTube Data API (v3) rather than the v2 API in your application. The YouTube API blog

explains some of the benefits that the newer API offers, and we have added a year's worth of additional functionality to the

API since that blog post!

OAuth 2.0 flows

Google supports several OAuth 2.0 use cases:

The server-side flow supports web applications that can securely store persistent information.

The client-side flow supports JavaScript applications running in a browser.

The installed application flow supports applications installed on a device, such as a phone or computer.

The device flow supports devices with limited input capabilities, such as game consoles and video cameras.

Server-side web applications

This flow is designed for web applications with servers that can store information and maintain state. While this section

walks through the steps your code would go through to use OAuth 2.0 in a server-side web application, you could also use

one of several client libraries in your OAuth 2.0 implementation.

The following steps explain the server-side flow:

1. Obtain an access token

Note: Requests to Google's authorization server must use https instead of http because the server is onlyaccessible over SSL (HTTPs) and will refuse HTTP connections.

When a user first tries to perform an action that requires API authentication, direct the user to Google's authorization

server at https://accounts.google.com/o/oauth2/auth. It supports the following URL parameters:

Parameter Description

client_id Required. The OAuth 2.0 client ID for your application.

redirect_uri Required. A registered redirect_uri for that client ID.

response_type Required. Set this parameter's value to code.

scope Required. A space-delimited list of scopes that identify the resources that your

application could access on the user's behalf.


3/14

approval_prompt Optional. This parameter indicates whether the user should be prompted to grant

account access to your application each time she tries to complete a particular action.

The default value is auto, which indicates that a user would only need to grant access

the first time she tried to access a protected resource.

Set the parameter value to force to direct the user to a consent page even if she has

already granted access to your application for a particular set of scopes.

access_type Recommended. This parameter indicates whether your application can refresh access

tokens when the user is not present at the browser. Valid parameter values are online

and offline. Set this parameter value to offline to allow the application to refresh

access tokens when the user is not present. (This is the method of refreshing access

tokens described later in this document.)

state Optional. Any string that your application would use to maintain state between the

request and redirect response. Your application will receive the same value that it sends

for this parameter. For example, you could use this parameter to redirect the user to a

particular resource in your application.

The sample URL below shows a redirect to Google's authorization server for an application requesting permission tosubmit YouTube Data API requests on the user's behalf:

https://accounts.google.com/o/oauth2/auth?

client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&

redirect_uri=http://localhost/oauth2callback&

scope=https://gdata.youtube.com&

response_type=code&

access_type=offline

2. User decides whether to grant access to your application

Google's authorization server will display the name of your application and the Google services that it is requesting

permission to access on the user's behalf. The user can then consent or refuse to grant access to your application.

You can test this flow by clicking on the sample URL in step 1. If you also place a file on your server at

http://localhost/oauth2callback, you will also be able to see how the user's response appears in the

redirect URI. (See step 3 for more details.)

3. Google redirects user to your application

After the user consents or refuses to grant access to your application, Google will redirect the user to the

redirect_uri that you specified in step 1.

If the user granted access to your application, Google will have appended a code parameter to the

redirect_uri. This value is a temporary authorization code that you can exchange for an access token as

discussed in step 4.

http://localhost/oauth2callback?code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf

If the user refused to grant access to your application, Google will have included the access_denied error

message in the hash fragment of the redirect_uri:

http://localhost/oauth2callback#error=access_denied

4. Exchange authorization code for refresh and access tokens


4/14

Assuming the user has granted access to your application, exchange the authorization code obtained in step 3 for a

refresh token and access token. To do so, send a POST request to

https://accounts.google.com/o/oauth2/token that includes the following key-value pairs in the request

body:

Key Value

code The authorization code that Google returned to your redirect_uri in step 3.

client_id The OAuth 2.0 client ID for your application.

client_secret The client secret associated with your client ID. This value is displayed in the Google

Developers Console.

redirect_uri A registered redirect_uri for your client ID.

grant_type Set this value to authorization_code.

A sample request is displayed below:

POST /o/oauth2/token HTTP/1.1

Host: accounts.google.com

Content-Type: application/x-www-form-urlencoded

code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf&


client_secret=hDBmMRhz7eJRsM9Z2q1oFBSe&


grant_type=authorization_code

5. Process response and store tokens

Google will respond to your POST request by returning a JSON object that contains a short-lived access token and a

refresh token.

{

"access_token" : "ya29.AHES6ZTtm7SuokEB-RGtbBty9IIlNiP9-eNMMQKtXdMP3sfjL1Fc",

"token_type" : "Bearer",

"expires_in" : 3600,

"refresh_token" : "1/HKSmLFXzqP0leUihZp2xUt3-5wkU7Gmu2Os_eBnzw74"

}

Important: Your application should store both values.

The Calling the YouTube Data API section explains how to submit an authorized request using the access

token.

The Refreshing an access token section explains how to use the refresh token to obtain a new access token if

the one that you have expires.

Client-side web applications

This flow is designed for JavaScript-based web applications that cannot maintain state over time.

The following steps explain the client-side flow:



5/14

Note: Requests to Google's authorization server must use https instead of http because the server is only

accessible over SSL (HTTPs) and will refuse HTTP connections.





redirect_uri Required. A registered redirect_uri for that client ID.

response_type Required. Set this parameter's value to token.

scope Required. A space-delimited list of scopes that identify the resources that your

application could access on the user's behalf.

approval_prompt Optional. This parameter indicates whether the user should be prompted to grant

account access to your application each time she tries to complete a particular action.

The default value is auto, which indicates that a user would only need to grant access

the first time she tried to access a protected resource.

Set the parameter value to force to direct the user to a consent page even if she has

already granted access to your application for a particular set of scopes.

state Optional. A string used to maintain state between the request and redirect. This value

will be appended to your redirect_uri after the user consents to or denies your

application's access request.

The sample URL below shows a redirect to Google's authorization server for an application requesting permission to

submit YouTube Data API requests on the user's behalf:





response_type=token








After the user consents or refuses to grant access to your application, Google will redirect the user to the

redirect_uri that you specified in step 1.

If the user granted access to your application, Google will have appended a short-lived access token in the hash

fragment of the redirect URI. The response will also include the expires_in and token_type parameters.

These parameters describe the lifetime of the token in seconds and the kind of token that is being returned,

respectively. Finally, the response will include the state parameter if a state parameter was included in the

original request to the authorization server.


6/14

http://localhost/oauth2callback#access_token=1/QbIbRMWW&token_type=Bearer&expires_in=3

600

Note: Your application should also allow other fields to be returned in the response. The list provided above

identifies the minimum set of fields that will be appended to the redirect_uri.

JavaScript code running on your page can capture the access token from the window.location.hash value

and either store the token in a cookie or POST it to a server.




4. Validate the user's token

Assuming the user has granted access to your application, you need to explicitly validate the token returned in the

redirect_uri. You validate the token by specifying the token as the value of the access_token parameter in a

web service request to https://www.googleapis.com/oauth2/v1/tokeninfo. That URL accepts an access

token and returns information about that token, including the application that the token was issued to, the user

associated with the token, the scopes that the user granted access to, and the remaining life of the token.

The sample URL below demonstrates where you would send a token validation request:

https://www.googleapis.com/oauth2/v1/tokeninfo?access_token=1/fFBGRNJru1FQd44AzqT3Zg

5. Process the token validation response

In response to a token validation request, the Google authorization server will return either a JSON object that

describes the token or an error message.

If the token is still valid, the JSON object will include the following values:

Field Description

audience The application that is the intended user of the access token.

Important: Before using the token, you need to verify that this field's value exactly matches

your client_id in the Google Developers Console. This verification ensures that your

application will not be vulnerable to the confused deputy problem.

expires_in The number of seconds left before the token will become invalid.

scope A space-delimited list of scopes that the user granted access to. The list should match the

scopes you specified in your authorization request in step 1.

userid This value lets you correlate profile information from multiple Google APIs. It is only

present in the response if you included the

https://www.googleapis.com/auth/userinfo.profile scope in your request in

step 1. The field value is an immutable identifier for the logged-in user that can be used to

create and manage user sessions in your application.

A sample response is shown below:


7/14

{

"audience":"8819981768.apps.googleusercontent.com",

"user_id":"123456789",

"scope":"https://gdata.youtube.com",

"expires_in":436

}

If the token has expired, been tampered with, or had its permissions revoked, Google's authorization server will

return an error message in the JSON object. The error surfaces as a 400 error, and a JSON body in the formatshown below:

{"error":"invalid_token"}

By design, no additional information is given as to the reason for the failure.

Installed applications

This flow is designed for applications that are installed on a device, such as a mobile phone or computer. These

applications could access the YouTube Data API while the user is interacting with the application or when the application is

running in the background for an extended period of time without direct user interaction.

This flow assumes that the application cannot securely store tokens that would enable a user to interact with YouTube Data

API. It also requires that the application has access to the system browser or has the ability to embed a browser control. If

the application does not meet either of these conditions, refer to the OAuth 2.0 instructions for devices by clicking the

Devices tab above.

The following steps explain this flow:

1. Register your application as an installed application

When registering your application, make sure that you specify that it is an installed application. This results in a

different default value for the redirect_uri parameter.


Note: Requests to Google's authorization server must use https instead of http because the server is only

accessible over SSL (HTTPs) and will refuse HTTP connections.





redirect_uri Required. A registered redirect_uri for that client ID. For installed applications, you can

choose between an http://localhost: port or urn:ietf:wg:oauth:2.0:oob as

described below:

http://localhost: port

This value indicates that Google's authorization server should return the authorization

code as a query string parameter to the client device's web server. You may specify a

port number without changing the configuration in the Google Developers Console.

To receive the authorization code on this URL, your application must be listening on

the local web server. If your platform supports it, this is the recommended


8/14

mechanism for obtaining the authorization code. However, note that not all platforms

support this approach and that even if a platform does support it, other software (e.g.

Windows firewall) may prevent delivery of the message.

urn:ietf:wg:oauth:2.0:oob

This value indicates that Google's authorization server should return the authorization

code in the browser's title bar. This option is useful if the client cannot listen on an

HTTP port without significant modifications to the client. Windows applications

possess this characteristic.

If your application uses this value, it needs to determine when the browser has loaded

a response from the authorization server. It will then need to extract the authorization

code from the title of the page served in the browser. See step 4 for specific

instructions for parsing the token from the page title.

Your application should also close the browser window if you want to prevent the

user from seeing the page with the authorization code. The mechanism for closing

that window varies from platform to platform.

response_type Required. Set this parameter's value to code.

scope Required. A space-delimited list of scopes that identify the resources that your application

could access on the user's behalf.

state Optional. Any string that your application would use to maintain state between the request

and redirect response. Your application will receive the same value that it sends for this

parameter. For example, you could use this parameter to redirect the user to a particular

resource in your application.

The sample URL below shows a redirect to Google's authorization server for an application requesting permission to

submit YouTube Data API requests on the user's behalf:





response_type=code&

access_type=offline








After the user consents or refuses to grant access to your application, Google will either redirect the user to the

redirect_uri that you specified in step 2 or return a page to the user's browser.

If you set the redirect_uri to http://localhost (or some path on the local web server), then one of the

following two scenarios will apply:


9/14

If the user granted access to your application, Google will have appended a code parameter to the

redirect_uri. This value is a temporary authorization code that you can exchange for an access token

as discussed in step 5.

http://localhost/oauth2callback?code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf




If you set the redirect_uri to urn:ietf:wg:oauth:2.0:oob, Google's authorization server will return a

page to the browser like the one shown below. Your application can then extract the authorization code from

the page title.

To extract the token, your application should assume that everything that follows the last space character in the

page title is a parameter string in the format x=a&y=b. Your code should parse the parameters from that

substring, looking for a code= or error= assignment to indicate that the page contains the final title string and

the sign-in flow is complete. If the page title assigns a value to the code parameter, then that value is the token.

However, your application should not make assumptions about the token length or the number of parameters in

the parameter string.

For example, the screenshot below shows a page with the following attributes:

Page title: Success code=4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu

Parameter string: code=4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu

Authorization token: 4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu

5. Exchange authorization code for refresh and access tokens

Assuming the user has granted access to your application, exchange the authorization code obtained in step 4 for a

refresh token and access token. To do so, send a POST request to

https://accounts.google.com/o/oauth2/token that includes the following key-value pairs in the requestbody:

Key Value


10/14

code The authorization code that Google returned to your redirect_uri in step 4.



Developers Console.

redirect_uri A registered redirect_uri for your client ID.

grant_type Set this value to authorization_code.

A sample request is displayed below:




code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf&


client_secret=hDBmMRhz7eJRsM9Z2q1oFBSe&


grant_type=authorization_code

6. Process response and store tokens

Google will respond to your POST request by returning a JSON object that contains a short-lived access token and a

refresh token.

{

"access_token" : "ya29.AHES6ZTtm7SuokEB-RGtbBty9IIlNiP9-eNMMQKtXdMP3sfjL1Fc",

"token_type" : "Bearer",

"expires_in" : 3600,

"refresh_token" : "1/HKSmLFXzqP0leUihZp2xUt3-5wkU7Gmu2Os_eBnzw74"

}

Important:Your application should store both values.


token.



Devices

This flow is designed for applications that run on devices with limited input capabilities, such as game consoles or video

cameras. In this flow, the user interacts with an application on the device to obtain a URL and a device code. The user then

switches to another device, such as a computer or smartphone, that has richer input capabilities to authorize the device

code.

The following steps explain this flow:

1. Embed your client_id and client_secret in your application

You need to register your application with Google and embed the client_id and client_secret created during

the registration process into your application.


11/14

2. Request a device code

Your device sends a POST request to Google's authorization server at

https://accounts.google.com/o/oauth2/device/code. The request specifies the following parameters:



scope Required. A space-delimited list of scopes that identify the resources that your application could

access on the user's behalf.

The following sample request shows how to retrieve a device code:

POST /o/oauth2/device/code HTTP/1.1




scope=https://gdata.youtube.com

3. Handle the response

Google will respond to your request by returning a JSON object to your device. A sample response is shown below:

{

"device_code" : "4/L9fTtLrhY96442SEuf1Rl3KLFg3y",

"user_code" : "a9xfwk9c",

"verification_url" : "http://www.google.com/device",

"expires_in" : "1800"

"interval" : 5,}

The application on your device should display the user_code and verification_url to the user. It should store

the device_code, expires_in, and interval values for use in step 4.

4. Begin polling Google's authorization server

Your application can begin polling Google's authorization server using the device_code returned in the JSON

response in step 3. To do so, your application sends a POST request to

https://accounts.google.com/o/oauth2/token that specifies the following key-value pairs:

Key Value



Developers Console.

code The device code obtained in step 3.

grant_type Set this value to http://oauth.net/grant_type/device/1.0.

A sample polling request is shown below. The interval returned in the JSON response in step 3 specifies the

minimum amount of time, in seconds, that your application should wait between polling requests.


12/14





client_secret=hDBmMRhz7eJRsM9Z2q1oFBSem&

code=4/YMSlR3fSCC1NtUh073DuZKTJJ3ss&

grant_type=http://oauth.net/grant_type/device/1.0

Until the user completes steps 5 through 7, your application will receive one of the following responses to each

polling request:

The following response indicates that the user has not yet completed the steps to grant API access to the

device:

{

"error" : "authorization_pending"

}

The following response indicates that your application is sending polling requests too frequently:

{

"error" : "slow_down"

}

5. User enters user_code in separate browser

The user launches a browser on another device, such as a computer or mobile phone, and navigates to the

verification_url. That URL will display a page where the user can enter the user_code obtained in step 3.

Note: The user_code is case-sensitive, so the user will need to enter it exactly as it appears in the response.

6. User logs in to Google Account that will be used on your device

After entering the user_code, the user will be asked to log in to the Google Account that will be used to

authenticate YouTube Data API requests from your device. (If the user is already logged in, she will proceed directly

to the next step.)


After the user logs in, Google's authorization server will display a page that shows the name of your application and

the Google services that it is requesting permission to access on the user's behalf. The user can then consent or

refuse to grant access to your application.


13/14

8. Process response from polling server to obtain tokens

If the user grants access to your application, the next polling request that your device sends will return a JSON

object that contains an access token and a refresh token.

{

"access_token":"1/fFAGRNJru1FTz70BzhT3Zg",

"expires_in":3920,

"token_type":"Bearer",

"refresh_token":"1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ"

}

Important: Your application should store both values.


token.



Calling the YouTube Data API

After obtaining an access token for a user, your application can use that token to submit authorized API requests on that

user's behalf. The API supports two ways to specify an access token. The first option provides greater security and is the

recommended approach.

1. Specify the access token as the value of the Authorization: Bearer HTTP request header:

POST /feeds/api/users/default/uploads HTTP/1.1Host: gdata.youtube.com

Authorization: Bearer ACCESS_TOKEN

...

You can test this using cURL with the following command:

curl -H "Authorization: Bearer ACCESS_TOKEN" gdata.youtube.com/feeds/api/users/default/up

loads

2. Specify the access token as the value of the access_token query parameter:

https://gdata.youtube.com/feeds/api/users/default/uploads?access_token=ACCESS_TOKEN

You can test this using cURL with the following command:

curl gdata.youtube.com/feeds/api/users/default/uploads?access_token=YOUR_ACCESS_TOKEN

The API will return an HTTP 401 response code (Unauthorized) if you submit a request to access a protected resource with

an expired access token. The following section explains how to refresh an access token.

Refreshing an access token

If your application obtains a refresh token during the authorization process, then you will need to periodically use that token

to obtain a new, valid access token. Server-side web applications, installed applications, and devices all obtain refresh

tokens.


14/14

At any time, your application can send a POST request to Google's authorization server that specifies your client ID, your

client secret, and the refresh token for the user. The request should also set the grant_type parameter value to

refresh_token. The following example demonstrates this request:




client_id=21302922996.apps.googleusercontent.com&

client_secret=XTHhXh1SlUNgvyWGwDk1EjXB&

refresh_token=1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ&

grant_type=refresh_token

The authorization server will return a JSON object that contains a new access token:

{

"access_token":"1/fFAGRNJru1FTz70BzhT3Zg",

"expires_in":3920,

"token_type":"Bearer"

}

Client libraries

The Google Data client libraries that support the YouTube Data API do not currently support OAuth 2.0. However, a newer

set of Google API client libraries, which do not support the YouTube Data API, do provide OAuth 2.0 support.

As such, it is an option to use these newer libraries, which are listed below, for their OAuth 2.0 capabilities and then force the

Google Data client library to use the OAuth 2.0 token(s) that you have obtained.

Google APIs Client Library for JavaGoogle APIs Client Library for Python

Google APIs Client Library for .NET

Google APIs Client Library for Ruby

Google APIs Client Library for PHP

OAuth 2.0 Library for Google Web Toolkit

Google Toolbox for Mac OAuth 2.0 Controllers

You can also follow the instructions in the Calling the YouTube Data API section to modify your code to properly set the

OAuth 2.0 token values.

« Previous

Authentication

Next »

Flash Applications

Salvo quanto diversamente indicato, i contenuti di questa pagina sono disponibili ai sensi della licenza Creative Commons

Attribuzione 3.0 , mentre gli esempi di codice sono disponibili ai sensi della licenza Apache 2.0. Per informazioni dettagliate

leggi le Norme del sito.

Last updated gennaio 14, 2015.

youtube api v2.0 - oauth 2.0 authorization - youtube — google developers.pdf

Documents