English | Site Directory

Account Authentication API

Registration for Web-Based Applications

Developers of web applications using the Authentication Proxy 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 allows users to grant access to their account, 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.

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 using the OAuth interface must be registered with enhanced security. Web applications that opt not to register with Google can still use the AuthSub interface. Transactions take place using a lower level of security. Google does not automatically recognize the calling web application and adds a caution to the Google login page (see example).

Note: If you registered your domain under the old registration system, some services may require that you re-register again using this automated service.

Registering Your Web Application

When registering an application, you have two levels to choose from:

  • Registered: This level requires that you provide some information to Google using the registration process. Registered applications are considered "recognized" by Google, and the Google Access Consent page, which prompts users to either grant or deny access for your application, displays this message: "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." The yellow background, displayed for unregistered applications, is removed.
  • Registered with enhanced security: This level requires that, in addition to providing some information, you file a security certificate with Google. Registered applications with a security certificate on file can use secure tokens. The Google Access Consent page displays this message: "This website is registered with Google to make authorization requests securely. We recommend that you continue the process if you trust the following destination."

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 authentication 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 authentication 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. File a security certificate.

    To make full use of Google's domain registration, you must upload a security certificate. A valid certificate allows you to use Google's OAuth library when communicating with a Google service or use secure tokens with AuthSub. For more information on secure tokens, see Signing AuthSub Requests.

    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 authentication server's Access Request page. Here you can view what your users are shown when you make an authentication 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.