openid.realm: Why you should play close attention to this parameter ?

In this page, we will discuss perhaps the most important aspect of configuring your OpenID library for use with the Google Federated Login API: The choice of value for the openid.realm parameter.

What is a realm?

In OpenID terminology, the realm is the entity that accepts user authentication claims from another party. That is, the realm is your website, if you are employing OpenID technology to accept users of Google Accounts or of any other OpenID provider of authentication services.

When a user attempts to login to your site using their Google Account, you send to Google the information about who you are by adding the name of your site as the value of the openid.realm parameter in the authentication request.

Examples:

• Your own the "example.com" name.
• If your home page address is 'www.example.com' then your natural choice for your realm parameter is openid.realm=http://*.example.com ; an alternative is http://www.example.com
  
• if your home page address is instead 'example.com' then your natural choice for realm parameter is simply openid.realm=http://example.com
  
  
• You own the site "hosted-app.example.com", but not "example.com". The natural choice for your realm parameter is openid.realm=http://hosted-app.example.com

The realm parameter is, simply put, the URL (or URL pattern, if you use '*') most likely to be associated in your users' mind with who you are as a business or app.

Crucial point: The realm parameter is used to ask users if they trust your site

When we prompt users for authorization, we render the realm parameter, eliminating any '*' or 'www', as well as the schema (http/https) aspect. So in the above examples, we would ask the users to authorize, respectively:

• openid.realm='http://*.example.com' rendered as 'example.com'
• openid.realm='http://www.example.com' rendered as 'example.com'
• openid.realm='http://example.com' rendered as 'example.com'
• openid.realm='http://hosted-app.example.com', rendered as 'hosted-app.example.com'

This value is likely displayed in URL bars when users visit your home page.

Crucial point: The realm parameter is used to generate the URL that identifies users to your site.

In OpenID, users are identified by URLs. In the case of Google Accounts users, their URL is a random-looking (but reproducible) function of the user's Google Account AND of the realm URL. 

You should use the OpenID URL to identify when users return to your site. Keep in mind that the same user will receive a different URL when logging in to another site: more precisely, when two requests have different values for the openid.realm parameter, different URL identifiers will be asserted. So choose your realm parameter to be representative of your entire site identity, so that you don't have to ever change it!

Q&A

• Q: Why did you make the OpenID identifier a function of the openid.realm parameter? Why not a global value? Is this compliant with the OpenID spec?
  
• A: Realm-specific URLs are fully compliant with the OpenID 2.0 spec. We have chosen to make the identifiers realm-specific to provide a measure of privacy to our users. For instance, you can create a site that provides services to Google Accounts users, without having to learn their identities at Google.
   
• Q: If I configure my openid.realm parameter this way, will it work with other sites, in addition to Google Accounts?
• A: It should. In the examples above, we talked about "natural choices" because they result in good user experience: The user will be asked to approve authentication to a site she recognizes. It may be that some other providers disallow '*' for security reasons, and in that case, you may want to use 'www' instead.
  
  
• Q: The OpenID spec says that the openid.realm is optional, and that if not provided, Google should use the openid.return_to URL instead. Will that work?
• A: It will work in the sense that the protocol will complete successfully. But if your return_to URL is something like www.example.com/authenticate?style=openid-federated_login, you are asking us to prompt users to approve and trust a specific address at your site, which is not user-friendly. Also, if you omit the openid.realm parameter, you will never be able to change your return_to URL: It will also implicitly change the realm and the URL identifiers of your Google Account users.
  
  
• Q: Should I key my accounts by the URL you send, or by the email address?
• A: By the URL, as required in the OpenID spec. As documented in our API, we only send the email address when the user is prompted. If the user has chosen "allow <your site> to remember me", her future sign-on attempts to your site will be auto-approved (without prompt), and the email will not be sent (this is necessary to prevent email harvesting). Note also that users can change the email address in their Google account. If the user changes her email address we will notify you the next time she logs in by sending the new email address. You can safely associate this new email address to the same account if the received URL identifier is the same.