What are authentication and authorization?
Third-party applications often require limited access to a user's Google Account for certain types of activity. To ensure that user data is not abused, all requests for access must be approved by the account holder. Access control has two components, authentication and authorization.
Authentication services allow users to sign in to your application using a Google Account. Some services also allow users to sign in using another account, such as an OpenID login. Authentication allows you to identify users, for example to provide a customized experience when using your application.
Authorization services let users provide your application with access to the data they have stored in Google applications. Google takes privacy seriously, and any application that requires access to a user's data must be authorized by the user.
Authentication: Allow users to sign-in
Authorization: Access users' data
OpenID for Google Account Users, based on the OpenID 2.0 protocol, allows users to log into your website or web application with their Google account. When Google authenticates a user's account, it returns a user ID to your application, which allows you to collect and store user information. OpenID also allows you to get access to certain user account information, with user approval.
The OAuth open-standard protocol allows users to authorize access to their data, after they have been authenticated. When you use OAuth, the user is presented with a screen asking them to give your application access to the data you request. If they agree, OAuth returns a token which you can use to access that data. OAuth is available for web applications and for installed applications.
* The hybrid protocol uses both OpenID and OAuth, to provide both authentication and authorization in a single-step process.
* Google's proprietary AuthSub API offers access control features similar to those available using OAuth. AuthSub is not used widely outside the Google APIs, so we recommend that you migrate to OAuth where possible.
The Authentication and Authorization APIs can be used with both regular Google accounts and Google Apps hosted accounts. Although the user experience varies slightly, the process of managing authorization and/or authentication programmatically is the same for both types of accounts.
Getting Started
I want to...
* Choose an auth mechanism that will work for my application.
* Authorize my app to access data using a Google API.
* Let users sign in to my website using their Google Account.
* Register my application with Google.
* Get help! Join our community and participate in the discussion group.
http://code.google.com/intl/it-IT/apis/accounts/docs/GettingStarted.html
piazzare i seguenti link nel punto giusto ... un poco di confusione!http://code.google.com/intl/it-IT/apis/accounts/docs/OpenID.html
http://code.google.com/intl/it-IT/apis/accounts/docs/RegistrationForWebAppsAuto.html
http://groups.google.com/group/Google-Accounts-API?pli=1
Choosing an Auth Mechanism
Authentication and Authorization for Google APIs allow third-party applications to get limited access to a user's Google accounts for certain types of activities. This document explains the available auth mechanisms and what each one provides for your application.
* OAuth provides authorization for all Google APIs. This allows your application to request access to data associated with a user's Google Account.
* Hybrid protocol provides authentication and authorization for web applications, allowing users to log in and authorize access to their data in a single step. This protocol uses OpenID to provide authentication services, and OAuth to provide authorization to Google APIs.
* OpenID authenticates a user with their Google Account. This allows users to log in to your web site without having to sign up for a new account.
AuthSub and ClientLogin are Google's proprietary authorization APIs, available as an alternative to OAuth for most Google APIs. If possible, you should migrate applications using these auth mechanisms to one of the recommended options above.
OAuth - authorization for web and installed applications
Many Google services allow third-party access to user-generated data, such as Calendar or feed data, so long as access is authorized by the user. This feature allows users to share and exchange data between their Google applications and third-party applications for a variety of purposes. Google supports several options for getting authorized access to a user's Google data, offering access to both web applications and installed applications.
OAuth is an open standard. It can be used for authorization with services provided by Google, or by other companies that have implemented the standard.
OAuth allows users to log in using the familiar Google login box, promoting confidence in security. It also offers great flexibility; it allows the user to select which account to use if more than one is logged in, it supports SAML-enabled hosted domains, it handles login errors and suspicious activity in the familiar Google environment, and it allows users to create a Google account if they don't already have one.
OAuth for web applications
Web applications that need authorized access to data associated with a Google Account or a Google Apps Account can use Google's implementation of the OAuth API. For help implementing OAuth for a web-based application, see the OAuth for Web Apps guide.
OAuth for installed applications
An application installed on a user's machine—whether it's a desktop computer or a mobile device—can also use OAuth to authorize access to data associated with a Google Account. For help implementing OAuth for installed applications, see the OAuth for Installed Applications guide.
Hybrid Protocol - authentication & authorization for web applications
Some applications require both authentication, for example, to handle sessions or store data provided directly to the application, and authorization, to access the data associated with a user's Google Account.
The hybrid protocol combines OpenID with OAuth to provide these services. This allows the user to authenticate and authorize access to their data in a single step.
For help implementing the hybrid solution, see Implementing OAuth with OpenID.
OpenID - authentication for web applications
Using Google's OpenID services, web applications can hand off user authentication tasks to Google. This feature frees you up from having to manage log-in information and security measures, and also avoids forcing your users to set up yet another login account.
When you use OpenID, your application does not handle any login information. After a user successfully logs in to their Google Account, the OpenID server returns a persistent user identifier that your application can use to recognize that user, handle sessions, store user-specific data, and so on.
Google's OpenID service is based on the open-source OpenID 2.0 protocol. You can use the same interface to accept logins from any OpenID provider.
OpenID is designed for web applications only. For more information about implementing a login solution, see the following documents:
* OpenID for Google Account Users
* OpenID for Google Apps (hosted) Account Users.
Marketplace applications
Applications built for the Google Apps Marketplace can use Google's OpenID service to provide OpenID-based Single Sign-On, and handle authorization requests using two-legged OAuth.
For details on implementing OpenID-based SSO, see OpenID Federated Login Service for Google Apps. For details on two-legged OAuth, see OAuth for Google Apps domains. You should also read the Marketplace Best Practices for SSO.
OAuth for Web Applications
This document describes how to get started using Google's implementation of the OAuth protocol to authorize a web application's requests for access to a user's data. If instead your application is installed on a computer or a mobile device, you should read the documentation on OAuth for Installed Apps.
If you want to allow users to sign in to your application using OpenID, you can find more information about implementing the Hybrid Protocol (OAuth+OpenID) in the OpenID documentation.
Prerequisites
This document is written for web application developers using the Google Data APIs to access a user's data. It assumes that you have read the documentation for the API you are using and are aware of any service-specific authorization issues. The document also assumes that you are familiar with the principles behind OAuth. For more background information, see the Beginner's Guide to OAuth
Contents
http://code.google.com/intl/it-IT/apis/accounts/docs/OAuth.html
1. The OAuth authorization process
2. Getting ready for OAuth
1. Deciding whether or not to register your web application
2. Determining the scope of the data to which you require access
3. Setting up a mechanism to manage OAuth tokens
4. Setting up a mechanism to request access to a Google service
5. Implementing OpenID (optional)
3. Working with OAuth tokens
1. Setting a callback URL
2. Identifying your application to users
3. Working with Google Apps domains
4. OAuth for Google Apps domains
5. Migrating from AuthSub to OAuth
The OAuth authorization process
The OAuth authorization process involves a series of interactions between your web application, Google's authorization servers, and the end user.
At a basic level, the process is as follows:
1. Your application gets an unauthorized request token from Google's authorization server.
2. Google asks the user to grant you access to the required data.
3. Your application gets an authorized request token from the authorization server.
4. You exchange the authorized request token for an access token.
5. You use the access token to request data from Google's service access servers.
When your application initially requests access to a user's data, Google issues an unauthorized request token to your application.
Google prompts the user to log into their account if they are not already logged in. Google then displays an authorization page that allows the user to see what Google service data your application is requesting access to.
If the user approves your application's access request, Google issues an authorized request token. Each request token is valid for only one hour. Only an authorized request token can be exchanged for an access token, and a request token can be exchanged for an access token only once.
An access token is, by default, long-lived. It is specific to the user account specified in the original request for authorization, and grants access to only the services specified in that request. Your application should store the access token securely, as it is required for all access to a user's data.
Getting ready for OAuth
Before you can set up your application to use the Google Authorization service with OAuth, you must complete the following tasks.
Deciding whether or not to register your web application
To provide your users with additional assurances of the security of their data, you can choose to register your web application with Google and sign your requests with the registered security certificate. Some Google Data API feeds are available to registered applications only.
Your application must sign each OAuth request it makes. If you choose to use a RSA-SHA1 signature to sign your requests, you must upload a security certificate as part of the registration process.
Alternatively, you can use a HMAC-SHA1 signature to sign your requests. No certificate is required for HMAC-SHA1 signatures. Instead, Google generates an OAuth consumer secret value, which is displayed on your domain's registration page after you have registered.
For more information on the registration process, see Registration for Web Applications.
Determining the scope of the data to which you require access
Each Google service sets limits on the access it will allow through the Google Data APIs. This access is expressed as a scope value. Some services provide a variety of scope values, to allow a user to choose which applications should have access to which data. For information about the available scope values for the Google service you want to access, see the documentation for that service.
You should generally request a token for the broadest scope you expect to need. For example, if your application requires access to a user's Google Calendar feed, you should usually request a token for the scope http://www.google.com/calendar/feeds/, which grants access to all of Calendar's feeds.
If you request a token for the scope http://www.google.com/calendar/feeds/default/allcalendars/full, your application will have access to the user's "All Calendars" feed only, and will not have access to the feeds for individual calendars.
Setting up a mechanism to manage OAuth tokens
When you obtain an OAuth access token for a user's data, you must use that access token for all future interactions with the specified Google service on behalf of the user.
Your application should manage token storage securely, including tracking the Google service for which each token is valid. If you require access to more than one Google service, you can obtain multiple access tokens, but no more than ten access tokens per user and application can be outstanding at any time.
If your application supports multiple user accounts, you must also track the account for which each token is valid. Each OAuth token is specific to the user who authorized access. Therefore, your application must be able to associate a token with the correct user. The recommended option is to issue a cookie to the user before making the token request. After the user grants access to the requested data, Google sends an authorized request token and redirects the user to your application. You can then use your application's cookie to associate the token with the correct user.
Setting up a mechanism to request access to a Google service
Every request to a Google service must be signed, and must include a valid OAuth access token. In general, each request is made in the form of a HTTP GET request, with the access token and signature included in the header. Requests that write new data should use a HTTP POST.
For more information on the proper request format for each Google Data API, refer to the documentation of that API.
Implementing OpenID (optional)
If you're implementing OpenID for user authentication, you might want to use the hybrid protocol to combine the two processes. With OpenID+OAuth, the tasks of getting a request token and authorizing it are handled as part of the OpenID request with OAuth extensions. As with OAuthGetRequestToken, these extensions are used to identify the Google services to be accessed. A successful response to the OpenID request contains an authorized request token. Once this token is received, use OAuthGetAccessToken to exchange it for an access token.
Working with OAuth tokens
To use OAuth, your application must generate well-formed, signed token request calls, and handle the responses, for the following sequence:
1. Get an unauthorized request token (OAuthGetRequestToken)
2. Authorize the request token (OAuthAuthorizeToken)
3. Exchange the authorized request token for an access token (OAuthGetAccessToken)
All OAuth requests must be signed, whether or not your application is registered. For further information, see Signing OAuth Requests.
You can experiment with requesting and receiving authorization tokens in the OAuth Playground.
For detailed documentation, see the OAuth API Reference.
Setting a callback URL
You can specify a value for oauth_callback in an OAuthGetRequestToken request, to determine where Google redirects the user after they authorize your access request. The callback URL can include query parameters. The redirect will include the same query parameters, as well as the authorized request token, which your application must be able to parse.
For example, when supporting multiple languages, you can include a query parameter that identifies the version of the application that a user is viewing. An oauth_callback value of "http://www.yoursite.com/Retrievetoken?Lang=de would result in the redirect "http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE". Parsing the token and the language parameter ensures that the user is redirected back to the correct version of the site.
If the oauth_callback parameter is not included, Google will direct the user to a web page that displays a verification number (see example), after authorizing your access request. The user must manually return to your application and enter the verification number before you can obtain an authorized request token.
Identifying your application to users
Google normally displays the name of an application when requesting access consent from the user (see example).
If your application is not registered, use the xoauth_displayname parameter in your OAuthGetRequestToken request to specify the name of your application. If that parameter is not specified, Google displays the domain name of the URL provided by the oauth_callback parameter. If no callback URL is provided, Google displays the string "anonymous".
Do not set this parameter if your application is registered. By default, Google shows the display name specified during registration. If you set a display name in your OAuthGetRequestToken request, Google will use this instead of your registered display name, and will include a message that the identity of your application cannot be verified.
Note: To set the xoauth_displayname parameter in the OAuth Playground, check the "Advanced" box before fetching the request token.
Working with Google Apps domains
If your application is designed for users on a hosted Google Accounts domain, consider using the hd parameter when authorizing a token. For more information on the hd parameter, see Handling Users with Multiple Accounts.
OAuth for Google Apps domains
Using 2-legged OAuth allows for domain-wide delegation of authority. A domain administrator can authorize access requests for all users. An application that has the OAuth consumer key and secret (roughly equivalent to a role account username and password) is allowed to act as any user in the domain when accessing Google Data APIs.
The domain administrator can revoke the key, change the secret, and control which APIs accept domain-wide delegation.
2-legged OAuth can be used, for example, to integrate with a document management system, enable third-party workflow applications, centralize backup of documents and contacts, or monitor document sharing inside and outside of the company.
Administrators for Google Apps Premier and Education Edition domains can enable 2-legged OAuth for their domains. This differs from the normal authorization flow, also known as 3-legged OAuth, in that no access token is required. All applications using 2-legged OAuth must be registered with Google.
Note: This feature is only available to Google Apps Premier and Education Edition domains.
Three key groups can use 2-legged OAuth, and the access controls can be set individually for each group.
Google Apps domain administrators
Administrators can build scripts and custom applications to manage user data for their domain using Google Data APIs. For example, an administrator can use the Google Documents Data List feed and 2-legged OAuth to provide every user in their domain with a Google Docs folder named "Human Resources", populated with common employee forms. Some Google Apps applications, such as the Google Apps Connector for BlackBerry Enterprise Server, also require OAuth to be enabled.
To learn about managing the domain administrator's key and secret associated with your Google Apps domain, and granting global access control, see "Managing the OAuth key and secret".
Third-party software vendors
Vendors can offer applications that use 2-legged OAuth to integrate with Google Apps. If the vendor has registered their own consumer key and secret with Google, you can grant their application access to a limited set of resources within your domain using the Manage API client page.
To learn about setting up third-party or internal access to a specific set of Google Data APIs, see "Managing Client API access".
Marketplace applications
Applications built for the Google Apps Marketplace can access Google APIs using 2-legged OAuth. A Marketplace application includes the API scope required in its application manifest. When the application is installed in a domain, the domain administrator must explicitly approve access to the declared scope. This gives the application access to the required scope, for that domain, using the application's 2-legged OAuth consumer key and secret.
For an example of how to use 2-legged OAuth with the Google Data API client libraries, see the Google Data OAuth documentation.
Example: Accessing a Google Data API feed
When sending access requests to Google services with 2-legged OAuth, you do not need an OAuth access token to access a user's data. Instead, include the xoauth_requestor_id query parameter in the request URL and set its value to the email address of the user whose data you are trying to access. Next, send the signed OAuth request using the HMAC-SHA1 signature method (the consumer key and secret are provided in the administrative control panel) or upload a public certificate to use RSA-SHA1. For more information on signing requests, see the Signing OAuth Requests section of this document.
The example below is used to upload an empty document, titled 'Company Perks', to the Google Docs account for j.doe@example.com. This request will succeed only if 2-legged OAuth has been enabled for the domain.
POST /feeds/documents/private/full?xoauth_requestor_id=j.doe%40example.com HTTP/1.1
Host: docs.google.com
Content-Type: application/atom+xml
Authorization: OAuth
oauth_version="1.0",
oauth_nonce="1c4fbbe4387a685829d5938a3d97988c",
oauth_timestamp="1227303732",
oauth_consumer_key="example.com",
oauth_signature_method="HMAC-SHA1",
oauth_signature="lqz%2F%2BfwtusOas8szdYd0lAxC8%3D"
term="http://schemas.google.com/docs/2007#document" />
Company Perks
The Authorization header should be contained on a single line. Newlines have been inserted here for clarity.
The xoauth_requestor_id must be included as a query parameter for requests using 2-legged OAuth. The oauth_token query parameter should not be used.
Migrating from AuthSub to OAuth
AuthSub is Google's proprietary authorization API. We recommend that you migrate to the open OAuth standard where possible. For more information about the differences between the two protocols, see Using OAuth with the Google Data APIs.
If you're already registered with Google to use AuthSub, you do not need to re-register to use OAuth. However, you must specify which signature method you'll use to sign your requests. If you are using an RSA-SHA1 signature, you must also upload a security certificate as part of your domain's registration record.
If you've been using secure tokens under AuthSub, these tokens are equivalent to OAuth access tokens. These secure tokens can be used with OAuth requests.
http://code.google.com/intl/it-IT/apis/accounts/docs/OpenID.html
http://code.google.com/intl/it-IT/apis/accounts/docs/RegistrationForWebAppsAuto.html
http://groups.google.com/group/Google-Accounts-API?pli=1
http://code.google.com/intl/it-IT/apis/accounts/docs/RegistrationForWebAppsAuto.html
Registration for Web-Based Applications
Developers of web applications using Google's Authorization service can opt to register their application domain with Google. There are several advantages to registering your domain. Registered applications:
* are recognized by Google. The Google "Access Consent" page, which asks users to grant/deny access to their account when requested by third-party applications, omits default text cautioning that the site is not trusted.
* can provide a better level of security for their users.
* get access to certain services (such as some Google Data API feeds) that require third-party applications to be registered.
* enables "2-legged" OAuth access for Google Apps domain administrators.
Note: Applications are NOT added to the Google search engine as part of the registration process and do not get preferential treatment in search result pages. If you're trying to add your site to the Google search engine, visit the Add your URL to Google page.
Web applications that opt not to register with Google can still use either the OAuth or AuthSub interfaces and conduct transactions using a lower level of security; at this level, Google does not automatically recognize the calling web application and adds a caution to the Google login page (see example).
Contents
1. Registering your web application
1. Registering a new domain
2. Updating an existing registration
Registering your web application
Registration involves giving Google some basic information about your web application. In addition, if you've opted to enhance the security of your requests to Google services by signing them, you may need to upload a security certificate. There are three levels of registration:
* Unregistered: Application is not recognized by Google. The Access Request page, which prompts your users to either grant or deny access for your application, displays this caution highlighted in yellow: "This website has not registered with Google. We recommend that you continue the process only if you trust this destination."
* Registered: Application is recognized by Google. The Access Request page displays this caution: "This website is registered with Google to make authorization requests, but has not been configured to send requests securely. We recommend that you continue the process only if you trust the following destination
."
* Registered with enhanced security: Registered applications with a security certificate on file can use secure tokens. The Access Request page removes cautions, displaying this message: " Google is not affiliated with , and we recommend that you grant access only if you trust the site."
Registration is optional but recommended. For more information on requirements for signing requests, see Signing AuthSub Requests or Signing OAuth Requests. Registered applications are considered "recognized" by Google and this is reflected in the messaging displayed on the Google Access Consent page, which is displayed to users when a third-party application requests access to a Google service and prompts users to grant/deny access for the application. The messaging differs depending on whether or not the application is registered and signs requests. For unregistered applications, a yellow background is displayed to indicate a caution.
Application domain registration with Google is now automated using a free Google account. If you don't have an account appropriate for registering your application, sign up for one here.
To register a new domain:
Go to the Google Manage Your Domains page. Make sure you're using the appropriate Google account. If you're not logged in at all, you'll be prompted to do so. If you start this process and quit without completing, return to the Manage Your Domains page and click on the Manage link for your domain. The site will remember where you left off.
Note: If you want to be able to use different sub-domains, you'll need to register each sub-domain separately.
1. Add your domain.
Under the heading "Add a New Domain", enter the URL for your domain and click the "Add Domain" button. A new link for the domain is added under the "Manage Registrations" heading. You can register up to eight different domains using one Google account. At this point in the process, your domain has been identified but not yet registered.
2. Verify your domain.
Under the heading "Manage Registrations", click on the link for the domain you just added. The interface walks you through the process of verifying that you have administrator access to the domain. Choose between one of two verification methods: upload an HTML file or add a specific meta tag to your home page.
* Uploading a file: With this method, Google specifies a file name starting with "google". Create an empty file with this name, using the html extension, and upload it to your domain. Be sure to place the file at the domain root. Check that the new file has been published, and return to the Manage Your Domains page for this domain. Click the "Verify" button. If you are unable to verify using this method (for example, there may be a conflict with your web server configuration), use the meta tag method.
* Adding a meta tag: With this method, Google specifies a tag to be added to your domain's home page. Add the tag anywhere in the section of the page and upload it to your domain. Check that the new file has been published, and return to the Manage Your Domains for this domain. Click the "Verify" button.
If verification is successful, you'll be prompted to accept Google's terms of service.
3. Provide domain information.
Once you've accepted the terms of service, Google requests two pieces of information to complete registration:
* Target URL path prefix: This value enables Google to reject all authorization requests ostensibly from your domain that use an incorrect domain or prefix. If you're making an AuthSub request, this URL must be identical to the prefix value of the next parameter used in your authorization requests. For example, if your next values will be something like http://example.com/authsub and/or http://example.com/feed/authsub, your prefix should be http://example.com. If you're using the OAuth interface, this URL must match the value of the oauth_consumer_key parameter.
* Domain description: This optional value should briefly describe the domain you're registering. In the future, this description may be displayed on the Google Access Consent page to provide additional information for your users. You always have the option of changing this description or leaving it blank.
At this point, you have provided all the information required for registration. Click the "Save" button to complete registration.
4. Upload a security certificate.
If your application is using AuthSub or OAuth with the RSA-SHA1 signature method, you need to upload a security certificate.
Note: If you're using OAuth with the HMAC-SHA1 signature method, you do not need to upload a certificate; instead, an OAuth "consumer secret" value is automatically generated when you register your domain.
To create a certificate, generate a public key. The public key must be a 1024-bit RSA key encoded in an X.509 certificate in PEM format. We suggest creating a self-signed certification rather than getting one from a central certificate authority.
If you have multiple sub-domains registered, you can use the same X.509 certificate for all of them.
For more information on creating and using certificates, see these resources:
Generating X.509 Certificates (from IPsec how-to)
X.509 Certificates and Certificate Revocation Lists (from Sun, Java specific but includes good general info)
5. Test your registration status.
Once you've provided the required information and uploaded a security certificate (if desired), use the Manage Your Domains test link to verify that your registration status is accurate. The test link is located on the Manage Your Domains page specific to the domain you're working on. If you've left this site, return to Manage Your Domains and click on the Manage link for the domain you want to test.
The test link essentially makes an AuthSubRequest call using the next URL value you provided for registration. This call prompts a redirect to the Google authorization server's Access Request page. Here you can view what your users are shown when you make an authorization request from your own application. Verify that the message provided is appropriate to your registration status.
To update an existing registration:
1. Go to the Google Manage Your Domains page. Make sure you're using the appropriate Google account.
2. Click on the "Manage" link for the domain you want to update.
3. Make your changes and click Save.
4. If desired, test your registration status using the test link.
http://groups.google.com/group/Google-Accounts-API
The group has been moved to the Google Apps APIs Help Forum. Posts will no longer be accepted here. Please post in the new forum.
At Google, we welcome the development of third-party applications that rely on and communicate with Google services. Many of these services require users to log into their Google Accounts, which means your application needs some way to manage user authentication. The Google Accounts APIs help streamline this task by validating requests for access and issuing authentication tokens. All of the Google Data APIs support these authentication services.
BEFORE YOU POST:
- Please search our documentation for possible answers.
- Search this group! Someone may have already asked the same question before.
- If you're a new member, your post may not appear immediately.
- To report a bug or submit a feature request, use the Public Issue Tracker.
This group is regularly read by various Google employees who will make announcements, answer questions, or solicit feedback.
Enjoy posting, and welcome to the community!
