This topic has not yet been rated - Rate this topic

Guidelines for Migrating an ACS 1.0 Namespace to an ACS 2.0 Namespace

Updated: December 9, 2011

Applies To

Windows Azure Access Control Service (ACS) 1.0 and ACS 2.0

Overview

This document provides guidance for upgrading an ACS 1.0 namespace to an ACS 2.0 namespace.

The April 2011 release of ACS 2.0 represented a major update of the existing ACS 1.0 service, and enabled support for many new web application, web service, and mobile device scenarios. This release contained some breaking changes from ACS 1.0 (released in December 2009), and as a result the existing ACS 1.0 namespaces were not automatically migrated to the latest version. The breaking changes between ACS 1.0 and 2.0 are described in Changes Required For ACS 2.0.

The ACS 1.0 Migration Tool enables customers with existing ACS 1.0 namespaces to migrate them to ACS 2.0 namespaces. This tool allows ACS 1.0 namespace owners to do the following:

Copy the data from an ACS 1.0 namespace to a different ACS 2.0 namespace. This enables inspection and testing of the migrated settings on a different ACS 2.0 namespace without affecting the original ACS 1.0 namespace or applications that rely on it.
Migrate the DNS name from the original ACS 1.0 namespace to the new ACS 2.0 namespace with no Secure Token Service (STS) downtime, after any optional testing and verification has completed.

This guide describes how to use the ACS 1.0 Migration Tool, and how ACS 1.0 namespace settings are transformed into ACS 2.0 namespace settings.

Prerequisites

To migrate ACS 1.0 namespaces to ACS 2.0 you must use the ACS 1.0 Migration Tool. This tool is a Windows command line application, and can be downloaded at the following URL: http://go.microsoft.com/fwlink/?LinkID=228405.

To migrate an ACS 1.0 namespace to an ACS 2.0 namespace using the ACS 1.0 Migration Tool, you must meet the following system requirements:

A client machine running one of the following operating systems: Windows 7, Windows Vista SP1, Windows XP SP3, Windows Server 2008 R2, Windows Server 2008, or Windows Server 2003 SP2.
.NET Framework 4.0. For the Microsoft .NET Framework 4 web installer package, see http://go.microsoft.com/fwlink/?LinkID=228185.

Using the ACS 1.0 Migration Tool

You can use the ACS 1.0 Migration Tool to migrate regular ACS 1.0 namespaces as well as ACS 1.0 namespaces that are used by Windows Azure Service Bus. Your usage of the tool depends on which one of these use cases applies to you. For instructions on how to use the ACS 1.0 Migration Tool, see one of the following:

ACS 1.0 Migration Reference

This section describes how the ACS 1.0 Migration Tool transforms ACS 1.0 resources into ACS 2.0 resources. It also describes code changes that you can make to your solution in order for it to be compatible with ACS 2.0, and provides a reference for all errors that can be produced by the ACS 1.0 Migration Tool. This information is applicable to all use cases for the migration tool.

Transformation of ACS 1.0 Resources

When using the ACS 1.0 Migration Tool to copy data between an ACS 1.0 namespace and an ACS 2.0 namespace, the tool transforms ACS 1.0 resources into equivalent ACS 2.0 resources. The table below describes how these settings are transformed.

ACS 1.0 Resource	ACS 2.0 Resource	Notes
Scope	Relying Party Application	An ACS 1.0 scope is converted into an ACS 2.0 relying party application, and URIs are stored as Relying Party Addresses when used via the ACS Management Service.
Issuer	Service Identity, Issuer	If the ACS 1.0 Migration Tool determines through rule analysis that an ACS 1.0 Issuer is used to assert claims, then it creates both an ACS 2.0 Service Identity and an ACS 2.0 Issuer with that name. The additional ACS 2.0 Issuer record allows rules for that issuer to be created in the ACS 2.0 rules engine. If this conversion occurs, the migration tool outputs a warning: "Issuer <name> referenced by Non-Issuer Rules, therefore it has been converted to a Service Identity and a corresponding Issuer has been created". If the ACS 1.0 Migration Tool determines through rule analysis that an issuer is not used to assert claims, then only an ACS 2.0 Service Identity is created.
Ruleset	Rule Group
Rule	Rule
Token Policy	Relying Party Keys	Signing keys are created as relying party signing keys, but the token lifetime is added as a property of the relying party application. These keys are represented as RelyingPartyKey entities in the ACS Management Service, and can be viewed as part of relying party applications in the Relying Party Applications section of the ACS Management Portal.

After a data copy operation has completed, the ACS 2.0 resources above are visible through the ACS 2.0 Management Portal and the ACS 2.0 Management Service.

Changes Required for ACS 2.0

To test the new ACS 2.0 namespace without affecting your production service, you can create a staging version of your application. To work with the new ACS 2.0 namespace, there are several changes that must be made to your code.

Token Response Changes

In order for your staging application to accept tokens from the new ACS 2.0 namespace, you must update your code with the Issuer name of the new ACS 2.0 namespace. Also, there are two differences in the OAuth WRAP token responses issued by ACS 2.0 as opposed to those issued by ACS 1.0. These changes may or may not be benign depending on your code:

A trailing forward-slash is always appended to the end of the Audience parameter in OAuth WRAP token responses issued by ACS 2.0.
An IdentityProvider claim type is always present in the token issued by ACS 2.0 to be returned to a relying party application. This claim type indicates the identity provider that signed the incoming token used in the request.

The following is an example of a SWT token issued by ACS 2.0. Note that the IdentityProvider claim type uses a URI for compatibility with other token formats supported by ACS (e.g. SAML):

Copy

Role=Administrator& 
Action=Write& http://schemas.microsoft.com/accesscontrolservice/2010/07/claims/IdentityProvider=MyIdentityProvider& 
Audience= http://mysnservice.com/& ExpiresOn=1302284966& 
Issuer=https://your-namespace.accesscontrol.windows.net/& HMACSHA256=X...DGzVepvditIP33IIq753JCz99ENY=

Note
If you have a Silverlight client that requests token from ACS 1.0 , ensure that the URL to the ACS endpoint in you code is written in this exact format, where “<namespace-url>” is replaced with the fully qualified domain name of your ACS namespace (e.g. mynamespace.accesscontrol.windows.net): `https://<namespace-url>/WRAPv0.9` Otherwise, your client may break on a Silverlight security exception. For Silverlight clients, ACS 2.0 emits a client access policy XML file with very specific URL restrictions under an ACS hostname that a Silverlight client can access. The client access policy in ACS 2.0 defines the allowed path as “`/WRAPv0.9`” and Silverlight security runtime compares the paths in a case-sensitive way. If your Silverlight client accesses a path that does not match `https://<namespace-url>/WRAPv0.9` precisely, your client will break on a Silverlight security exception.

Note

If you have a Silverlight client that requests token from ACS 1.0 , ensure that the URL to the ACS endpoint in you code is written in this exact format, where “<namespace-url>” is replaced with the fully qualified domain name of your ACS namespace (e.g. mynamespace.accesscontrol.windows.net):

https://<namespace-url>/WRAPv0.9

Otherwise, your client may break on a Silverlight security exception. For Silverlight clients, ACS 2.0 emits a client access policy XML file with very specific URL restrictions under an ACS hostname that a Silverlight client can access. The client access policy in ACS 2.0 defines the allowed path as “/WRAPv0.9” and Silverlight security runtime compares the paths in a case-sensitive way. If your Silverlight client accesses a path that does not match https://<namespace-url>/WRAPv0.9 precisely, your client will break on a Silverlight security exception.

Management Service Changes

The ACS Management Service has been completely overhauled from 1.0 and now, in ACS 2.0, uses the OData protocol to enable the management of the ACS settings. The ACM.exe tool used in ACS 1.0 is not compatible with and is not supported for ACS 2.0.

If your existing application code programmatically makes calls to the ACS 1.0 Management Service, then you must modify your code to work with the new ACS 2.0 Management Service. For more information on the ACS 2.0 Management Service including code samples, see ACS Management Service.

Certificates

Certificate validation is more strict in ACS 2.0, and token requests using a SAML token only work if the following conditions are true:

A Certificate must not be expired
A certificate must either be self-signed, or be issued by a public certificate authority

To ensure that no expired certificates are copied to the ACS namespace

In the ACS Management Portal, navigate to Administration > Service Identities.
Select a service identity (known as the Issuer in ACS 1.0) that has an associated X.509 certificate.
In the Credentials list, ensure that all credentials of type X.509 Certificate show a Valid status.
- If a certificate is expired, click on the X.509 certificate entry and update it with a non-expired certificate.

Error Code Changes

The error codes returned by the OAuth WRAP endpoint have changed in ACS 2.0. If you have code that takes a dependency on any specific ACS 1.0 error codes, this code must be updated for ACS 2.0. For a complete list of ACS 2.0 error codes, see ACS Error Codes.

Error Reference

This section provides tips for troubleshooting the migration of your ACS 1.0 namespaces to ACS 2.0 namespaces.

Data Copy Errors

Error Message	Action
The tool version could not be verified. Please download the latest version.	Download the latest version of the ACS 1.0 Migration Tool at http://go.microsoft.com/fwlink/?LinkID=228405.
Unable to read <item> from the ACS 1.0 namespace	A network error may have occurred during the data copy. Try to copy the data again.
Access to ACS <version> is unauthorized. Either the namespace does not exist or the management key is incorrect	Verify that the name of the namespace and the management key are correct, as described in “Copying Data to ACS 2.0” section of How To: Migrate an ACS 1.0 Namespace to an ACS 2.0 Namespace or How To: Migrate an ACS 1.0 Namespace Used by the Windows Azure Service Bus to an ACS 2.0 Namespace.
ACS namespace cannot be reached	Verify that the name of the namespace is correct and that your client can connect to the Internet.
Cannot copy resources between Service Bus and non-Service Bus namespaces	Namespaces that are managed by the Windows Azure Service Bus (e.g. contoso-sb) cannot be copied to regular ACS namespaces, and vice versa. For more information, see How To: Migrate an ACS 1.0 Namespace Used by the Windows Azure Service Bus to an ACS 2.0 Namespace.
Issuer missing for Rule	The ACS 1.0 Migration Tool detected a misconfigured rule. Verify that your solution works as expected.
Token Policy missing for Scope	The ACS 1.0 Migration Tool detected a misconfigured scope. Verify that your solution works as expected.
Cannot copy intermediate NameId Rule	This is the only case where an ACS 1.0 namespace cannot be migrated to an ACS 2.0 namespace. The reason is that ACS 2.0 generates a “nameidentifier” (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier) claim which causes this ACS 1.0 rule to return true if it exists. As this can create a security issue in your application, the ACS 1.0 to ACS 2.0 migration is rejected if a rule with ACS as the Issuer and nameidentifier as the inout claim type exists. Modify your ACS 1.0 configuration to not rely on this rule.
Internal error	An unknown error occurred. Verify that the names of your ACS 1.0 and ACS 2.0 namespaces are correct and operational, the management keys are correct, and try the data copy operation again. If the issue persists, install the .NET Framework 4.0 (http://go.microsoft.com/fwlink/?LinkID=237469) on a different client machine and try running the ACS 1.0 Migration Tool on that machine.

DNS Migration Errors

The table below describes errors that can occur during the DNS name migration.

Error Message	Action
Invalid ACS <version> namespace	Verify that the name of the namespace is correct, as described in the “Copying Data to ACS 2.0” section of How To: Migrate an ACS 1.0 Namespace to an ACS 2.0 Namespace or How To: Migrate an ACS 1.0 Namespace Used by the Windows Azure Service Bus to an ACS 2.0 Namespace.
Invalid ACS <version> management key	Verify that the management key for the namespace is correct, as described in the “Copying Data to ACS 2.0” section of How To: Migrate an ACS 1.0 Namespace to an ACS 2.0 Namespace or How To: Migrate an ACS 1.0 Namespace Used by the Windows Azure Service Bus to an ACS 2.0 Namespace.
ACS namespace cannot be reached	Verify that the name of the namespace is correct and that your client can connect to the Internet.
Cannot copy resources between Service Bus and non-Service Bus namespaces	Namespaces that are managed by Windows Azure Service Bus (e.g. contoso-sb) cannot be copied to regular ACS namespaces, and vice versa. For more information, see How To: Migrate an ACS 1.0 Namespace Used by the Windows Azure Service Bus to an ACS 2.0 Namespace.
The specified namespaces must be located on the same Azure scale unit in the same data center	Using the Windows Azure Management Portal, verify that the ACS 1.0 and ACS 2.0 namespaces are located in the same region (for example, North United States).
The specified namespaces must belong to the same Azure subscription	Verify that both ACS 1.0 and ACS 2.0 namespaces are owned by the same Windows Azure subscriber.
Access to ACS is unauthorized. Either the namespace does not exist or the management key is incorrect	Verify that the name of the namespace and the management key are correct, as described in the “Copying Data to ACS 2.0” section of How To: Migrate an ACS 1.0 Namespace to an ACS 2.0 Namespace or How To: Migrate an ACS 1.0 Namespace Used by the Windows Azure Service Bus to an ACS 2.0 Namespace.
Internal Error	An unknown error occurred. Verify that the names of your ACS 1.0 and ACS 2.0 namespaces are correct and operational, the management keys are correct, and try the DNS migration operation again.