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.
-
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.
I don't use C#, what are my options?
-
All of our libraries support SAS. Note the links below might reference old libraries. Any new libraries will support SAS.