Autenticazione del bus di servizio con firme di accesso condivisoService Bus authentication with Shared Access Signatures

Le firme di accesso condiviso sono il meccanismo di sicurezza principale per la messaggistica del bus di servizio.Shared Access Signatures (SAS) are the primary security mechanism for Service Bus messaging. Questo articolo illustra le firme di accesso condiviso, il loro funzionamento e come usarle in modo indipendente dalla piattaforma.This article discusses SAS, how they work, and how to use them in a platform-agnostic way.

L'autenticazione con firma di accesso condiviso consente alle applicazioni di eseguire l'autenticazione al bus di servizio usando una chiave di accesso configurata nello spazio dei nomi o nell'entità di messaggistica, ad esempio coda o argomento, a cui sono associati diritti specifici.SAS authentication enables applications to authenticate to Service Bus using an access key configured on the namespace, or on the messaging entity (queue or topic) with which specific rights are associated. È quindi possibile usare questa chiave per generare un token di firma di accesso condiviso di cui possono avvalersi i client per eseguire l'autenticazione al bus di servizio.You can then use this key to generate a SAS token that clients can in turn use to authenticate to Service Bus.

Il supporto per l'autenticazione della firma di accesso condiviso è inclusa in Azure SDK 2.0 e versioni successive.SAS authentication support is included in the Azure SDK version 2.0 and later.

Panoramica di SASOverview of SAS

Le firme di accesso condiviso sono un meccanismo di autenticazione basato su hash sicuri SHA-256 o URI.Shared Access Signatures are an authentication mechanism based on SHA-256 secure hashes or URIs. SAS è un meccanismo estremamente efficace utilizzato da tutti i servizi del bus di servizio.SAS is an extremely powerful mechanism that is used by all Service Bus services. Nell'uso effettivo, SAS presenta due componenti: i criteri di accesso condiviso e una firma di accesso condiviso che viene spesso chiamata token.In actual use, SAS has two components: a shared access policy and a Shared Access Signature (often called a token).

Nel bus di servizio, l'autenticazione della firma di accesso condiviso implica la configurazione di una chiave di crittografia con i relativi diritti in una risorsa del bus di servizio.SAS authentication in Service Bus involves the configuration of a cryptographic key with associated rights on a Service Bus resource. I client richiedono l'accesso alle risorse del bus di servizio presentando un token di firma di accesso condiviso.Clients claim access to Service Bus resources by presenting a SAS token. Questo token è costituito dall'URI della risorsa a cui si accede e da una scadenza firmata con la chiave configurata.This token consists of the resource URI being accessed, and an expiry signed with the configured key.

È possibile configurare le regole di autorizzazione della firma di accesso condiviso in inoltri, code e argomenti del bus di servizio.You can configure Shared Access Signature authorization rules on Service Bus relays, queues, and topics.

L'autenticazione della firma di accesso condiviso usa gli elementi seguenti:SAS authentication uses the following elements:

  • Regola di autorizzazione per l'accesso condiviso: una chiave di crittografia primaria a 256 bit in formato Base 64, una chiave secondaria facoltativa e un nome di chiave e i diritti associati (una raccolta di diritti di tipo Listen, Send o Manage).Shared Access authorization rule: A 256-bit primary cryptographic key in Base64 representation, an optional secondary key, and a key name and associated rights (a collection of Listen, Send, or Manage rights).
  • firma di accesso condiviso : generato usando l'algoritmo HMAC-SHA256 di una stringa di risorsa, costituito dall'URI della risorsa a cui si accede e da una scadenza, con la chiave di crittografia.Shared Access Signature token: Generated using the HMAC-SHA256 of a resource string, consisting of the URI of the resource that is accessed and an expiry, with the cryptographic key. La firma e gli altri elementi descritti nelle sezioni seguenti vengono formattati in una stringa per formare un token di firma di accesso condiviso.The signature and other elements described in the following sections are formatted into a string to form the SAS token.

Criteri di accesso condivisoShared access policy

Un elemento importante da comprendere rispetto alle firme di accesso condiviso è che iniziano con un criterio.An important thing to understand about SAS is that it starts with a policy. Per ogni criterio si stabiliscono tre informazioni: nome, ambito e autorizzazioni.For each policy, you decide on three pieces of information: name, scope, and permissions. Il nome è un nome univoco all'interno dell’ambito.The name is just that; a unique name within that scope. L'ambito è abbastanza semplice: è l'URI della risorsa in questione.The scope is easy enough: it's the URI of the resource in question. Per uno spazio dei nomi del bus di servizio, l'ambito è il nome di dominio completo (FQDN), ad esempio https://<yournamespace>.servicebus.windows.net/.For a Service Bus namespace, the scope is the fully qualified domain name (FQDN), such as https://<yournamespace>.servicebus.windows.net/.

Le autorizzazioni disponibili per un criterio sono in gran parte autoesplicative:The available permissions for a policy are largely self-explanatory:

  • InvioSend
  • AttesaListen
  • GestireManage

Dopo aver creato il criterio, gli vengono assegnate una chiave primaria e una chiave secondaria.After you create the policy, it is assigned a Primary Key and a Secondary Key. Si tratta di chiavi di crittografia complesse.These are cryptographically strong keys. Queste chiavi non possono essere perse perché sono sempre disponibili nel portale di Azure.Don't lose them or leak them - they'll always be available in the Azure portal. È possibile utilizzare una delle chiavi generate ed è possibile rigenerarle in qualsiasi momento.You can use either of the generated keys, and you can regenerate them at any time. Tuttavia, se si rigenera o si modifica la chiave primaria nel criterio, le firme di accesso condiviso create da tale chiave verranno invalidate.However, if you regenerate or change the primary key in the policy, any Shared Access Signatures created from it will be invalidated.

Quando si crea uno spazio dei nomi del bus di servizio, per l'intero spazio dei nomi viene creato automaticamente un criterio con tutte le autorizzazioni denominato RootManageSharedAccessKey.When you create a Service Bus namespace, a policy is automatically created for the entire namespace called RootManageSharedAccessKey, and this policy has all permissions. Non accedere come radice e non usare questo criterio a meno che non esista un motivo molto valido.You don't log on as root, so don't use this policy unless there's a really good reason. È possibile creare criteri aggiuntivi nella scheda Configura per lo spazio dei nomi nel portale.You can create additional policies in the Configure tab for the namespace in the portal. È importante notare che a un singolo livello della struttura ad albero nel bus di servizio (spazio dei nomi, coda e così via) può essere associato un massimo di 12 criteri.It's important to note that a single tree level in Service Bus (namespace, queue, etc.) can only have up to 12 policies attached to it.

Configurazione dell'autenticazione della firma di accesso condivisoConfiguration for Shared Access Signature authentication

È possibile configurare la regola SharedAccessAuthorizationRule in spazi dei nomi, code, argomenti del bus di servizio.You can configure the SharedAccessAuthorizationRule rule on Service Bus namespaces, queues, or topics. La configurazione di una regola SharedAccessAuthorizationRule in una sottoscrizione del bus di servizio non è attualmente supportata, ma è possibile usare le regole configurate in uno spazio dei nomi o in un argomento per proteggere l'accesso alle sottoscrizioni.Configuring a SharedAccessAuthorizationRule on a Service Bus subscription is currently not supported, but you can use rules configured on a namespace or topic to secure access to subscriptions. Per un esempio pratico di questa procedura, vedere l'articolo relativo all' uso dell'autenticazione della firma di accesso condiviso con le sottoscrizioni del bus di servizio .For a working sample that illustrates this procedure, see the Using Shared Access Signature (SAS) authentication with Service Bus Subscriptions sample.

In uno spazio dei nomi, una coda o un argomento del bus di servizio è possibile configurare fino 12 regole di questo tipo.A maximum of 12 such rules can be configured on a Service Bus namespace, queue, or topic. Le regole configurate in uno spazio dei nomi del bus di servizio si applicano a tutte le entità incluse nello spazio dei nomi.Rules that are configured on a Service Bus namespace apply to all entities in that namespace.

SAS

In questa figura le regole di autorizzazione manageRuleNS, sendRuleNS e listenRuleNS si applicano sia alla coda Q1 che all'argomento T1, mentre listenRuleQ e sendRuleQ si applicano solo alla coda Q1 e sendRuleT si applica solo all'argomento T1.In this figure, the manageRuleNS, sendRuleNS, and listenRuleNS authorization rules apply to both queue Q1 and topic T1, while listenRuleQ and sendRuleQ apply only to queue Q1 and sendRuleT applies only to topic T1.

I parametri principali di SharedAccessAuthorizationRule sono i seguenti:The key parameters of a SharedAccessAuthorizationRule are as follows:

ParametroParameter DescrizioneDescription
KeyNameKeyName Stringa che descrive la regola di autorizzazione.A string that describes the authorization rule.
PrimaryKeyPrimaryKey Chiave primaria a 256 bit con codifica Base 64 per la firma e la convalida del token di firma di accesso condiviso.A base64-encoded 256-bit primary key for signing and validating the SAS token.
SecondaryKeySecondaryKey Chiave secondaria a 256 bit con codifica Base 64 per la firma e la convalida del token di firma di accesso condiviso.A base64-encoded 256-bit secondary key for signing and validating the SAS token.
AccessRightsAccessRights Elenco di diritti di accesso concessi dalla regola di autorizzazione.A list of access rights granted by the authorization rule. Questi diritti possono essere qualsiasi raccolta di diritti di ascolto, invio e gestione.These rights can be any collection of Listen, Send, and Manage rights.

Quando viene eseguito il provisioning di uno spazio dei nomi del bus di servizio, per impostazione predefinita viene creata una regola SharedAccessAuthorizationRule, con KeyName impostato su RootManageSharedAccessKey.When a Service Bus namespace is provisioned, a SharedAccessAuthorizationRule, with KeyName set to RootManageSharedAccessKey, is created by default.

Generare una firma di accesso condiviso (token)Generate a Shared Access Signature (token)

Il criterio non è il token di accesso del bus di servizio.The policy itself is not the access token for Service Bus. È l'oggetto da cui viene generato il token di accesso, utilizzando la chiave primaria o secondaria.It is the object from which the access token is generated - using either the primary or secondary key. Qualsiasi client che abbia accesso alle chiavi di firma specificate nella regola di autorizzazione di accesso condiviso può generare il token di firma di accesso condiviso.Any client that has access to the signing keys specified in the shared access authorization rule can generate the SAS token. Il token viene generato creando attentamente una stringa nel formato seguente:The token is generated by carefully crafting a string in the following format:

SharedAccessSignature sig=<signature-string>&se=<expiry>&skn=<keyName>&sr=<URL-encoded-resourceURI>

Dove signature-string è l'hash SHA-256 dell'ambito del token (ambito come descritto nella sezione precedente) con un CRLF accodato e una scadenza (in secondi dal periodo: 00:00:00 UTC l'1 gennaio 1970).Where signature-string is the SHA-256 hash of the scope of the token (scope as described in the previous section) with a CRLF appended and an expiry time (in seconds since the epoch: 00:00:00 UTC on 1 January 1970).

Nota

Per evitare che i token scadano rapidamente è consigliabile codificare il valore della scadenza come almeno un numero intero senza segno a 32 bit o preferibilmente un numero intero lungo a 64 bit.To avoid a short token expiry time, it is recommended that you encode the expiry time value as at least a 32-bit unsigned integer, or preferably a long (64-bit) integer.

L'hash è simile al seguente pseudocodice e restituisce 32 byte.The hash looks similar to the following pseudo code and returns 32 bytes.

SHA-256('https://<yournamespace>.servicebus.windows.net/'+'\n'+ 1438205742)

I valori non hash si trovano nella stringa SharedAccessSignature per cui il destinatario può calcolare l'hash con gli stessi parametri, per essere certo che restituisca lo stesso risultato.The non-hashed values are in the SharedAccessSignature string so that the recipient can compute the hash with the same parameters, to be sure that it returns the same result. L'URI specifica l'ambito e il nome della chiave identifica i criteri da utilizzare per calcolare l'hash.The URI specifies the scope, and the key name identifies the policy to be used to compute the hash. Questo è importante dal punto di vista della sicurezza.This is important from a security standpoint. Se la firma non corrisponde a quella calcolata dal destinatario (bus di servizio), l'accesso viene negato.If the signature doesn't match that which the recipient (Service Bus) calculates, then access is denied. A questo punto si può essere certi che il mittente abbia accesso alla chiave e che disponga dei diritti specificati nei criteri.At this point you can be sure that the sender had access to the key and should be granted the rights specified in the policy.

Si noti che è necessario usare l'URI di risorsa codificato per questa operazione.Note that you should use the encoded resource URI for this operation. L'URI di risorsa è l'URI completo della risorsa del bus di servizio a cui si richiede l'accesso.The resource URI is the full URI of the Service Bus resource to which access is claimed. Ad esempio http://<namespace>.servicebus.windows.net/<entityPath> o sb://<namespace>.servicebus.windows.net/<entityPath>, ovvero http://contoso.servicebus.windows.net/contosoTopics/T1/Subscriptions/S3.For example, http://<namespace>.servicebus.windows.net/<entityPath> or sb://<namespace>.servicebus.windows.net/<entityPath>; that is, http://contoso.servicebus.windows.net/contosoTopics/T1/Subscriptions/S3.

La regola di autorizzazione di accesso condiviso usata per la firma deve essere configurata nell'entità specificata da questo URI o in un elemento padre nella gerarchia.The shared access authorization rule used for signing must be configured on the entity specified by this URI, or by one of its hierarchical parents. Ad esempio http://contoso.servicebus.windows.net/contosoTopics/T1 o http://contoso.servicebus.windows.net nell'esempio precedente.For example, http://contoso.servicebus.windows.net/contosoTopics/T1 or http://contoso.servicebus.windows.net in the previous example.

Un token di firma di accesso condiviso è valido per tutte le risorse nell'elemento <resourceURI> usato in signature-string.A SAS token is valid for all resources under the <resourceURI> used in the signature-string.

L'oggetto KeyName nel token di firma di accesso condiviso fa riferimento all'oggetto keyName della regola di autorizzazione di accesso condiviso usata per generare il token.The KeyName in the SAS token refers to the keyName of the shared access authorization rule used to generate the token.

L'elemento URL-encoded-resourceURI deve corrispondere all'URI usato nella stringa da firmare durante il calcolo della firma.The URL-encoded-resourceURI must be the same as the URI used in the string-to-sign during the computation of the signature. Il valore deve essere codificato in percentuale.It should be percent-encoded.

È consigliabile rigenerare periodicamente le chiavi usate nella regola SharedAccessAuthorizationRule .It is recommended that you periodically regenerate the keys used in the SharedAccessAuthorizationRule object. In genere le applicazioni usano il parametro PrimaryKey per generare un token di firma di accesso condiviso.Applications should generally use the PrimaryKey to generate a SAS token. Quando si rigenerano le chiavi, sostituire SecondaryKey con la chiave primaria precedente e generare una nuova chiave come nuova chiave primaria.When regenerating the keys, you should replace the SecondaryKey with the old primary key, and generate a new key as the new primary key. In questo modo, è possibile continuare a usare i token per l'autorizzazione rilasciati con la chiave primaria precedente e non ancora scaduti.This enables you to continue using tokens for authorization that were issued with the old primary key, and that have not yet expired.

Se una chiave viene compromessa ed è necessario revocare le chiavi, è possibile rigenerare entrambi gli oggetti PrimaryKey e SecondaryKey per una regola SharedAccessAuthorizationRule, sostituendo le chiavi precedenti con quelle nuove.If a key is compromised and you have to revoke the keys, you can regenerate both the PrimaryKey and the SecondaryKey of a SharedAccessAuthorizationRule, replacing them with new keys. Se viene eseguita questa procedura, tutti i token firmati con le chiavi precedenti non sono più validi.This procedure invalidates all tokens signed with the old keys.

Come usare l'autenticazione della firma di accesso condiviso con il bus di servizioHow to use Shared Access Signature authentication with Service Bus

Gli scenari illustrati di seguito includono la configurazione delle regole di autorizzazione, la generazione di token di firma di accesso condiviso e l'autorizzazione dei client.The following scenarios include configuration of authorization rules, generation of SAS tokens, and client authorization.

Per un esempio pratico completo di un'applicazione del bus di servizio che illustra la configurazione e usa l'autorizzazione con firma di accesso condiviso, vedere Autenticazione della firma di accesso condiviso con il bus di servizio.For a full working sample of a Service Bus application that illustrates the configuration and uses SAS authorization, see Shared Access Signature authentication with Service Bus. Un esempio correlato che illustra l'uso delle regole di autorizzazione con firma di accesso condiviso configurate negli spazi dei nomi o negli argomenti per proteggere le sottoscrizioni del bus di servizio è disponibile nella pagina relativa all' uso dell'autenticazione con firma di accesso condiviso con le sottoscrizioni del bus di servizio.A related sample that illustrates the use of SAS authorization rules configured on namespaces or topics to secure Service Bus subscriptions is available here: Using Shared Access Signature (SAS) authentication with Service Bus Subscriptions.

Accesso alle regole di autorizzazione per l'accesso condiviso in uno spazio dei nomiAccess Shared Access Authorization rules on a namespace

Per le operazioni nella radice dello spazio dei nomi del bus di servizio è necessaria l'autenticazione tramite certificati.Operations on the Service Bus namespace root require certificate authentication. È necessario caricare un certificato di gestione per la sottoscrizione di Azure.You must upload a management certificate for your Azure subscription. Per caricare un certificato di gestione, seguire questi passaggi usando il portale di Azure.To upload a management certificate, follow the steps here, using the Azure portal. Per altre informazioni sui certificati di gestione di Azure, vedere la Panoramica sui certificati di Azure.For more information about Azure management certificates, see the Azure certificates overview.

L'endpoint per l'accesso alle regole di autorizzazione per l'accesso condiviso in uno spazio dei nomi del bus di servizio è il seguente:The endpoint for accessing shared access authorization rules on a Service Bus namespace is as follows:

https://management.core.windows.net/{subscriptionId}/services/ServiceBus/namespaces/{namespace}/AuthorizationRules/

Per creare un oggetto SharedAccessAuthorizationRule in uno spazio dei nomi del bus di servizio, eseguire un'operazione POST in questo endpoint con le informazioni sulle regole serializzate come JSON o XML.To create a SharedAccessAuthorizationRule object on a Service Bus namespace, execute a POST operation on this endpoint with the rule information serialized as JSON or XML. Ad esempio:For example:

// Base address for accessing authorization rules on a namespace
string baseAddress = @"https://management.core.windows.net/<subscriptionId>/services/ServiceBus/namespaces/<namespace>/AuthorizationRules/";

// Configure authorization rule with base64-encoded 256-bit key and Send rights
var sendRule = new SharedAccessAuthorizationRule("contosoSendAll",
    SharedAccessAuthorizationRule.GenerateRandomKey(),
    new[] { AccessRights.Send });

// Operations on the Service Bus namespace root require certificate authentication.
WebRequestHandler handler = new WebRequestHandler
{
    ClientCertificateOptions = ClientCertificateOption.Manual
};
// Access the management certificate by subject name
handler.ClientCertificates.Add(GetCertificate(<certificateSN>));

HttpClient httpClient = new HttpClient(handler)
{
    BaseAddress = new Uri(baseAddress)
};
httpClient.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));
httpClient.DefaultRequestHeaders.Add("x-ms-version", "2015-01-01");

// Execute a POST operation on the baseAddress above to create an auth rule
var postResult = httpClient.PostAsJsonAsync("", sendRule).Result;

In modo analogo, usare un'operazione GET sull'endpoint per leggere le regole di autorizzazione configurate nello spazio dei nomi.Similarly, use a GET operation on the endpoint to read the authorization rules configured on the namespace.

Per aggiornare o eliminare una regola di autorizzazione specifica, usare l'endpoint seguente:To update or delete a specific authorization rule, use the following endpoint:

https://management.core.windows.net/{subscriptionId}/services/ServiceBus/namespaces/{namespace}/AuthorizationRules/{KeyName}

Accedere alle regole di autorizzazione per l'accesso condiviso in un'entitàAccess Shared Access Authorization rules on an entity

È possibile accedere a un oggetto Microsoft.ServiceBus.Messaging.SharedAccessAuthorizationRule configurato in una coda o in un argomento del bus di servizio tramite la raccolta AuthorizationRules negli oggetti QueueDescription o TopicDescription corrispondenti.You can access a Microsoft.ServiceBus.Messaging.SharedAccessAuthorizationRule object configured on a Service Bus queue or topic through the AuthorizationRules collection in the corresponding QueueDescription or TopicDescription.

Il codice seguente illustra come aggiungere regole di autorizzazione per una coda.The following code shows how to add authorization rules for a queue.

// Create an instance of NamespaceManager for the operation
NamespaceManager nsm = NamespaceManager.CreateFromConnectionString(
    <connectionString> );
QueueDescription qd = new QueueDescription( <qPath> );

// Create a rule with send rights with keyName as "contosoQSendKey"
// and add it to the queue description.
qd.Authorization.Add(new SharedAccessAuthorizationRule("contosoSendKey",
    SharedAccessAuthorizationRule.GenerateRandomKey(),
    new[] { AccessRights.Send }));

// Create a rule with listen rights with keyName as "contosoQListenKey"
// and add it to the queue description.
qd.Authorization.Add(new SharedAccessAuthorizationRule("contosoQListenKey",
    SharedAccessAuthorizationRule.GenerateRandomKey(),
    new[] { AccessRights.Listen }));

// Create a rule with manage rights with keyName as "contosoQManageKey"
// and add it to the queue description.
// A rule with manage rights must also have send and receive rights.
qd.Authorization.Add(new SharedAccessAuthorizationRule("contosoQManageKey",
    SharedAccessAuthorizationRule.GenerateRandomKey(),
    new[] {AccessRights.Manage, AccessRights.Listen, AccessRights.Send }));

// Create the queue.
nsm.CreateQueue(qd);

Usare l'autorizzazione con firma di accesso condivisoUse Shared Access Signature authorization

Le applicazioni che usano Azure .NET SDK con le librerie .NET del bus di servizio possono usare l'autorizzazione con firma di accesso condiviso nella classe SharedAccessSignatureTokenProvider .Applications using the Azure .NET SDK with the Service Bus .NET libraries can use SAS authorization through the SharedAccessSignatureTokenProvider class. Il codice seguente illustra l'uso del provider di token per inviare messaggi a una coda del bus di servizio.The following code illustrates the use of the token provider to send messages to a Service Bus queue.

Uri runtimeUri = ServiceBusEnvironment.CreateServiceUri("sb",
    <yourServiceNamespace>, string.Empty);
MessagingFactory mf = MessagingFactory.Create(runtimeUri,
    TokenProvider.CreateSharedAccessSignatureTokenProvider(keyName, key));
QueueClient sendClient = mf.CreateQueueClient(qPath);

//Sending hello message to queue.
BrokeredMessage helloMessage = new BrokeredMessage("Hello, Service Bus!");
helloMessage.MessageId = "SAS-Sample-Message";
sendClient.Send(helloMessage);

Le applicazioni possono anche usare la firma di accesso condiviso per l'autenticazione usando una stringa di connessione della firma di accesso condiviso nei metodi che accettano stringhe di connessione.Applications can also use SAS for authentication by using a SAS connection string in methods that accept connection strings.

Si noti che per usare l'autorizzazione con firma di accesso condiviso con gli inoltri del bus di servizio è possibile usare le chiavi della firma di accesso condiviso configurate nello spazio dei nomi del bus di servizio.Note that to use SAS authorization with Service Bus relays, you can use SAS keys configured on the Service Bus namespace. Se si crea in modo esplicito un inoltro per lo spazio dei nomi (NamespaceManager con un oggetto RelayDescription), è possibile impostare le regole della firma di accesso condiviso solo per tale inoltro.If you explicitly create a relay on the namespace (NamespaceManager with a RelayDescription) object, you can set the SAS rules just for that relay. Per usare l'autorizzazione con firma di accesso condiviso con le sottoscrizioni del bus di servizio è possibile usare le chiavi della firma di accesso condiviso configurate in uno spazio dei nomi o in un argomento del bus di servizio.To use SAS authorization with Service Bus subscriptions, you can use SAS keys configured on a Service Bus namespace or on a topic.

Usare la firma di accesso condiviso (a livello HTTP)Use the Shared Access Signature (at HTTP level)

Dopo aver creato firme di accesso condiviso per tutte le entità nel bus di servizio, si è pronti a eseguire una richiesta HTTP POST:Now that you know how to create Shared Access Signatures for any entities in Service Bus, you are ready to perform an HTTP POST:

POST https://<yournamespace>.servicebus.windows.net/<yourentity>/messages
Content-Type: application/json
Authorization: SharedAccessSignature sr=https%3A%2F%2F<yournamespace>.servicebus.windows.net%2F<yourentity>&sig=<yoursignature from code above>&se=1438205742&skn=KeyName
ContentType: application/atom+xml;type=entry;charset=utf-8

Questa procedura funziona per ogni elemento.Remember, this works for everything. È possibile creare una firma di accesso condiviso per una coda, un argomento o una sottoscrizione.You can create SAS for a queue, topic, or subscription.

Se un token SAS viene assegnato a un mittente o ad un client, questi ultimi non dispongono della chiave direttamente e non possono invertire l'hash per ottenerla.If you give a sender or client a SAS token, they don't have the key directly, and they cannot reverse the hash to obtain it. Di conseguenza, è necessario controllare a cosa possono accedere e per quanto tempo.As such, you have control over what they can access, and for how long. Se si modifica la chiave primaria nel criterio, le firme di accesso condiviso create da tale chiave verranno invalidate.An important thing to remember is that if you change the primary key in the policy, any Shared Access Signatures created from it will be invalidated.

Usare la firma di accesso condiviso (a livello AMQP)Use the Shared Access Signature (at AMQP level)

Nella sezione precedente, è stato illustrato come utilizzare il token SAS con una richiesta HTTP POST per l'invio di dati per il Bus di servizio.In the previous section, you saw how to use the SAS token with an HTTP POST request for sending data to the Service Bus. Com'è noto, è possibile accedere al bus di servizio usando il protocollo AMQP (Advanced Message Queuing Protocol), ovvero il protocollo preferito da usare per motivi di prestazioni in molti scenari.As you know, you can access Service Bus using the Advanced Message Queuing Protocol (AMQP) that is the preferred protocol to use for performance reasons, in many scenarios. L'uso del token SAS con AMQP viene descritto nel documento dedicato ad AMQP Claim-Based Security versione 1.0 , in fase di bozza dal 2013 ma attualmente supportato da Azure.The SAS token usage with AMQP is described in the document AMQP Claim-Based Security Version 1.0 that is in working draft since 2013 but well-supported by Azure today.

Prima di iniziare a inviare i dati al bus di servizio, il server di pubblicazione deve inviare il token di firma di accesso condiviso all'interno di un messaggio AMQP a un nodo AMQP ben definito denominato "$cbs". Può essere visualizzato come una coda "speciale" usata dal servizio per acquisire e convalidare tutti i token di firma di accesso condiviso.Before starting to send data to Service Bus, the publisher must send the SAS token inside an AMQP message to a well-defined AMQP node named $cbs (you can see it as a "special" queue used by the service to acquire and validate all the SAS tokens). Il server di pubblicazione deve specificare il campo ReplyTo all'interno del messaggio AMQP. Si tratta del nodo in cui il servizio invia una risposta al server di pubblicazione con il risultato della convalida del token. È un modello di richiesta/risposta semplice tra il server di pubblicazione e il servizio.The publisher must specify the ReplyTo field inside the AMQP message; this is the node in which the service replies to the publisher with the result of the token validation (a simple request/reply pattern between publisher and service). Questo nodo risposta viene creato al momento in quanto "creazione dinamica di nodo remoto" come descritto nella specifica di AMQP 1.0.This reply node is created "on the fly," speaking about "dynamic creation of remote node" as described by the AMQP 1.0 specification. Dopo avere verificato che il token di firma di accesso condiviso è valido, il server di pubblicazione può andare avanti e iniziare a inviare dati al servizio.After checking that the SAS token is valid, the publisher can go forward and start to send data to the service.

La procedura seguente illustra come inviare il token SAS con il protocollo AMQP usando la libreria AMQP.Net Lite .The following steps show how to send the SAS token with AMQP protocol using the AMQP.Net Lite library. È utile se non è possibile usare la versione ufficiale di Service Bus SDK (ad esempio su WinRT, .Net Compact Framework, .Net Micro Framework e Mono) che si sviluppa in C#.This is useful if you can't use the official Service Bus SDK (for example on WinRT, .Net Compact Framework, .Net Micro Framework and Mono) developing in C#. Naturalmente, questa libreria è utile per comprendere il funzionamento della sicurezza basata sulle attestazioni a livello AMQP, dopo aver visto il funzionamento a livello HTTP (con una richiesta HTTP POST e il token SAS inviati all'interno dell'intestazione "Authorization").Of course, this library is useful to help understand how claims-based security works at the AMQP level, as you saw how it works at the HTTP level (with an HTTP POST request and the SAS token sent inside the "Authorization" header). Se non sono necessarie tali informazioni approfondite su AMQP, è possibile usare l'SDK ufficiale del bus di servizio con le applicazioni .Net Framework che eseguiranno l'operazione in modo automatico.If you don't need such deep knowledge about AMQP, you can use the official Service Bus SDK with .Net Framework applications, which will do it for you.

C#C#

/// <summary>
/// Send claim-based security (CBS) token
/// </summary>
/// <param name="shareAccessSignature">Shared access signature (token) to send</param>
private bool PutCbsToken(Connection connection, string sasToken)
{
    bool result = true;
    Session session = new Session(connection);

    string cbsClientAddress = "cbs-client-reply-to";
    var cbsSender = new SenderLink(session, "cbs-sender", "$cbs");
    var cbsReceiver = new ReceiverLink(session, cbsClientAddress, "$cbs");

    // construct the put-token message
    var request = new Message(sasToken);
    request.Properties = new Properties();
    request.Properties.MessageId = Guid.NewGuid().ToString();
    request.Properties.ReplyTo = cbsClientAddress;
    request.ApplicationProperties = new ApplicationProperties();
    request.ApplicationProperties["operation"] = "put-token";
    request.ApplicationProperties["type"] = "servicebus.windows.net:sastoken";
    request.ApplicationProperties["name"] = Fx.Format("amqp://{0}/{1}", sbNamespace, entity);
    cbsSender.Send(request);

    // receive the response
    var response = cbsReceiver.Receive();
    if (response == null || response.Properties == null || response.ApplicationProperties == null)
    {
        result = false;
    }
    else
    {
        int statusCode = (int)response.ApplicationProperties["status-code"];
        if (statusCode != (int)HttpStatusCode.Accepted && statusCode != (int)HttpStatusCode.OK)
        {
            result = false;
        }
    }

    // the sender/receiver may be kept open for refreshing tokens
    cbsSender.Close();
    cbsReceiver.Close();
    session.Close();

    return result;
}

Il metodo PutCbsToken() riceve la connessione, vale a dire l'istanza della classe di connessione AMQP indicata dalla libreria AMQP .NET Lite, che rappresenta la connessione TCP al servizio e il parametro sasToken, ovvero il token di firma di accesso condiviso da inviare.The PutCbsToken() method receives the connection (AMQP connection class instance as provided by the AMQP .NET Lite library) that represents the TCP connection to the service and the sasToken parameter that is the SAS token to send.

Nota

È importante che la connessione venga creata con il meccanismo di autenticazione SASL impostato su EXTERNAL (e non il PLAIN predefinito con nome utente e password usato quando non è necessario inviare il token SAS).It's important that the connection is created with SASL authentication mechanism set to EXTERNAL (and not the default PLAIN with username and password used when you don't need to send the SAS token).

Successivamente, il server di pubblicazione crea due collegamenti AMQP per inviare il token SAS e ricevere la risposta (il risultato di convalida del token) dal servizio.Next, the publisher creates two AMQP links for sending the SAS token and receiving the reply (the token validation result) from the service.

Il messaggio AMQP contiene un insieme di proprietà e altre informazioni rispetto a un semplice messaggio.The AMQP message contains a set of properties, and more information than a simple message. Il token SAS rappresenta il corpo del messaggio (tramite il relativo costruttore).The SAS token is the body of the message (using its constructor). La proprietà "ReplyTo" è impostata sul nome del nodo per la ricezione del risultato di convalida sul collegamento ricevitore (se si desidera modificare il nome, è possibile farlo e verrà creato in modo dinamico dal servizio).The "ReplyTo" property is set to the node name for receiving the validation result on the receiver link (you can change its name if you want, and it will be created dynamically by the service). Le ultime tre proprietà personalizzate/relative all'applicazione vengono usate dal servizio per indicare quale tipologia di operazione è necessario eseguire.The last three application/custom properties are used by the service to indicate what kind of operation it has to execute. Come descritto nella bozza di specifica CBS, devono essere il nome dell'operazione ("put-token"), il tipo di token (in questo caso, "servicebus.windows.net:sastoken") e il "nome" del gruppo di destinatari a cui viene applicato il token (l'intera entità).As described by the CBS draft specification, they must be the operation name ("put-token"), the type of token (in this case, a "servicebus.windows.net:sastoken"), and the "name" of the audience to which the token applies (the entire entity).

Dopo aver inviato il token SAS sul collegamento mittente, il server di pubblicazione deve leggere la risposta sul collegamento ricevitore.After sending the SAS token on the sender link, the publisher must read the reply on the receiver link. La risposta è un semplice messaggio AMQP con una proprietà dell'applicazione denominata "status-code" che può contenere gli stessi valori di un codice di stato HTTP.The reply is a simple AMQP message with an application property named "status-code" that can contain the same values as an HTTP status code.

Diritti necessari per le operazioni del bus di servizioRights required for Service Bus operations

La tabella seguente illustra i diritti di accesso necessari per l'esecuzione di operazioni relative alle risorse del bus di servizio.The following table shows the access rights required for various operations on Service Bus resources.

OperazioneOperation Attestazione necessariaClaim Required Ambito attestazioneClaim Scope
Spazio dei nomiNamespace
Configurare le regole di autorizzazione relative a uno spazio dei nomiConfigure authorization rule on a namespace ManageManage Qualsiasi indirizzo dello spazio dei nomiAny namespace address
Registro di sistema del servizioService Registry
Enumerare i criteri privatiEnumerate Private Policies ManageManage Qualsiasi indirizzo dello spazio dei nomiAny namespace address
Iniziare l'attesa su uno spazio dei nomi del servizioBegin listening on a namespace AttesaListen Qualsiasi indirizzo dello spazio dei nomiAny namespace address
Inviare messaggi a un listener in uno spazio dei nomiSend messages to a listener at a namespace InvioSend Qualsiasi indirizzo dello spazio dei nomiAny namespace address
CodaQueue
Creare una codaCreate a queue ManageManage Qualsiasi indirizzo dello spazio dei nomiAny namespace address
Eliminare una codaDelete a queue ManageManage Qualsiasi indirizzo valido della codaAny valid queue address
Enumerare le codeEnumerate queues ManageManage /$Resources/Queues/$Resources/Queues
Ottenere la descrizione di una codaGet the queue description GestireManage Qualsiasi indirizzo valido della codaAny valid queue address
Configurare le regole di autorizzazione per una codaConfigure authorization rule for a queue ManageManage Qualsiasi indirizzo valido della codaAny valid queue address
Effettuare un invio alla codaSend into to the queue InvioSend Qualsiasi indirizzo valido della codaAny valid queue address
Ricevere messaggi da una codaReceive messages from a queue AttesaListen Qualsiasi indirizzo valido della codaAny valid queue address
Abbandonare o completare messaggi dopo la ricezione del messaggio in modalità PeekLock (blocco di visualizzazione)Abandon or complete messages after receiving the message in peek-lock mode AttesaListen Qualsiasi indirizzo valido della codaAny valid queue address
Rinviare un messaggio per il successivo recuperoDefer a message for later retrieval AttesaListen Qualsiasi indirizzo valido della codaAny valid queue address
Spostare un messaggio nella coda dei messaggi non recapitabiliDeadletter a message AttesaListen Qualsiasi indirizzo valido della codaAny valid queue address
Ottenere lo stato associato a una sessione della coda dei messaggiGet the state associated with a message queue session AttesaListen Qualsiasi indirizzo valido della codaAny valid queue address
Impostare lo stato associato a una sessione della coda dei messaggiSet the state associated with a message queue session AttesaListen Qualsiasi indirizzo valido della codaAny valid queue address
ArgomentoTopic
Creare un argomentoCreate a topic ManageManage Qualsiasi indirizzo dello spazio dei nomiAny namespace address
Eliminare un argomentoDelete a topic ManageManage Qualsiasi indirizzo valido dell'argomentoAny valid topic address
Enumerare gli argomentiEnumerate topics ManageManage /$Resources/Topics/$Resources/Topics
Ottenere la descrizione di un argomentoGet the topic description GestireManage Qualsiasi indirizzo valido dell'argomentoAny valid topic address
Configurare le regole di autorizzazione per un argomentoConfigure authorization rule for a topic ManageManage Qualsiasi indirizzo valido dell'argomentoAny valid topic address
Effettuare un invio all'argomentoSend to the topic InvioSend Qualsiasi indirizzo valido dell'argomentoAny valid topic address
SottoscrizioneSubscription
Creare una sottoscrizioneCreate a subscription ManageManage Qualsiasi indirizzo dello spazio dei nomiAny namespace address
Eliminare una sottoscrizioneDelete subscription ManageManage ../myTopic/Subscriptions/mySubscription../myTopic/Subscriptions/mySubscription
Enumerare le sottoscrizioniEnumerate subscriptions ManageManage ../myTopic/Subscriptions../myTopic/Subscriptions
Ottenere la descrizione di una sottoscrizioneGet subscription description GestireManage ../myTopic/Subscriptions/mySubscription../myTopic/Subscriptions/mySubscription
Abbandonare o completare messaggi dopo la ricezione del messaggio in modalità PeekLock (blocco di visualizzazione)Abandon or complete messages after receiving the message in peek-lock mode AttesaListen ../myTopic/Subscriptions/mySubscription../myTopic/Subscriptions/mySubscription
Rinviare un messaggio per il successivo recuperoDefer a message for later retrieval AttesaListen ../myTopic/Subscriptions/mySubscription../myTopic/Subscriptions/mySubscription
Spostare un messaggio nella coda dei messaggi non recapitabiliDeadletter a message AttesaListen ../myTopic/Subscriptions/mySubscription../myTopic/Subscriptions/mySubscription
Ottenere lo stato associato a una sessione dell'argomentoGet the state associated with a topic session AttesaListen ../myTopic/Subscriptions/mySubscription../myTopic/Subscriptions/mySubscription
Impostare lo stato associato a una sessione dell'argomentoSet the state associated with a topic session AttesaListen ../myTopic/Subscriptions/mySubscription../myTopic/Subscriptions/mySubscription
RegoleRules
Creare una regolaCreate a rule ManageManage ../myTopic/Subscriptions/mySubscription../myTopic/Subscriptions/mySubscription
Eliminare una regolaDelete a rule ManageManage ../myTopic/Subscriptions/mySubscription../myTopic/Subscriptions/mySubscription
Enumerare le regoleEnumerate rules Manage o ListenManage or Listen ../myTopic/Subscriptions/mySubscription/Rules../myTopic/Subscriptions/mySubscription/Rules

Passaggi successiviNext steps

Per altre informazioni sulla messaggistica del bus di servizio, vedere gli argomenti seguenti.To learn more about Service Bus messaging, see the following topics.