How to: Migrate from the Azure Access Control Service

Microsoft Azure Access Control Service (ACS), a service of Azure Active Directory (Azure AD), will be retired on November 7, 2018. Applications and services that currently use Access Control must be fully migrated to a different authentication mechanism by then. This article describes recommendations for current customers, as you plan to deprecate your use of Access Control. If you don't currently use Access Control, you don't need to take any action.

Overview

Access Control is a cloud authentication service that offers an easy way to authenticate and authorize users for access to your web applications and services. It allows many features of authentication and authorization to be factored out of your code. Access Control is primarily used by developers and architects of Microsoft .NET clients, ASP.NET web applications, and Windows Communication Foundation (WCF) web services.

Use cases for Access Control can be broken down into three main categories:

• Authenticating to certain Microsoft cloud services, including Azure Service Bus and Dynamics CRM. Client applications obtain tokens from Access Control to authenticate to these services to perform various actions.
• Adding authentication to web applications, both custom and prepackaged (like SharePoint). By using Access Control "passive" authentication, web applications can support sign-in with a Microsoft account (formerly Live ID), and with accounts from Google, Facebook, Yahoo, Azure AD, and Active Directory Federation Services (AD FS).
• Securing custom web services with tokens issued by Access Control. By using "active" authentication, web services can ensure that they allow access only to known clients that have authenticated with Access Control.

Each of these use cases and their recommended migration strategies are discussed in the following sections.

Access Control has the following components:

• A secure token service (STS), which receives authentication requests and issues security tokens in return.
• The Azure classic portal, where you create, delete, and enable and disable Access Control namespaces.
• A separate Access Control management portal, where you customize and configure Access Control namespaces.
• A management service, which you can use to automate the functions of the portals.
• A token transformation rule engine, which you can use to define complex logic to manipulate the output format of tokens that Access Control issues.

To use these components, you must create one or more Access Control namespaces. A namespace is a dedicated instance of Access Control that your applications and services communicate with. A namespace is isolated from all other Access Control customers. Other Access Control customers use their own namespaces. A namespace in Access Control has a dedicated URL that looks like this:

https://<mynamespace>.accesscontrol.windows.net

All communication with the STS and management operations are done at this URL. You use different paths for different purposes. To determine whether your applications or services use Access Control, monitor for any traffic to https://<namespace>.accesscontrol.windows.net. Any traffic to this URL is handled by Access Control, and needs to be discontinued.

The exception to this is any traffic to https://accounts.accesscontrol.windows.net. Traffic to this URL is already handled by a different service and is not affected by the Access Control deprecation.

For more information about Access Control, see Access Control Service 2.0 (archived).

Find out which of your apps will be impacted

Follow the steps in this section to find out which of your apps will be impacted by ACS retirement.

Download and install ACS PowerShell

1. Go to the PowerShell Gallery and download Acs.Namespaces.

2. Install the module by running

   Install-Module -Name Acs.Namespaces
   

3. Get a list of all possible commands by running

   Get-Command -Module Acs.Namespaces
   

   To get help on a specific command, run:

    Get-Help [Command-Name] -Full
   

   where [Command-Name] is the name of the ACS command.

List your ACS namespaces

1. Connect to ACS using the Connect-AcsAccount cmdlet.

   You may need to run Set-ExecutionPolicy -ExecutionPolicy Bypass before you can execute commands and be the admin of those subscriptions in order to execute the commands.

2. List your available Azure subscriptions using the Get-AcsSubscription cmdlet.

3. List your ACS namespaces using the Get-AcsNamespace cmdlet.

Check which applications will be impacted

1. Use the namespace from the previous step and go to https://<namespace>.accesscontrol.windows.net

   For example, if one of the namespaces is contoso-test, go to https://contoso-test.accesscontrol.windows.net

2. Under Trust relationships, select Relying party applications to see the list of apps that will be impacted by ACS retirement.

3. Repeat steps 1-2 for any other ACS namespace(s) that you have.

Retirement schedule

As of November 2017, all Access Control components are fully supported and operational. The only restriction is that you can't create new Access Control namespaces via the Azure classic portal.

Here's the schedule for deprecating Access Control components:

• November 2017: The Azure AD admin experience in the Azure classic portal is retired. At this point, namespace management for Access Control is available at a new, dedicated URL: https://manage.windowsazure.com?restoreClassic=true. Use this URl to view your existing namespaces, enable and disable namespaces, and to delete namespaces, if you choose to.
• April 2, 2018: The Azure classic portal is completely retired, meaning Access Control namespace management is no longer available via any URL. At this point, you can't disable or enable, delete, or enumerate your Access Control namespaces. However, the Access Control management portal will be fully functional and located at https://\<namespace\>.accesscontrol.windows.net. All other components of Access Control continue to operate normally.
• November 7, 2018: All Access Control components are permanently shut down. This includes the Access Control management portal, the management service, STS, and the token transformation rule engine. At this point, any requests sent to Access Control (located at <namespace>.accesscontrol.windows.net) fail. You should have migrated all existing apps and services to other technologies well before this time.

Migration strategies

The following sections describe high-level recommendations for migrating from Access Control to other Microsoft technologies.

Clients of Microsoft cloud services

Each Microsoft cloud service that accepts tokens that are issued by Access Control now supports at least one alternate form of authentication. The correct authentication mechanism varies for each service. We recommend that you refer to the specific documentation for each service for official guidance. For convenience, each set of documentation is provided here:

SharePoint customers

SharePoint 2013, 2016, and SharePoint Online customers have long used ACS for authentication purposes in cloud, on premises, and hybrid scenarios. Some SharePoint features and use cases will be affected by ACS retirement, while others will not. The below table summarizes migration guidance for some of the most popular SharePoint feature that leverage ACS:

Web applications that use passive authentication

For web applications that use Access Control for user authentication, Access Control provides the following features and capabilities to web application developers and architects:

• Deep integration with Windows Identity Foundation (WIF).
• Federation with Google, Facebook, Yahoo, Azure Active Directory, and AD FS accounts, and Microsoft accounts.
• Support for the following authentication protocols: OAuth 2.0 Draft 13, WS-Trust, and Web Services Federation (WS-Federation).
• Support for the following token formats: JSON Web Token (JWT), SAML 1.1, SAML 2.0, and Simple Web Token (SWT).
• A home realm discovery experience, integrated into WIF, that allows users to pick the type of account they use to sign in. This experience is hosted by the web application and is fully customizable.
• Token transformation that allows rich customization of the claims received by the web application from Access Control, including:
  • Pass through claims from identity providers.
  • Adding additional custom claims.
  • Simple if-then logic to issue claims under certain conditions.

Unfortunately, there isn't one service that offers all of these equivalent capabilities. You should evaluate which capabilities of Access Control you need, and then choose between using Azure Active Directory, Azure Active Directory B2C (Azure AD B2C), or another cloud authentication service.

Migrate to Azure Active Directory

A path to consider is integrating your apps and services directly with Azure AD. Azure AD is the cloud-based identity provider for Microsoft work or school accounts. Azure AD is the identity provider for Office 365, Azure, and much more. It provides similar federated authentication capabilities to Access Control, but doesn't support all Access Control features.

The primary example is federation with social identity providers, such as Facebook, Google, and Yahoo. If your users sign in with these types of credentials, Azure AD is not the solution for you.

Azure AD also doesn't necessarily support the exact same authentication protocols as Access Control. For example, although both Access Control and Azure AD support OAuth, there are subtle differences between each implementation. Different implementations require you to modify code as part of a migration.

However, Azure AD does provide several potential advantages to Access Control customers. It natively supports Microsoft work or school accounts hosted in the cloud, which are commonly used by Access Control customers.

An Azure AD tenant can also be federated to one or more instances of on-premises Active Directory via AD FS. This way, your app can authenticate cloud-based users and users that are hosted on-premises. It also supports the WS-Federation protocol, which makes it relatively straightforward to integrate with a web application by using WIF.

The following table compares the features of Access Control that are relevant to web applications with those features that are available in Azure AD.

At a high level, Azure Active Directory is probably the best choice for your migration if you let users sign in only with their Microsoft work or school accounts.

If you decide that Azure AD is the best migration path for your applications and services, you should be aware of two ways to integrate your app with Azure AD.

To use WS-Federation or WIF to integrate with Azure AD, we recommend following the approach described in Configure federated single sign-on for a non-gallery application. The article refers to configuring Azure AD for SAML-based single sign-on, but also works for configuring WS-Federation. Following this approach requires an Azure AD Premium license. This approach has two advantages:

• You get the full flexibility of Azure AD token customization. You can customize the claims that are issued by Azure AD to match the claims that are issued by Access Control. This especially includes the user ID or Name Identifier claim. To continue to receive consistent user IDentifiers for your users after you change technologies, ensure that the user IDs issued by Azure AD match those issued by Access Control.
• You can configure a token-signing certificate that is specific to your application, and with a lifetime that you control.

An alternative approach is to follow this code sample, which gives slightly different instructions for setting up WS-Federation. This code sample does not use WIF, but rather, the ASP.NET 4.5 OWIN middleware. However, the instructions for app registration are valid for apps using WIF, and don't require an Azure AD Premium license.

If you choose this approach, you need to understand signing key rollover in Azure AD. This approach uses the Azure AD global signing key to issue tokens. By default, WIF does not automatically refresh signing keys. When Azure AD rotates its global signing keys, your WIF implementation needs to be prepared to accept the changes. For more information, see Important information about signing key rollover in Azure AD.

If you can integrate with Azure AD via the OpenID Connect or OAuth protocols, we recommend doing so. We have extensive documentation and guidance about how to integrate Azure AD into your web application available in our Azure AD developer guide.

Migrate to Azure Active Directory B2C

The other migration path to consider is Azure AD B2C. Azure AD B2C is a cloud authentication service that, like Access Control, allows developers to outsource their authentication and identity management logic to a cloud service. It's a paid service (with free and premium tiers) that is designed for consumer-facing applications that might have up to millions of active users.

Like Access Control, one of the most attractive features of Azure AD B2C is that it supports many different types of accounts. With Azure AD B2C, you can sign in users by using their Microsoft account, or Facebook, Google, LinkedIn, GitHub, or Yahoo accounts, and more. Azure AD B2C also supports "local accounts," or username and passwords that users create specifically for your application. Azure AD B2C also provides rich extensibility that you can use to customize your sign-in flows.

However, Azure AD B2C doesn't support the breadth of authentication protocols and token formats that Access Control customers might require. You also can't use Azure AD B2C to get tokens and query for additional information about the user from the identity provider, Microsoft or otherwise.

The following table compares the features of Access Control that are relevant to web applications with those that are available in Azure AD B2C. At a high level, Azure AD B2C is probably the right choice for your migration if your application is consumer facing, or if it supports many different types of accounts.

If you decide that Azure AD B2C is the best migration path for your applications and services, begin with the following resources:

• Azure AD B2C documentation
• Azure AD B2C custom policies
• Azure AD B2C pricing

Migrate to Ping Identity or Auth0

In some cases, you might find that Azure AD and Azure AD B2C aren't sufficient to replace Access Control in your web applications without making major code changes. Some common examples might include:

• Web applications that use WIF or WS-Federation for sign-in with social identity providers such as Google or Facebook.
• Web applications that perform direct federation to an enterprise identity provider over the WS-Federation protocol.
• Web applications that require the access token issued by a social identity provider (such as Google or Facebook) as a claim in the tokens issued by Access Control.
• Web applications with complex token transformation rules that Azure AD or Azure AD B2C can't reproduce.
• Multi-tenant web applications that use ACS to centrally manage federation to many different identity providers

In these cases, you might want to consider migrating your web application to another cloud authentication service. We recommend exploring the following options. Each of the following options offer capabilities similar to Access Control:

	Auth0 is a flexible cloud identity service that has created high-level migration guidance for customers of Access Control, and supports nearly every feature that ACS does.
	Ping Identity offers two solutions similar to ACS. PingOne is a cloud identity service that supports many of the same features as ACS, and PingFederate is a similar on premises identity product that offers more flexibility. Refer to Ping's ACS retirement guidance for more details on using these products.

Our aim in working with Ping Identity and Auth0 is to ensure that all Access Control customers have a migration path for their apps and services that minimizes the amount of work required to move from Access Control.

Web services that use active authentication

For web services that are secured with tokens issued by Access Control, Access Control offers the following features and capabilities:

• Ability to register one or more service identities in your Access Control namespace. Service identities can be used to request tokens.
• Support for the OAuth WRAP and OAuth 2.0 Draft 13 protocols for requesting tokens, by using the following types of credentials:
  • A simple password that's created for the service identity
  • A signed SWT by using a symmetric key or X509 certificate
  • A SAML token issued by a trusted identity provider (typically, an AD FS instance)
• Support for the following token formats: JWT, SAML 1.1, SAML 2.0, and SWT.
• Simple token transformation rules.

Service identities in Access Control are typically used to implement server-to-server authentication.

Migrate to Azure Active Directory

Our recommendation for this type of authentication flow is to migrate to Azure Active Directory. Azure AD is the cloud-based identity provider for Microsoft work or school accounts. Azure AD is the identity provider for Office 365, Azure, and much more.

You can also use Azure AD for server-to-server authentication by using the Azure AD implementation of the OAuth client credentials grant. The following table compares the capabilities of Access Control in server-to-server authentication with those that are available in Azure AD.

For guidance about implementing server-to-server scenarios, see the following resources:

• Service-to-Service section of the Azure AD developer guide
• Daemon code sample by using simple password client credentials
• Daemon code sample by using certificate client credentials

Migrate to Ping Identity or Auth0

In some cases, you might find that the Azure AD client credentials and the OAuth grant implementation aren't sufficient to replace Access Control in your architecture without major code changes. Some common examples might include:

• Server-to-server authentication using token formats other than JWTs.
• Server-to-server authentication using an input token provided by an external identity provider.
• Server-to-server authentication with token transformation rules that Azure AD cannot reproduce.

In these cases, you might consider migrating your web application to another cloud authentication service. We recommend exploring the following options. Each of the following options offer capabilities similar to Access Control:

	Auth0 is a flexible cloud identity service that has created high-level migration guidance for customers of Access Control, and supports nearly every feature that ACS does.
	Ping Identity offers two solutions similar to ACS. PingOne is a cloud identity service that supports many of the same features as ACS, and PingFederate is a similar on premises identity product that offers more flexibility. Refer to Ping's ACS retirement guidance for more details on using these products.

Our aim in working with Ping Identity and Auth0 is to ensure that all Access Control customers have a migration path for their apps and services that minimizes the amount of work required to move from Access Control.

Passthrough authentication

For passthrough authentication with arbitrary token transformation, there is no equivalent Microsoft technology to ACS. If that is what your customers need, Auth0 might be the one who provides the closest approximation solution.

Questions, concerns, and feedback

We understand that many Access Control customers won't find a clear migration path after reading this article. You might need some assistance or guidance in determining the right plan. If you would like to discuss your migration scenarios and questions, please leave a comment on this page.