ACS Migration Guide

Microsoft

Mar 15, 2019

First published on on May 18, 2018
Previously Service Bus namespaces could contain Queues/Topics, Event Hubs, Relays, or Notification Hubs. You may still be affected by the ACS deprecation if you are using an older namespace. For the scope of the below article, "Service Bus namespaces" includes older, mixed-entity namespaces.

Access Control Service PowerShell has been released and is available here. This provides a direct replacement for the ACS functionality in the classic Azure portal. Throughout this guide, ACS PowerShell examples have been added.

Access Control Service (ACS) is being retired soon (see blog post ). Customers who are using ACS authorized Service Bus namespaces will need to migrate to Shared Access Signature (SAS) authorization prior to November 7, 2018 to protect themselves from unnecessary downtime.

We recommend following the below steps to start your migration to SAS authorization, which will be the supported model going forward.

1. Identify your ACS-Authorized Namespaces

Check to see if you have an ACS buddy namespace provisioned. For a Service Bus namespace typollaktestACS , there will be typollaktestacs-sb ACS buddy namespace provisioned if you are using ACS authorization. You can run the below commands to see if an ACS namespace exists (or batch many together in one script):
PS C:\Users\typollak> nslookup typollaktestacs-sb.accesscontrol.windows.net
....
Non-authoritative answer:
Name: aad-ac-prod-sn1-001.cloudapp.net
Address: 70.37.92.127
Aliases: typollaktestacs-sb.accesscontrol.windows.net
prod-sn1-001.accesscontrol.windows.net

PS C:\Users\typollak> Connect-AcsAccount
Token authenticated successfully
PS C:\Users\typollak> Get-AcsNamespace -SubscriptionID 27150243-299a-426c-ba0b-68dd10cbd7aa

Name ManagementUrl Region State
---- ------------- ------ -----
typollaktestACS-sb https://typollaktestacs-sb.accesscontrol.windows.net USSC Active
If the ACS namespace resolves or the Get-ACSNamespace cmdlet returns values, continue with the below steps.

If nslookup fails with an error like 'Non-existent domain', or if no results are displayed via Get-ACSNamespace, you are not using ACS.

2. Identify if You Are Using ACS in your Application

The presence of an ACS buddy namespace does not necessarily mean that ACS authorization is being used. Even if an ACS buddy namespace is present, SAS authorization can be used. The following are some of the ways to determine if your Service Bus solution is using ACS.

Check your solution code for the following strings
- "SharedSecretIssuer"
- "SharedSecretValue"
- "owner"
- "SharedSecretTokenProvider" class references

Use Fiddler with decryption turned on (or any other network capture tool) to check for traffic to ACS. Look for traffic to <namespace>-sb.accesscontrol.windows.net.

Go to the ACS portal ( https://<namespace>-sb.accesscontrol.windows.net ) and change your keys and see if your solutions fail with ACS errors.

Typical ACS errors have a reference to an error of form 'ACSxxxx' where xxxx represents a specific error code number.

You can use the Disable/Enable-ACSNamespace PowerShell cmdlets to disable/enable your ACS namespace like you would have in the classic Azure portal. This could cause downtime for your service, but is a quick way to see where you rely on ACS. Note: you must include the "-sb" extension.

PS C:\Users\typollak> Disable-AcsNamespace -Name "typollaktestACS-sb"
Name Region
---- ------
typollaktestACS-sb USSC

PS C:\Users\typollak> Enable-AcsNamespace -Name "typollaktestACS-sb"
Name ManagementUrl Region
---- ------------- ------
typollaktestACS-sb https://typollaktestacs-sb.accesscontrol.windows.net USSC

3. Migration Scenarios (from here )

Unchanged Defaults

If you are using the ACS default settings, you can just replace the ACS connection string with the SAS connection string provided in the Azure portal ( https://portal.azure.com ).

Change your ACS connection string:
Endpoint=sb://<namespace>.servicebus.windows.net/; SharedSecretIssuer=owner;SharedSecretValue=[snip]
To your SAS connection string:
Endpoint=sb://<namespace>.servicebus.windows.net/; SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=wG46rtpDCQRGRVnBsTx+eRbYQwkda0slQF1bHy1FBoA=

You can see your connection strings via PowerShell using the Get-AzureRmServiceBusAuthorizationRule cmdlet:
PS C:\Users\typollak> Get-AzureRmServiceBusAuthorizationRule -ResourceGroupName $ResourceGroup -Namespace "typollaktestacs"

Id : /subscriptions/27150243-299a-426c-ba0b-68dd10cbd7aa/resourceGroups/Default-ServiceBus-SouthCentralUS/providers/Microsoft.ServiceBus/namespaces/typollaktestacs/AuthorizationRules/RootManageSharedAccessKey
Type :
Name : RootManageSharedAccessKey
Location :
Tags :
Rights : {Listen, Manage, Send}

Id : /subscriptions/27150243-299a-426c-ba0b-68dd10cbd7aa/resourceGroups/Default-ServiceBus-SouthCentralUS/providers/Microsoft.ServiceBus/namespaces/typollaktestacs/AuthorizationRules/Rule2
Type :
Name : Rule2
Location :
Tags :
Rights : {Manage, Listen, Send}

Id : /subscriptions/27150243-299a-426c-ba0b-68dd10cbd7aa/resourceGroups/Default-ServiceBus-SouthCentralUS/providers/Microsoft.ServiceBus/namespaces/typollaktestacs/AuthorizationRules/Rule3
Type :
Name : Rule3
Location :
Tags :
Rights : {Manage, Listen, Send}
After choosing the key with the specific rights you want, get the key values using Get-AzureRmServiceBusKey :
PS C:\Users\typollak> Get-AzureRmServiceBusKey -ResourceGroupName $ResourceGroup -Namespace "typollaktestacs" -Name "Rule2"
PrimaryConnectionString : Endpoint=sb://typollaktestacs.servicebus.windows.net/;SharedAccessKeyName=Rule2;SharedAccessKey=WYw3Hwu7OTSgiIrbVK2v0V+GSIXJwsGlO0E8b/FegeI=
SecondaryConnectionString : Endpoint=sb://typollaktestacs.servicebus.windows.net/;SharedAccessKeyName=Rule2;SharedAccessKey=YCV+s+JkGUp/5UfKg5lLC/zHl7sFLmXX86AGv01cUUY=
AliasPrimaryConnectionString :
AliasSecondaryConnectionString :
PrimaryKey : WYw3Hwu7OTSgiIrbVK2v0V+GSIXJwsGlO0E8b/FegeI=
SecondaryKey : YCV+s+JkGUp/5UfKg5lLC/zHl7sFLmXX86AGv01cUUY=
KeyName : Rule2

You should also replace all SharedSecretTokenProvider references with a SharedAccessSignatureTokenProvider object, and use the SAS policies/keys from the Azure portal instead of the ACS owner account:

From (ACS):
MessagingFactory mf = MessagingFactory.Create(runtimeUri, TokenProvider.CreateSharedSecretTokenProvider(issuerName, issuerSecret));
Change to (SAS):
MessagingFactory mf = MessagingFactory.Create(runtimeUri, TokenProvider.CreateSharedAccessSignatureTokenProvider(keyName, key));
Simple Rules

If the application uses custom service identities with simple rules, the migration is straightforward in the case where an ACS service identity was created to provide access control on a specific queue. This scenario is often the case in SaaS-style solutions where each queue is used as a bridge to a tenant site or branch office, and the service identity is created for that particular site. In this case, the respective service identity can be migrated to a Shared Access Signature rule, directly on the queue. The service identity name can become the SAS rule name and the service identity key can become the SAS rule key. The rights of the SAS rule are then configured equivalent to the respectively applicable ACS rule for the entity.

You can make this new and additional configuration of SAS in-place on any existing namespace that is federated with ACS, and the migration away from ACS is subsequently performed by using SharedAccessSignatureTokenProvider instead of SharedSecretTokenProvider . The namespace does not need to be unlinked from ACS.

You can assign SAS keys with Manage, Send, or Listen privileges via the Azure portal or the Set-AzureRmServiceBusAuthorizationRule cmdlet.

PS C:\Users\typollak> Set-AzureRmServiceBusAuthorizationRule -ResourceGroupName "Default-ServiceBus-SouthCentralUS" -Namespace "typollaktestacs" -Name "Rule11" -Rights "Listen"

Id : /subscriptions/27150243-299a-426c-ba0b-68dd10cbd7aa/resourceGroups/Default-ServiceBus-SouthCentralUS/providers/Microsoft.ServiceBus/namespaces/typollaktestacs/AuthorizationRules/Rule11
Type :
Name : Rule11
Location :
Tags :
Rights : {Listen}

Relay Specific Guidance

If you are using Relays, you might find something like below in your config file:
<behavior name="sharedSecretClientCredentials">
<transportClientEndpointBehavior>
<tokenProvider>
<sharedSecret issuerName="ISSUER_NAME" issuerSecret="ISSUER_SECRET"/>
</tokenProvider>
</transportClientEndpointBehavior>
</behavior>
Please change this to below, with the appropriate key name/value from your Shared Access Signature Policy in the portal.
<sharedAccessSignature keyName="KEY_NAME" key="KEY_VALUE"/>

Please open a Service Bus support ticket here for urgent needs and immediate support. Additional questions can be sent to ACS-SB@microsoft.com .

FAQ

How do I map my ACS access rules to SAS?

The general circumstances and solutions for this are outlined here .

One caveat is that at any level (namespace/entity), there is a limit of 12 SharedAccessAuthorization rules. If you need more, we recommend using SAS Tokens . We have a sample on how to create a Security Token Service (STS) to issue SAS Tokens to trusted applications. The sample is meant to serve only as a guideline, and can be easily modified for your scenarios.