Como usar o Serviço de Gerenciamento do ACS para configurar aplicativos de terceira parte confiável

  • Artigo

Atualizado: 19 de junho de 2015

Aplica-se ao Azure

Aplica-se A

  • Access Control do Active Directory do Microsoft Azure (também conhecido como Access Control Service ou ACS)

Visão geral

Você pode configurar aplicativos de terceira parte confiável do ACS usando o Portal de Gerenciamento do ACS (para obter mais informações, consulte Aplicativos de Terceira Parte Confiável) ou o Serviço de Gerenciamento do ACS. Trabalhar com o Serviço de Gerenciamento do ACS pode ser mais eficiente se você estiver criando uma interface de usuário personalizada para gerenciar o ACS ou se quiser automatizar a integração de um novo locatário para soluções SaaS (Software como serviço) multilocatário.

Etapas para configurar aplicativos de terceira parte confiável usando o Serviço de Gerenciamento ACS

Importante

Antes de executar as etapas a seguir, verifique se o sistema atende a todos os requisitos de estrutura e plataforma do .NET que são resumidos em pré-requisitos do ACS.

Para configurar aplicativos de terceira parte confiável usando o Serviço de Gerenciamento do ACS, conclua as seguintes etapas:

  • Etapa 1 – Coletar informações de configuração do ACS

  • Etapa 2 – Criar um exemplo de aplicativo de console

  • Etapa 3 – Adicionar referências aos serviços e assemblies necessários

  • Etapa 4 – Implementar o cliente do Serviço de Gerenciamento

  • Etapa 5 – Adicionar um aplicativo de terceira parte confiável

Etapa 1 – Coletar informações de configuração do ACS

Você pode usar o Portal de Gerenciamento do ACS para coletar as informações de configuração necessárias. Para obter mais informações sobre como iniciar o Portal de Gerenciamento do ACS, consulte o Portal de Gerenciamento do ACS.

Para coletar informações de configuração do ACS

  1. Inicie o Portal de Gerenciamento do ACS. Para obter mais informações sobre como iniciar o Portal de Gerenciamento do ACS, consulte o Portal de Gerenciamento do ACS.

  2. Obtenha o valor da conta de serviço de gerenciamento do ACS. Você pode usar a conta padrão ManagementClient. Para exibir esse valor, no Portal de Gerenciamento do ACS, clique no serviço Gerenciamento na seção Administração na árvore no lado esquerdo da página.

  3. Obtenha o valor da senha da conta do Serviço de Gerenciamento do ACS. Para exibir esse valor, faça o seguinte:

    1. No Portal de Gerenciamento do ACS, clique no serviço Gerenciamento na seção Administração na árvore no lado esquerdo da página.

    2. Na página Serviço de gerenciamento, clique em ManagementClient em Contas do Serviço de Gerenciamento.

    3. Na página Editar Contas do Serviço de Gerenciamento, em Credenciais, clique em Senha.

    4. Na página Editar Credencial de Gerenciamento, copie o valor no campo Senha.

  4. Obtenha o nome do namespace do Azure. Você pode obter esse valor do portal do Azure ou da URL do Portal de Gerenciamento do ACS. Por exemplo, em http://contoso.accesscontrol.windows.net, o nome do namespace é contoso.

  5. Obtenha o nome do host do ACS. Normalmente é accesscontrol.windows.net.

Etapa 2 – Criar um exemplo de aplicativo de console

Nesta etapa, você cria um aplicativo de console de exemplo que pode executar o código para adicionar seus grupos de regras e regras do ACS.

Para criar um exemplo de aplicativo de console

  1. Abra Visual Studio 2012 e crie um novo projeto de aplicativo de console no modelo Windows instalado.

  2. Adicione o código a seguir à classe Programa e atribua as variáveis serviceIdentityPasswordForManagement, serviceNamespace e acsHostName às informações de configuração apropriadas que você coletou na etapa anterior.

    public const string serviceIdentityUsernameForManagement = "ManagementClient";
public const string serviceIdentityPasswordForManagement = "My Password/Key for ManagementClient";
public const string serviceNamespace = "MyNameSpaceNoDots";
public const string acsHostName = "accesscontrol.windows.net";
public const string acsManagementServicesRelativeUrl = "v2/mgmt/service/";
static string cachedSwtToken;

Etapa 3 – Adicionar referências aos serviços e assemblies necessários

Nesta etapa, você identifica e adiciona as dependências necessárias aos serviços e assemblies.

Para adicionar as dependências necessárias aos serviços e assemblies

  1. Clique com o botão direito do mouse em Referências, clique em Adicionar Referência e adicione uma referência a System.Web.Extensions.

    Observação

    Você talvez tenha que clicar com o botão direito do mouse no nome do exemplo de aplicativo de console no Gerenciador de Soluções, selecionar Propriedades e alterar a estrutura de destino de seu exemplo de aplicativo no .NET Framework 4 Client Profile (atribuído por padrão quando você cria um novo aplicativo de console) ao .NET Framework 4.

  2. Clique com o botão direito do mouse em Referências de Serviço, clique em Adicionar Referência de Serviço e adicione uma referência de serviço ao Serviço de Gerenciamento. A URL do Serviço de Gerenciamento é exclusiva para seu namespace e tem uma aparência semelhante a esta:

    https:// YOURNAMESPACE.accesscontrol.windows.net/v2/mgmt/service

  3. Adicione as seguintes declarações, onde MyConsoleApplication é o nome de seu aplicativo de console:

    using System;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Web;
using System.Net;
using System.Data.Services.Client;
using System.Collections.Specialized;
using System.Web.Script.Serialization;
using System.Globalization;
using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates; 
using MyConsoleApplication.MyServiceReference;

Etapa 4 – Implementar o cliente do Serviço de Gerenciamento

Nesta etapa, você implementa o cliente do Serviço de Gerenciamento.

Para implementar o cliente do Serviço de Gerenciamento

  1. Adicione o seguinte método à classe Programa :

       public static ManagementService CreateManagementServiceClient()
        {
            string managementServiceEndpoint = String.Format(CultureInfo.InvariantCulture, "https://{0}.{1}/{2}",
                serviceNamespace,
                acsHostName,
                acsManagementServicesRelativeUrl);
            ManagementService managementService = new ManagementService(new Uri(managementServiceEndpoint));

            managementService.SendingRequest += GetTokenWithWritePermission;

            return managementService;
        }

  2. Adicione o método GetTokenWithWritePermission e seus métodos auxiliares à classe Programa. GetTokenWithWritePermission e seus auxiliares adicionam o token SWT OAuth ao cabeçalho de autorização da solicitação HTTP.

    public static void GetTokenWithWritePermission(object sender, SendingRequestEventArgs args)
        {
            GetTokenWithWritePermission((HttpWebRequest)args.Request);
        }

        public static void GetTokenWithWritePermission(HttpWebRequest args)
        {
            if (cachedSwtToken == null)
            {
                cachedSwtToken = GetTokenFromACS();
            }

            args.Headers.Add(HttpRequestHeader.Authorization, "Bearer " + cachedSwtToken);
        }

        private static string GetTokenFromACS()
        {
            //
            // Request a token from ACS
            //
            WebClient client = new WebClient();
            client.BaseAddress = string.Format(CultureInfo.CurrentCulture, 
                                               "https://{0}.{1}", 
                                               serviceNamespace, 
                                               acsHostName);

            NameValueCollection values = new NameValueCollection();
            values.Add("grant_type", "client_credentials");
            values.Add("client_id", serviceIdentityUsernameForManagement);
            values.Add("client_secret", serviceIdentityPasswordForManagement);
            values.Add("scope", client.BaseAddress + acsManagementServicesRelativeUrl);

            byte[] responseBytes = client.UploadValues("/v2/OAuth2-13", "POST", values);

            string response = Encoding.UTF8.GetString(responseBytes);

            // Parse the JSON response and return the access token 
            JavaScriptSerializer serializer = new JavaScriptSerializer();

            Dictionary<string, object> decodedDictionary = serializer.DeserializeObject(response) as Dictionary<string, object>;

            return decodedDictionary["access_token"] as string;

        }

Etapa 5 – Adicionar um aplicativo de terceira parte confiável

Nesta etapa, você cria um aplicativo de terceira parte confiável de exemplo com um formato de token SAML 2.0 (opção padrão), nenhuma política de criptografia de token (opção padrão), associada a um provedor de identidade de Windows ID dinâmica (conta da Microsoft) (opção padrão), 600 segundos de tempo de vida do token (opção padrão) e um certificado de assinatura de token X.509 personalizado para seu aplicativo de terceira parte ou um certificado de assinatura de token para o token Controle de Acesso namespace.

Para adicionar um aplicativo de terceira parte confiável com um certificado de assinatura de token de namespace Controle de Acesso

  1. Inicialize o cliente do Serviço de Gerenciamento adicionando o seguinte código ao método Principal na classe Programa:

    ManagementService svc = CreateManagementServiceClient();

  2. Adicione o novo aplicativo de terceira parte confiável (você pode chamá-lo de “MeuAplicativoDeTerceiraParteConfiavel”, como no código abaixo) e salve as alterações adicionando o código ao método Principal na classe Programa:

    Observação

    Substituta "Caminho completo do arquivo .PFX" no código abaixo pelo caminho completo válido de seu certificado X.509. Por exemplo, se um certificado chamado ACS2ClientCertificate.cer for salvo em C:, o valor correto será "C:\ ACS2ClientCertificate.cer".

    Substitua “SenhaDoMeuCertificado” no código abaixo pela senha correta de seu certificado X.509. 

                //Create Relying Party Application

            RelyingParty relyingParty = new RelyingParty()
            {
                Name = "MyRelyingPartyApplication",
                AsymmetricTokenEncryptionRequired = false,
                TokenType = "SAML_2_0",
                TokenLifetime = 3600
            };

            svc.AddToRelyingParties(relyingParty);


            //Create the Realm Address

            RelyingPartyAddress realmAddress = new RelyingPartyAddress()
            {
                Address = "http://TestRelyingParty.com/Realm",
                EndpointType = "Realm"
            };

            svc.AddRelatedObject(relyingParty, "RelyingPartyAddresses", realmAddress);

            //Create the Return URL Address

            RelyingPartyAddress replyAddress = new RelyingPartyAddress()
            {
                Address = "http://TestRelyingParty.com/Reply",
                EndpointType = "Reply"
            };

            svc.AddRelatedObject(relyingParty, "RelyingPartyAddresses", replyAddress);

          // Create a Rule Group for This Relying Party Application

            RuleGroup rg = new RuleGroup();
            rg.Name = "SampleRuleGroup For " + relyingParty.Name;
            svc.AddToRuleGroups(rg);

            // Assign This New Rule Group to Your New Relying Party Application

            RelyingPartyRuleGroup relyingPartyRuleGroup = new RelyingPartyRuleGroup();

            svc.AddToRelyingPartyRuleGroups(relyingPartyRuleGroup);
            svc.AddLink(relyingParty, "RelyingPartyRuleGroups", relyingPartyRuleGroup);
            svc.AddLink(rg, "RelyingPartyRuleGroups", relyingPartyRuleGroup);


            //Save Your New Relying Party Application

            svc.SaveChanges(SaveChangesOptions.Batch);

Para adicionar um aplicativo de terceira parte confiável com um certificado de assinatura de token dedicado

  1. Inicialize o cliente do Serviço de Gerenciamento adicionando o seguinte código ao método Principal na classe Programa:

    ManagementService svc = CreateManagementServiceClient();

  2. Crie uma função auxiliar ReadBytesFromPfxFile para ler bytes do certificado X.509 adicionando o seguinte código à classe Programa:

    //Helper Function to Read Bytes from Your .pfx file

        public static byte[] ReadBytesFromPfxFile(string pfxFileName, string protectionPassword)
        {
            byte[] signingCertificate;
            using (FileStream stream = File.OpenRead(pfxFileName))
            {
                using (BinaryReader br = new BinaryReader(stream))
                {
                    signingCertificate = br.ReadBytes((int)stream.Length);
                }
            }

            return signingCertificate;
        }

  3. Adicione o novo aplicativo de terceira parte confiável (você pode chamá-lo de “MeuAplicativoDeTerceiraParteConfiavel”, como no código abaixo) e salve as alterações adicionando o código ao método Principal na classe Programa:

    Observação

    Substituta "Caminho completo do arquivo .PFX" no código abaixo pelo caminho completo válido de seu certificado X.509. Por exemplo, se um certificado chamado ACS2ClientCertificate.cer for salvo em C:, o valor correto será "C:\ ACS2ClientCertificate.cer".

    Substitua “SenhaDoMeuCertificado” no código abaixo pela senha correta de seu certificado X.509. 

                //Create Relying Party Application

            RelyingParty relyingParty = new RelyingParty()
            {
                Name = "MyRelyingPartyApplication",
                AsymmetricTokenEncryptionRequired = false,
                TokenType = "SAML_2_0",
                TokenLifetime = 3600
            };

            svc.AddToRelyingParties(relyingParty);


            //Create the Realm Address

            RelyingPartyAddress realmAddress = new RelyingPartyAddress()
            {
                Address = "http://TestRelyingParty.com/Realm",
                EndpointType = "Realm"
            };

            svc.AddRelatedObject(relyingParty, "RelyingPartyAddresses", realmAddress);

            //Create the Return URL Address

            RelyingPartyAddress replyAddress = new RelyingPartyAddress()
            {
                Address = "http://TestRelyingParty.com/Reply",
                EndpointType = "Reply"
            };

            svc.AddRelatedObject(relyingParty, "RelyingPartyAddresses", replyAddress);

            //Create a Signing Certificate

            X509Certificate2 cert = new X509Certificate2(@"Full path to your .PFX file", "MyCertificatePassword");
            DateTime startDate, endDate;
            startDate = cert.NotBefore.ToUniversalTime();
            endDate = cert.NotAfter.ToUniversalTime();

            string pfxFileName = @"Full path to your .PFX file";
            string pfxPassword = @"MyCertificatePassword";

            byte[] signingCertificate = ReadBytesFromPfxFile(pfxFileName, pfxPassword);

            RelyingPartyKey relyingPartyKey = new RelyingPartyKey()
            {
                StartDate = startDate.ToUniversalTime(),
                EndDate = endDate.ToUniversalTime(),
                Type = "X509Certificate",
                Usage = "Signing",
                IsPrimary = true,
                Value = signingCertificate,
                Password = Encoding.UTF8.GetBytes("MyCertificatePassword")
            };
            svc.AddRelatedObject(relyingParty, "RelyingPartyKeys", relyingPartyKey);


          // Create a Rule Group for This Relying Party Application

            RuleGroup rg = new RuleGroup();
            rg.Name = "SampleRuleGroup For " + relyingParty.Name;
            svc.AddToRuleGroups(rg);

            // Assign This New Rule Group to Your New Relying Party Application

            RelyingPartyRuleGroup relyingPartyRuleGroup = new RelyingPartyRuleGroup();

            svc.AddToRelyingPartyRuleGroups(relyingPartyRuleGroup);
            svc.AddLink(relyingParty, "RelyingPartyRuleGroups", relyingPartyRuleGroup);
            svc.AddLink(rg, "RelyingPartyRuleGroups", relyingPartyRuleGroup);


            //Save Your New Relying Party Application

            svc.SaveChanges(SaveChangesOptions.Batch);

Consulte Também

Conceitos

Instruções do ACS