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 <URL of the requesting application>."
• 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 <the requesting application>, 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.