Controllo degli accessi del bus di servizio con firme di accesso condivisoService Bus access control 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.

La firma di accesso condiviso consente inoltre l'accesso al bus di servizio in base alle regole di autorizzazioneSAS guards access to Service Bus based on authorization rules. configurate in uno spazio dei nomi o in un'entità di messaggistica (inoltro, coda o argomento).Those are configured either on a namespace, or a messaging entity (relay, queue, or topic). Una regola di autorizzazione ha un nome, è associata a diritti specifici e include una coppia di chiavi di crittografia.An authorization rule has a name, is associated with specific rights, and carries a pair of cryptographic keys. Usare il nome e la chiave della regola tramite l'SDK del bus di servizio o nel proprio codice per generare un token di firma di accesso condiviso.You use the rule's name and key via the Service Bus SDK or in your own code to generate a SAS token. Un client può quindi passare il token al bus di servizio per dimostrare l'autorizzazione per l'operazione richiesta.A client can then pass the token to Service Bus to prove authorization for the requested operation.

Panoramica di SASOverview of SAS

Le firme di accesso condiviso (SAS) sono un meccanismo di autorizzazione basato sulle attestazioni che usa token semplici.Shared Access Signatures are a claims-based authorization mechanism using simple tokens. Quando si usano le firme di accesso, le chiavi non vengono mai passate durante il transito.Using SAS, keys are never passed on the wire. Le chiavi vengono usate per firmare crittograficamente informazioni che possono essere verificate in un secondo momento dal servizio.Keys are used to cryptographically sign information that can later be verified by the service. L'uso delle firme di accesso condiviso è paragonabile a quello della combinazione di nome utente e password in cui il client entra immediatamente in possesso di un nome di regola di autorizzazione e una chiave corrispondente.SAS can be used similar to a username and password scheme where the client is in immediate possession of an authorization rule name and a matching key. È paragonabile anche a un modello di sicurezza federata, in cui il client riceve un token di accesso firmato per un tempo limitato da un servizio token di sicurezza senza mai entrare in possesso della chiave di firma.SAS can also be used similar to a federated security model, where the client receives a time-limited and signed access token from a security token service without ever coming into possession of the signing key.

L'autenticazione SAS nel bus di servizio è configurata con il nome Regole di autorizzazione di accesso condiviso e a essa sono associati diritti di accesso e una coppia di chiavi di crittografia primaria e secondaria.SAS authentication in Service Bus is configured with named Shared Access Authorization Rules having associated access rights, and a pair of primary and secondary cryptographic keys. Le chiavi sono valori a 256 bit nella rappresentazione Base64.The keys are 256-bit values in Base64 representation. È possibile configurare le regole a livello di spazio dei nomi nel bus di servizio inoltri, code e argomenti.You can configure rules at the namespace level, on Service Bus relays, queues, and topics.

Il token Firma di accesso condiviso include il nome della regola di autorizzazione scelta, l'URI della risorsa alla quale si avrà accesso, un'istante di scadenza e una firma crittografica HMAC-SHA256 calcolata in base a questi campi mediante la chiave crittografica primaria o secondaria della regola di autorizzazione scelta.The Shared Access Signature token contains the name of the chosen authorization rule, the URI of the resource that shall be accessed, an expiry instant, and an HMAC-SHA256 cryptographic signature computed over these fields using either the primary or the secondary cryptographic key of the chosen authorization rule.

Criteri di autorizzazione dell'accesso condivisoShared Access Authorization Policies

Ogni spazio dei nomi e ogni entità del bus di servizio prevede un criterio di autorizzazione dell'accesso condiviso costituito da regole.Each Service Bus namespace and each Service Bus entity has a Shared Access Authorization policy made up of rules. I criteri a livello di spazio dei nomi si applicano a tutte le entità in esso incluse, indipendentemente dalle specifiche configurazioni dei criteri.The policy at the namespace level applies to all entities inside the namespace, irrespective of their individual policy configuration.

Per ogni regola del criterio di autorizzazione si stabiliscono tre informazioni: nome, ambito e diritti.For each authorization policy rule, you decide on three pieces of information: name, scope, and rights. 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/.

I diritti assegnati dalla regola del criterio possono essere una combinazione di:The rights conferred by the policy rule can be a combination of:

  • "Send": conferisce il diritto di inviare messaggi all'entità'Send' - Confers the right to send messages to the entity
  • "Listen": conferisce il diritto di ascolto (inoltro) o di ricezione (coda, sottoscrizioni) e di tutta la gestione correlata ai messaggi'Listen' - Confers the right to listen (relay) or receive (queue, subscriptions) and all related message handling
  • "Manage": conferisce il diritto di gestire la topologia dello spazio dei nomi, incluse la creazione e l'eliminazione di entità'Manage' - Confers the right to manage the topology of the namespace, including creating and deleting entities

Il diritto "Manage" include i diritti "Send" e "Receive".The 'Manage' right includes the 'Send' and 'Receive' rights.

Un criterio di entità o dello spazio dei nomi può contenere fino a 12 regole di autorizzazione di accesso condiviso, rendendo disponibile spazio per tre set di regole, ognuno dei quali copre i diritti di base e la combinazione di Send e Listen.A namespace or entity policy can hold up to 12 Shared Access Authorization rules, providing room for three sets of rules, each covering the basic rights and the combination of Send and Listen. Questo limite sottolinea che l'archivio dei criteri di firma di accesso condiviso non deve essere un utente o un archivio di account del servizio.This limit underlines that the SAS policy store is not intended to be a user or service account store. Se l'applicazione deve concedere l'accesso al bus di servizio in base alle identità utente o del servizio, deve implementare un servizio token di sicurezza che rilascia token di firma di accesso condiviso dopo un controllo di autenticazione e accesso.If your application needs to grant access to Service Bus based on user or service identities, it should implement a security token service that issues SAS tokens after an authentication and access check.

A una regola di autorizzazione vengono assegnate una chiave primaria e una chiave secondaria.An authorization rule 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. Se si rigenera o si modifica una chiave nel criterio, tutti i token emessi in precedenza in base a tale chiave diventano immediatamente non validi.If you regenerate or change a key in the policy, all previously issued tokens based on that key become instantly invalid. Le connessioni in corso create in base a tali token continueranno invece a funzionare fino alla scadenza del token.However, ongoing connections created based on such tokens will continue to work until the token expires.

Quando si crea uno spazio dei nomi del bus di servizio, viene creato automaticamente un criterio denominato RootManageSharedAccessKey.When you create a Service Bus namespace, a policy rule named RootManageSharedAccessKey is automatically created for the namespace. Questo criterio dispone delle autorizzazioni Manage per l'intero spazio dei nomi.This policy has Manage permissions for the entire namespace. È consigliabile considerare questa regola come un account radice amministratore e non usarla nell'applicazione.It's recommended that you treat this rule like an administrative root account and don't use it in your application. È possibile creare regole aggiuntive dei criteri nella scheda Configura per lo spazio dei nomi nel portale mediante Powershell o l'interfaccia della riga di comando di Azure.You can create additional policy rules in the Configure tab for the namespace in the portal, via Powershell or Azure CLI.

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.

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.

Generare un token della firma di accesso condivisoGenerate a Shared Access Signature token

Qualsiasi client che abbia accesso al nome di una regola di autorizzazione e a una delle relative chiavi di firma può generare un token di firma di accesso condiviso.Any client that has access to name of an authorization rule name and one of its signing keys can generate a SAS token. Il token viene generato creando una stringa nel formato seguente:The token is generated by crafting a string in the following format:

SharedAccessSignature sig=<signature-string>&se=<expiry>&skn=<keyName>&sr=<URL-encoded-resourceURI>
  • se: istante di scadenza del token.se - Token expiry instant. Valore intero che riflette i secondi trascorsi dalle 00:00:00 UTC del 1 ° gennaio 1970 (epoca UNIX) quando il token scade.Integer reflecting seconds since the epoch 00:00:00 UTC on 1 January 1970 (UNIX epoch) when the token expires.
  • skn: nome della regola di autorizzazione.skn - Name of the authorization rule.
  • sr: URI della risorsa a cui si ha accesso.sr - URI of the resource being accessed.
  • sig: firma.sig - Signature.

signature-string è il codice hash SHA-256 calcolato in base all'URI della risorsa (l'ambito descritto nella sezione precedente) e la rappresentazione di stringa dell'istante di scadenza del token, separati da CRLF.The signature-string is the SHA-256 hash computed over the resource URI (scope as described in the previous section) and the string representation of the token expiry instant, separated by CRLF.

Il calcolo del codice hash è simile allo pseudo codice seguente e restituisce un valore hash a 256 bit o 32 byte.The hash computation looks similar to the following pseudo code and returns a 256-bit/32-byte hash value.

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

Il token contiene i valori non hash in modo che il destinatario possa ricalcolare il codice hash con gli stessi parametri, verificando che l'autorità di certificazione sia in possesso di una chiave di firma valida.The token contains the non-hashed values so that the recipient can recompute the hash with the same parameters, verifying that the issuer is in possession of a valid signing key.

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. L'URI deve essere codificato in percentuale.The URI must be percent-encoded.

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 precedute dal prefisso <resourceURI> usato in signature-string.A SAS token is valid for all resources prefixed with the <resourceURI> used in the signature-string.

Rigenerazione delle chiaviRegenerating keys

È consigliabile rigenerare periodicamente le chiavi usate nella regola SharedAccessAuthorizationRule .It is recommended that you periodically regenerate the keys used in the SharedAccessAuthorizationRule object. La presenza degli slot di chiave primaria e secondaria cha lo scopo di consentire di ruotare le chiavi gradualmente.The primary and secondary key slots exist so that you can rotate keys gradually. Se l'applicazione usa in genere la chiave primaria, è possibile copiare la chiave primaria nello slot della chiave secondaria e solo allora rigenerare la chiave primaria.If your application generally uses the primary key, you can copy the primary key into the secondary key slot, and only then regenerate the primary key. Il nuovo valore di chiave primaria può essere quindi configurato nelle applicazioni client, che possono accedere in modo continuativo usando la chiave primaria precedente nello slot secondario.The new primary key value can then be configured into the client applications, which have continued access using the old primary key in the secondary slot. Dopo che tutti i client sono stati aggiornati, è possibile rigenerare la chiave secondaria per ritirare infine la chiave primaria precedente.Once all clients are updated, you can regenerate the secondary key to finally retire the old primary key.

Se è noto o si sospetta che una chiave è 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 you know or suspect that 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.

Autenticazione della firma di accesso condiviso con il bus di servizioShared 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 scenarios described as follows 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.

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

Con le librerie .NET Framework del bus di servizio è 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.With Service Bus .NET Framework libraries, 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. In alternativa all'uso qui illustrato, è possibile anche passare un token emesso in precedenza al metodo factory del provider di token.Alternative to the usage shown here, you can also pass a previously issued token to the token provider factory method.

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);

È anche possibile utilizzare direttamente il provider di token per il rilascio di token da passare ad altri client.You can also use the token provider directly for issuing tokens to pass to other clients.

Le stringhe di connessione possono includere un nome di regola (SharedAccessKeyName) e una chiave di regola (SharedAccessKey) o un token rilasciato in precedenza (SharedAccessSignature).Connection strings can include a rule name (SharedAccessKeyName) and rule key (SharedAccessKey) or a previously issued token (SharedAccessSignature). Quando sono presenti nella stringa di connessione passata a un costruttore o a un metodo factory che accetta una stringa di connessione, il provider di token di firma di accesso condiviso viene automaticamente creato e popolato.When those are present in the connection string passed to any constructor or factory method accepting a connection string, the SAS token provider is automatically created and populated.

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. È importante tenere presente che, 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 are 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 ANONYMOUS (e non sul valore predefinito PLAIN 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 ANONYMOUS (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 GestisciManage Qualsiasi indirizzo dello spazio dei nomiAny namespace address
Registro di sistema del servizioService Registry
Enumerare i criteri privatiEnumerate Private Policies GestisciManage 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 GestisciManage Qualsiasi indirizzo dello spazio dei nomiAny namespace address
Eliminare una codaDelete a queue GestisciManage Qualsiasi indirizzo valido della codaAny valid queue address
Enumerare le codeEnumerate queues GestisciManage /$Resources/Queues/$Resources/Queues
Ottenere la descrizione di una codaGet the queue description GestisciManage Qualsiasi indirizzo valido della codaAny valid queue address
Configurare le regole di autorizzazione per una codaConfigure authorization rule for a queue GestisciManage 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
Pianificare il recapito ritardato di un messaggio, ad esempio ScheduleMessageAsync()Schedule a message for later delivery; for example, ScheduleMessageAsync() AttesaListen Qualsiasi indirizzo valido della codaAny valid queue address
ArgomentoTopic
Creare un argomentoCreate a topic GestisciManage Qualsiasi indirizzo dello spazio dei nomiAny namespace address
Eliminare un argomentoDelete a topic GestisciManage Qualsiasi indirizzo valido dell'argomentoAny valid topic address
Enumerare gli argomentiEnumerate topics GestisciManage /$Resources/Topics/$Resources/Topics
Ottenere la descrizione di un argomentoGet the topic description GestisciManage Qualsiasi indirizzo valido dell'argomentoAny valid topic address
Configurare le regole di autorizzazione per un argomentoConfigure authorization rule for a topic GestisciManage 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 GestisciManage Qualsiasi indirizzo dello spazio dei nomiAny namespace address
Eliminare una sottoscrizioneDelete subscription GestisciManage ../myTopic/Subscriptions/mySubscription../myTopic/Subscriptions/mySubscription
Enumerare le sottoscrizioniEnumerate subscriptions GestisciManage ../myTopic/Subscriptions../myTopic/Subscriptions
Ottenere la descrizione di una sottoscrizioneGet subscription description GestisciManage ../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 GestisciManage ../myTopic/Subscriptions/mySubscription../myTopic/Subscriptions/mySubscription
Eliminare una regolaDelete a rule GestisciManage ../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.