Migrating ACS Namespaces to Google OpenID Connect

This topic is for owners of Access Control Service (ACS) 2.0 namespaces that currently use Google as an identity provider. ACS provides this capability using Google’s OpenID 2.0 implementation. Google plans to discontinue OpenID 2.0 support by April 20, 2015. ACS namespaces will continue to work with Google’s OpenID 2.0 implementation until June 1, 2015, by which time you must complete migration of these namespaces to use Google’s OpenID Connect implementation or users will no longer be able to sign in to your application with a Google account. Migrating your ACS namespaces to OpenID Connect will not cause application downtime. With one exception (see note below), this migration is possible without changing application code. After migrating your ACS namespaces to use OpenID Connect, you will need to migrate your users’ identifiers in your backend to OpenID Connect identifiers. This migration must be completed by January 1, 2017. It will require code changes in your backend. See the important note below for details about both phases of migration.

Important

Note the following important dates and complete the actions required by each date to ensure that your ACS namespaces that use Google as an identity provider continue to work:

• June 1, 2015 - ACS namespaces will stop working with Google’s OpenID 2.0 implementation. You must complete ACS namespace migration to use Google OpenID Connect by this date. Before this date, you can roll back to OpenID 2.0 if you encounter problems during migration. For namespaces that have not been migrated by this date, users will no longer be able to sign in with a Google account and will be presented with a page that indicates that OpenID 2.0 for Google accounts has gone away. To restore sign-in capability with Google accounts, you will need to migrate the namespace.
  
  In most cases, no application code changes should be required. If you have the “passthrough all claims” rule for Google as an identity provider in a rule group associated with your application, though, you may need to make code changes. This is because, upon migration, a new claim type (Subject) becomes available to ACS from Google, and you might have to make code changes to ensure that your application can handle the presence of the new claim type gracefully. To successfully complete migration, there won’t be any need to process the new claim type in your application.
  
  
• Jan 1, 2017 – Google’s OpenID 2.0 and OpenID Connect implementations use different identifiers to uniquely identify Google users. When you migrate your ACS namespace, ACS makes two identifiers, both the current OpenID 2.0 identifier and the new OpenID Connect identifier, available to your application. You must switch your users’ identifiers in your backend system to OpenID Connect identifiers by this date, and start using only OpenID Connect identifiers going forward. This requires application code changes.
  
  

You can post questions about migration on Stack Overflow and tag them with ‘acs-google’. We will respond as quickly as possible.

For more information about Google’s plans, see their OpenID 2.0 Migration Guide.

Migration Checklist

The following table contains a checklist that summarizes the steps required to migrate your ACS namespace to use Google’s OpenID Connect implementation:

Step	Description	Must be Completed by
1	Create a Google+ application at the Google Developers Console.	June 1, 2015
2	If you have the “passthrough all claims” rule for Google as an identity provider in a rule group associated with your application, test your application to ensure that it is migration-ready; otherwise, this step is optional.	June 1, 2015
3	Use the ACS Management Portal to switch your ACS namespace to use Google’s OpenID Connect implementation by supplying it with your Google+ application’s parameters (Client ID and Client secret). If you encounter problems with your migration, roll back to OpenID 2.0 is possible until June 1, 2015.	June 1, 2015
4	Migrate your users’ identifiers in your backend system from the current Google OpenID 2.0 identifiers to the new Google OpenID Connect identifiers. This requires code changes.	Jan 1, 2017

Migration walkthrough

To migrate your ACS namespace to use Google’s OpenID Connect implementation, complete the following steps:

1. Create a Google+ application

   For detailed instructions on how to do this, see the How to: Create a Google+ application section.

2. Ensure that your application is migration-ready

   If you have the “passthrough all claims” rule for Google as an identity provider in a rule group associated with your application, follow the instructions in the How to: Ensure an ACS application’s migration readiness section to test your application for migration readiness. This is because upon migration a new claim type (Subject) becomes available to ACS from Google.

   Note

   A “passthrough all claims” rule is a rule where Input claim type and Input claim value are set to Any and Output claim type and Output claim value are set to Pass through first input claim type and Pass through input claim value respectively. The rule is listed on the ACS Management Portal as shown below, with the Output Claim column set to Passthrough.

   

   If you have previously generated rules or added rules manually for Google as an identity provider in a rule group associated with your application, you can skip this step. This is because, in these cases, upon migration the new Subject claim type is not sent to the application.

   To learn more about these options, see Rule Groups and Rules.

3. Switch the ACS namespace to use Google’s OpenID Connect implementation

   1. Go to the Microsoft Azure Management Portal, sign in, and click Active Directory. Select the ACS namespace that needs to be migrated and click Manage to launch the ACS Management Portal.

   2. On the ACS Management Portal, click Identity Providers in the tree on the left-hand side or click the Identity Providers link under the Getting Started section. Click Google.

      

   3. In the Edit Google Identity Provider page, check Use OpenID Connect.

      

   4. In the Client ID and Client secret fields (now enabled), copy in the corresponding values from your Google+ application.

      

      Note

      At this point if you click Save, all Google identity provider requests from your ACS namespace will automatically use Google’s OpenID Connect implementation. If you need to roll back, you can uncheck Use OpenID Connect. The Client ID and Client secret stay saved and can be re-used later on.

   5. Click Save.

   6. Try signing in with a Google ID to ensure that the switch to using OpenID Connect was successful. If you have trouble signing in, go back to the Edit Google Identity Provider page and un-check Use OpenID Connect to roll back to OpenID 2.0. After you roll back, check that the Client ID and Secret that you copied from the Google Developer Console are entered correctly for your namespace; for example, check for typos.

4. Migrate your users’ identifiers in your backend system from Open ID 2.0 to OpenID Connect

   You must migrate your users’ identifiers in your backend system from the existing Google Open ID 2.0 identifiers to the new Google OpenID Connect identifiers before Jan 1, 2017. This step requires code changes. For more information, see How to: Migrate your users’ existing Open ID 2.0 identifiers to new OpenID Connect user identifiers

How to: Create a Google+ application

You will need a Google account to perform the following steps; if you don’t have one, you can get one at https://accounts.google.com/SignUp.

1. In a browser window, navigate to the Google Developers Console and sign-in with your Google account credentials.

2. Click Create Project, and enter a Project name and Project ID. Check the Terms of Service checkbox. Then click Create. This registers the application with Google.

   

3. Click APIs & auth on the left pane. And then click Credentials. Under OAuth, click Create new Client ID.Select Web Application and click Configure consent screen. Provide a Product Name and click Save.

   

4. Click APIs & auth on the left pane. And then click APIs. Under Browse APIs, search and find Google+ API. Turn the Status to ON.

   

5. In the Create Client ID dialog, select Web Application as the Application Type.

   In the Authorized Javascript Origins field, specify the fully qualified domain name (FQDN) URL of your namespace, including the leading “HTTPS://” and the trailing port number; for example, https://contoso.accesscontrol.windows.net:443.

   In the Authorized Redirect URIs field, specify a URI which contains the fully qualified domain name (FQDN) URL of your namespace, including the leading “HTTPS://” and the trailing port number, followed by “/v2/openid”; for example, https://contoso.accesscontrol.windows.net:443/v2/openid.

   Click Create Client ID.

   

6. Note down the values of Client ID and Client secret from the Client ID for web application page. You will need them to configure Google’s OpenID Connect implementation on the ACS Management Portal.

   

   Important

   Client Secret is an important security credential. Keep it secret.

How to: Migrate your users’ existing Open ID 2.0 identifiers to new OpenID Connect user identifiers

After you have successfully migrated your ACS namespace to use Google’s OpenID Connect implementation, you have until Jan 1, 2017 (per Google’s OpenID 2.0 Migration Guide) to migrate your users’ identifiers in your backend system from the current OpenID 2.0 identifiers to the new OpenID Connect identifiers.

The following table shows claim types that become available to ACS from Google once the ACS namespace has been migrated to use Google’s OpenID Connect implementation:

Claim Type	URI	Description	Protocol Availability
Name Identifier	https://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier	A unique identifier for the user account, provided by Google. This is the (existing) OpenID 2.0 identifier.	OpenID 2.0, OpenID Connect
Subject	https://schemas.microsoft.com/identity/claims/subject	A unique identifier for the user account, provided by Google. This is the (new) OpenID Connect identifier.	OpenID Connect
Name	https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name	The display name for the user account, provided by Google.	OpenID 2.0, OpenID Connect (see note below)
Email Address	https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	The email address for the user account, provided by Google	OpenID 2.0, OpenID Connect
Identity Provider	https://schemas.microsoft.com/accesscontrolservice/2010/07/claims/IdentityProvider	A claim provided by ACS that tells the relying party application that the user authenticated using the default Google identity provider. The value of this claim is visible in the ACS Management Portal via the Realm field in the Edit Identity Provider page.	OpenID 2.0, OpenID Connect

Note

For a Google user who doesn’t have a (registered) Google+ profile, the value of the Name claim type is the same as the value of the Email address claim type in OpenID Connect.

The Name Identifier and Subject claim types can be used to track and switch existing users’ unique identifiers in your backend by mapping (old) OpenID 2.0 identifiers to (new) OpenID Connect identifiers.

If you have the “passthrough all claims” rule for Google as an identity provider in a rule group associated your application, your application will automatically start receiving the Subject claim type.

If you have previously generated rules or added rules manually for Google as an identity provider in a rule group associated with your application, you will need to add the Subject claim type manually. For more information on how to do this, see Rule Groups and Rules.

For example, if you had previously generated rules for Google as an identity provider in a rule group and then add the new Subject claim type (as shown above), you will see the following.

The application using this rule group will receive the Subject claim type, along with other claim types.

Note

After Jan 1, 2017, when Google discontinues its support for identifier mapping, ACS will populate both the NameIdentifier and Subject claim types with the same OpenID Connect user identifier.

How to: Ensure an ACS application’s migration readiness

With one exception, migrating your ACS namespace to use Google’s OpenID Connect implementation is possible without changing application code. The exception case is if you have the “passthrough all claims” rule for Google as an identity provider in a rule group associated with your application. This is because, in this case, upon migration a new claim type (Subject) is automatically sent to the application.

This section outlines the recommended change and test procedure that you can follow to ensure that every application that will be impacted by migration is ready to handle the new claim type.

For the purposes of this How To, assume that you are the owner of an ACS namespace called ns-contoso and that your application in production is called ProdContosoApp. Also assume that this application uses Google as an identity provider and has “passthrough all claims” rule enabled for Google.

Setup

1. To get started, go to the Microsoft Azure Management Portal, sign in, and then click Active Directory. Select the ACS namespace (ns-contoso), and then click Manage to launch the ACS Management Portal.

2. On the ACS Management Portal, click Relying Party Applications in the tree on the left-hand side or click the Relying Party Applications link under the Getting Started section. Then click on your production application (ProdContosoApp).

3. Note down properties of ProdContosoApp, you will need these later.

   

4. Click Default Rule Group for ProdContosoApp under Rule groups to verify that it has the “passthrough all claims” rule enabled for Google.

   

Step 1: Setup a test instance of your application in your production ACS namespace

Set up a test instance of your application, TestContosoApp, on a different root URI; for example, https://contoso-test.com:7777/. You will have to register it as a Relying Party Application (Relying Party Applications) in the ns-contoso namespace.

1. On the ACS Management Portal, click Relying Party Applications in the tree on the left-hand side or click the Relying Party Applications link under the Getting Started section. Then click Add on the Relying Party Applications page.

2. On the Add Relying Partying Application page, do the following:

   • In Name, type the name of the test application. Here it is TestContosoApp.

   • In Mode, select Enter settings manually.

   • In Realm, type in the test application’s URI. Here it is https://contoso-test.com:7777/.

   • For the purposes of this How to, you can leave Error URL (optional) blank.

   • For the Token format, Token encryption policy, and Token lifetime (secs) properties and the Token Signing Settings section, use the same values that you used for ProdContosoApp.

   • Make sure that you have selected Google as an Identity Provider.

   • Under Rule Groups, select Create new rule group.

   

3. Click Save at the bottom of the page.

Step 2: Create a Rule Group that simulates the format of the ACS token that the application will receive once the namespace has been migrated to use Google’s OpenID Connect implementation

1. On the ACS Management Portal, click Rule Groups in the tree on the left-hand side or click the Rules Group link under the Getting Started section. Then click Add on the Rule Groups page.

2. On the Add Rule Group page, provide a name for the new rule group, say ManualGoogleRuleGroup. Click Save.

   

3. On the Edit Rule Group page, click the Add link.

   

4. In the Add Claim Rule page, make sure that you have the following values in place and click Save. This generates a “passthrough all claims” rule for Google.

   • If section:

     • Identity Provider is Google.

     • Input claim type selection is Any.

     • Input claim value is Any.

   • Then section:

     • Output claim type is Pass through first claim type.

     • Output claim value is Pass through first input claim value.

   • Rule information section:

     • Leave the Description (optional) field blank.

   

5. On the Edit Rule Group page, click the Add link again.

6. On the Add Claim Rule page, make sure that you have the following values in place and click Save. This generates a “static” claim rule for Google that simulates addition of a new claim type, Subject, which is the new user OpenID Connect identifier that Google sends the application upon migration.

   • If section:

     • Identity Provider is Google.

     • Input claim type selection is Any.

     • Input claim value is Any.

   • Then section:

     • Output claim type is Enter type. In the field, type https://schemas.microsoft.com/identity/claims/subject.

     • Output claim value is Enter value. In the field, type 123456.

   • Rule information section:

     • Leave the Description (optional) field blank.

   

7. Click Save on the Edit Rule Group page.

Step 3: Associate the new Rule Group with the test instance of the application

1. On the ACS Management Portal, click Relying Party Applications in the tree on the left-hand side or click the Relying Party Applications link under the Getting Started section. Then click TestContosoApp on the Relying Party Applications page.

2. On the Edit Relying Party page, select ManualGoogleRuleGroup in the Authentication Settings section and click Save.

   

At this point, all Google sign-in requests to your test applications will include the new claim type.

Step 4: Test to ensure that your application can handle the addition of the Subject claim type

Test your application to ensure that it can handle the presence of the new claim type (Subject) gracefully. Normally, a well written application should be robust to new claim types being added to the token. Find and fix any issues. Optionally, you can also follow the How to: Migrate your users’ existing Open ID 2.0 identifiers to new OpenID Connect user identifiers section to do user identifier mapping.

Step 5: Migrate your production environment

Re-build and deploy your production application (ProdContosoApp). Migrate the namespace (ns-contoso) to use Google’s OpenID Connect implementation by following the steps in the Migration walkthrough. Verify that ProdContosoApp works as expected.