VENDAS: 1-800-867-1389

Usar a Graph API para consultar o Azure AD

Atualizado: maio de 2014

noteObservação
OBSERVAÇÃO: Este exemplo está desatualizado. Sua tecnologia, métodos e/ou instruções da interface do usuário foram substituídos por recursos mais novos. Para ver um exemplo atualizado para criar um aplicativo semelhante, consulte WebApp-GraphAPI-DotNet.

Este aplicativo de exemplo é destinado a desenvolvedores do .NET que desejam adicionar aos aplicativos existentes e construir novos aplicativos para o Windows Azure Active Directory (Windows Azure AD). Este passo a passo baseia-se no Adicionar logon ao seu aplicativo Web usando o Azure AD, que produziu um aplicativo de exemplo que demonstra como fornecer uma experiência de usuário de logon único da Web para os clientes do Windows Azure AD. Este passo a passo mostra como usar a Graph API do Windows Azure AD para ler dados do diretório. A Graph API é uma API RESTful API que permite que os aplicativos acessem dados do diretório do cliente do Windows Azure.

Os aplicativos precisam ter acesso aos dados do diretório para muitos cenários, incluindo:

  • Recuperar listas de usuários, grupos, contatos para seletores de pessoas/grupo

  • Ler informações detalhadas de locatário, usuário e grupo

  • Verificar associação de grupo

  • Modificar associação de usuário, grupos e grupo

  • Atualizar senhas de um usuário

  • Desativar contas do usuário

noteObservação
Quando um aplicativo multilocatário tenta adquirir um token para acessar a Graph API de um locatário do Azure AD que consentiu recentemente no aplicativo, a solicitação de token pode falhar com o erro ACS50012. Para resolver o problema, aguarde alguns minutos e tente novamente. Ou obtenha o administrador de locatário que forneceu o logon de consentimento ao aplicativo após o consentimento. Para saber mais, consulte Códigos de erro ACS.

Este documento está organizado nas seguintes seções:

Os pré-requisitos a seguir são necessários para concluir este tutorial:

No final deste passo a passo, você terá um aplicativo que configurado para ler dados do seu locatário do Azure AD. O aplicativo pode ler as seguintes entidades de diretório: Usuários, Grupos, Contatos, Informações sobre a empresa, Licenças e Funções; e, se o seu aplicativo receber permissões de gravação, ele também poderá atualizar as entidades.

Neste aplicativo de exemplo, vamos rever como ler dados do diretório da sua empresa do Azure AD. Outros tópicos avançados incluem:

  • Obter detalhes totais de usuário

  • Criar e atualizar os usuários

  • Obter uma lista de grupos

  • Atualizar associação de grupo

A experiência de logon único continua a mesma depois que você atualizar o aplicativo para que ele possa acessar a Graph API. Após uma autenticação de usuário bem-sucedida, o aplicativo solicita um token do ponto de extremidade de autenticação do Azure AD e, se conseguir, o aplicativo usa o token em chamadas para a Graph API para chegar a todos os usuários do locatário. O aplicativo exibe uma lista de usuários, mostrando os seus Display Names e User Principal Names.

Arquitetura da solução

Neste passo a passo, vamos usar o fluxo de credenciais do cliente OAuth 2.0 para autenticar o aplicativo. Antes de acessar o ponto de extremidade da Graph API, o aplicativo deve primeiro adquirir um token válido do ponto de extremidade do Azure AD; ele faz isso através da apresentação de credenciais válidas do aplicativo (ID do cliente e secredo). Se as credenciais forem validadas, um token assinado é retornado ao aplicativo. Depois disso, o aplicativo inclui o token no cabeçalho de Autorização de suas chamadas para a Graph API. O serviço de Graph API valida o token em relação à solicitação de entrada e, se passar, uma verificação de autorização ocorre em seguida.

A autorização do aplicativo é verificada pela Graph API e o seu serviço de Controle de acesso baseado em função (RBAC). As chamadas para a Graph API são limitadas pelas permissões do aplicativo. Os dados são retornados para o aplicativo se a autenticação e autorização forem aprovadas.

A autenticação de um aplicativo e a configuração de autorização são armazenadas no Azure AD usando um objeto Service Principal armazenado no diretório do locatário. Os aplicativos são representados no Azure AD por um objeto Service Principal com uma identidade, credenciais e permissões exclusivas. Isso é semelhante aos objetos User Principal no Active Directory que representam usuários, cada um com identidades, credenciais e permissões exclusivas.

O Service Principal de um aplicativo tem uma ID exclusiva e um segredo que é usado para autenticação. A autorização é gerenciada pela adição da Entidade de serviço do aplicativo a uma função que tem as permissões necessárias. Os administradores podem criar Entidades de serviço do aplicativo e adicioná-los a funções no Portal de Gerenciamento do Azure AD. Opcionalmente, os administradores Locatários também podem usar o Windows PowerShell para gerenciar Entidades de serviço. Para obter mais informações, consulte Gerenciar o Azure AD com o Windows PowerShell.

No passo a passo Adicionar logon ao seu aplicativo Web usando o Azure AD, você autorizou o aplicativo a permitir o logon único usando suas credenciais de usuário do Azure AD, configurando as permissões de aplicativo no Portal de Gerenciamento do Azure AD. Agora você vai atualizar a configuração do aplicativo para permitir que seu aplicativo de Relatório de Despesas se autenticado à Graph API e seja autorizado a chamá-la. Nós vamos executar os seguintes passos:

  • Autorização: Configure as permissões do seu aplicativo para permitir o acesso de leitura/gravação ao diretório.

  • Autenticação: Obtenha uma chave de aplicativo, que é a senha do aplicativo. Ela é usada para autenticar o seu aplicativo à Graph API.

  1. Vá para o Portal de Gerenciamento do Microsoft Azure(https://manage.WindowsAzure.com), entre e, em seguida, clique em Active Directory. (Dica de solução de problemas: o item "Active Directory" está ausente ou indisponível)

  2. Clique para selecionar o diretório, clique em Aplicativos, e, depois, clique no aplicativo de exemplo de Relatório de Despesas que você criou no passo a passo de logon único.



    Acesso Externo

  3. Na parte inferior da página, clique em Gerenciar Acesso.

  4. Selecione Alterar o acesso ao diretório para este aplicativo.



    O que você deseja fazer?
  5. Selecione Logon único, ler dados do diretório. Depois, clique na marca de seleção para salvar as alterações.



    Acesso ao diretório

  1. Na página do aplicativo de Relatório de Despesas, expanda Habilite o seu aplicativo para ler ou gravar dados no diretório. Na seção Criar uma chave, selecione Configurar chave.



    Configurar chave

  2. Para adicionar uma chave, na página Configurar, na seção Chaves, selecione a vida útil da chave (padrão 1 ano) e clique em Salvar na parte inferior da tela. Isso gera um valor de chave que é a senha do aplicativo.

    WarningAviso
    O valor da chave é exibido depois da criação da chave, mas cannot ser recuperado posteriormente. Portanto, copie imediatamente o valor da chave e guarde em um local seguro para referência futura. Além disso, o aplicativo pode ter várias chaves. Por exemplo, você pode querer uma ou mais para testes e produção.



    Chave de gráfico

Nesse ponto, você tem uma ID de cliente (ID do aplicativo), uma chave do aplicativo (o valor da chave) e tem permissões de leitura configuradas para o aplicativo.

noteObservação
Neste aplicativo de exemplo do passo a passo, estamos usando o valor da chave como uma senha para autenticar o aplicativo. Nos termos do OAuth 2.0, estamos usando o fluxo de Concessão de credenciais de cliente, onde grant_type=client_credentials).

Abra o Visual Studio e depois abra o "Relatório de Despesas", o projeto de passo a passo de logon único que você já tinha criado. Nós vamos modificar o aplicativo passo a passo de logon único nos seguintes passos:

  1. Adicionar o projeto de classe auxiliar Gráfica

  2. Atualize para o WCF Datservices 5.3 ou superior

  3. Atualizar o arquivo Web.config

  4. Modifique o HomeController.

  5. Adicionar uma nova exibição para os usuários

  6. Atualizar a exibição comum _Layout

Baixe a Biblioteca auxiliar da Graph API do Azure AD. O projeto de classe Gráfica auxiliar inclui uma biblioteca e classes que facilitam a autenticação e chamam a Graph API. Ele inclui o código fonte e deve ser incluído e construído como parte desse passo a passo.

  1. Para adicionar a Gráfica auxiliar ao projeto Relatório de Despesas, clique com o botão direito do mouse na solução Solução 'ExpenseReport', clique em Adicionar, e clique em Projeto existente.

  2. Na caixa de diálogo Adicionar projeto existente, navegue até o caminho da Gráfica auxiliar e abra o arquivo de projeto Microsoft.WindowsAzure.ActiveDirectory.GraphHelper.csproj.

O projeto Gráfica auxiliar é adicionado à sua solução ExpenseReport.

A seção appSettings do arquivo Web.config tem informações de configuração específica do aplicativo. Adicione os pares de valor de chave ClientId e Password ao arquivo Web.config do aplicativo.

  • ClientId: igual ao valor de ID do cliente da página de gerenciamento de aplicativo do Portal de Gerenciamento do Azure AD.

  • Senha: igual ao valor de chave do aplicativo da página de gerenciamento de aplicativo do Portal de Gerenciamento do Azure AD. Ele deve ter sido gravado no passo anterior para criar uma chave. Observe que ele não é recuperável. Se você tiver esquecido ou perdido a chave anterior, crie outra sob o mesmo aplicativo.

<appSettings>
    <add key="ClientId" value="<insert your ClientId here>"/>
    <add key="Password" value="<insert your Application Key here>"/>
    ...

Depois de fazer as alterações, salve o arquivo Web.config.

  1. No Visual Studio, clique com o botão direito no na pasta Referências do projeto de Relatório de Despesas e em Adicionar Referência…

  2. Na caixa de diálogo Gerenciador de Referências, clique em Extensões e selecione o assembly Microsoft.Data.OData versão 5.3.0.0 e o assembly Microsoft.Data.Services.Client versão 5.3.0.0.



    Referência de OData
  3. Na mesma caixa de diálogo Gerenciador de Referências, expanda o menu Solução à esquerda e clique na caixa de seleção para o Microsoft.WindowsAzure.ActiveDirectory.GraphHelper. Pressione OK e as referências serão adicionadas ao seu projeto.



    Referência de auxiliar para adição de gráfico

Abra o arquivo HomeController.cs, que está na pasta Controladores. Adicione os assemblies seguintes ao arquivo e salve o arquivo.

using System.Configuration;
using System.Security.Claims;
using System.Data.Services.Client;
using Microsoft.WindowsAzure.ActiveDirectory;
using Microsoft.WindowsAzure.ActiveDirectory.GraphHelper;

Localize a classe HomeController no arquivo HomeController.cs, onde o ActionResults existente reside (Índice, Sobre, Contato). Adicione um novo ActionResult chamado Usuários como mostrado abaixo:

       public ActionResult Users()
       {
            //get the tenantName
            string tenantName = ClaimsPrincipal.Current.FindFirst("http://schemas.microsoft.com/identity/claims/tenantid").Value;



            // retrieve the clientId and password values from the Web.config file
            string clientId = ConfigurationManager.AppSettings["ClientId"];
            string password = ConfigurationManager.AppSettings["Password"];



            // get a token using the helper
            AADJWTToken token = DirectoryDataServiceAuthorizationHelper.GetAuthorizationToken(tenantName, clientId, password);

            // initialize a graphService instance using the token acquired from previous step
            DirectoryDataService graphService = new DirectoryDataService(tenantName, token);

            //  get Users
            //
            var users = graphService.users;
            QueryOperationResponse<User> response;
            response = users.Execute() as QueryOperationResponse<User>;
            List<User> userList = response.ToList();
            ViewBag.userList = userList;


            //  For subsequent Graph Calls, the existing token should be used.
            //  The following checks to see if the existing token is expired or about to expire in 2 mins
            //  if true, then get a new token and refresh the graphService
            //
            int tokenMins = 2;
            if (token.IsExpired || token.WillExpireIn(tokenMins))
            {
                AADJWTToken newToken = DirectoryDataServiceAuthorizationHelper.GetAuthorizationToken(tenantName, clientId, password);
                token = newToken;
                graphService = new DirectoryDataService(tenantName, token);
            }

            //  get tenant information
            //
            var tenant = graphService.tenantDetails;
            QueryOperationResponse<TenantDetail> responseTenantQuery;
            responseTenantQuery = tenant.Execute() as QueryOperationResponse<TenantDetail>;
            List<TenantDetail> tenantInfo = responseTenantQuery.ToList();
            ViewBag.OtherMessage = "User List from tenant: " + tenantInfo[0].displayName;


            return View(userList);
       }

Criar uma nova exibição sob as pastas Exibições/Inicial chamada Users.cshtml, e adicione o seguinte código:

@model IEnumerable<Microsoft.WindowsAzure.ActiveDirectory.User> 
@{
    ViewBag.Title = "Users";
}

<h1>@ViewBag.Message</h1>
<h2>@ViewBag.OtherMessage</h2>
<table>
    <tr>
        <th>
            DisplayName
        </th>
        <th>
            UPN
        </th>
        <th></th>
    </tr>

@if (User.Identity.IsAuthenticated)
{

  foreach (var user in Model) {
    <tr>
        <td>
         @Html.DisplayFor(modelItem => user.displayName)    
        </td>
        <td>
         @Html.DisplayFor(modelItem => user.userPrincipalName)
        </td>
   </tr>
  }
}
</table>

Na pasta Exibições/Compartilhadas, abra o arquivo _Layout.cshtml. Na seção <header> do arquivo no elemento <nav>, adicionar o novo item da lista: "<li>@Html.ActionLink("Users", "Users", "Home")</li>". Em seguida, salve o arquivo.

               <nav>
                        <ul id="menu">
                            <li>@Html.ActionLink("Home", "Index", "Home")</li>
                            <li>@Html.ActionLink("About", "About", "Home")</li>
                            <li>@Html.ActionLink("Contact", "Contact", "Home")</li>
                            <li>@Html.ActionLink("Users", "Users", "Home")</li>
                        </ul>
                    </nav>

Para executar o aplicativo, pressione F5. Quando solicitado, entre com as credenciais de um usuário em seu diretório do Azure AD, ou seja, um usuário com uma conta de organização no domínio do seu diretório.

A experiência de logon único é a mesma que você viu no passo a passo anterior, que exige autenticação com as suas credenciais do Azure AD. Se tiver publicado seu aplicativo em um site, você deve atualizá-lo com as atualizações deste passo a passo. Depois da autenticação de usuário bem sucedida, selecione a guia Usuários no menu superior direito.

Exibir usuários

O aplicativo inicia o processo de chamar a Graph API solicitando primeiro um token de autenticação do AD do ponto de extremidade do Azure. Uma vez que isso ocorrer, ele irá usar o token na chamada Gráfica subsequente para chegar a todos os usuários do locatário. Depois, o aplicativo exibe uma lista de usuários, mostrando os seus Display Names e User Principal Names.

Isso conclui a codificação para o aplicativo do passo a passo da Graph API. A próxima seção inclui informações mais detalhadas e links para um aplicativo de exemplo da Graph API mais avançada que mostra operações adicionais de leitura e gravação.

Depois do logon único bem-sucedido, o aplicativo solicitará um token do ponto de extremidade de autorização do Azure AD, usando o nome do locatário (obtida do logon na solicitação de ID do locatário do usuário), ClientID e Senha para autenticar. Os detalhes do método que suporta o token de aquisição podem ser encontrados na classe DirectoryDataServiceAuthorizationHelper localizada no arquivo do mesmo nome. O método GetAuthorization gerencia a aquisição do token da Web JSON (JWT) da autenticação do Azure AD fornecendo um nome válido de locatário (qualquer domínio verificado pertencente ao locatário), ID de cliente e a Senha.

Uma solicitação bem-sucedida retornará um token JWT para ser usado em chamadas para a Graph API, que é inserido no cabeçalho de autorização de solicitações subsequentes. A chamada de Graph API para chegar a todos os usuários é uma solicitação HTTP GET que contém os seguintes cabeçalhos:

Content-Type: application/json; odata=minimalmetadata
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1T….

Recomenda-se que o token JWT seja armazenado em cache pelo aplicativo para chamadas subsequentes. No aplicativo de exemplo, a expiração do token JWT é verificada antes que uma segunda chamada de Graph API seja feita. Se o token tiver expirado, um novo token será adquirido. Se uma chamada para a Graph API for feita com um token expirado, a resposta de erro a seguir será devolvida, e o cliente deverá solicitar um novo token.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="contoso.com", error="invalid_token", error_description="Your access token has expired. Please renew it before submitting the request.", 

noteObservação
Atualmente, há uma visualização da Biblioteca de Autenticação do Azure (AAL) que gerencia a aquisição dos tokens de autenticação do Azure AD. Quando a AAL for lançada, vamos atualizar nossos aplicativos de exemplo e a documentação para usar a AAL. A documentação para a visualização da AAL está localizada aqui.

Outras chamadas REST, incluindo métodos de leitura e gravação, podem ser encontrados em outro aplicativo de exemplo MVC4 que pode ser baixado aqui.

Este exemplo demonstra funcionalidades adicionais do REST, incluindo:

  • Obter e definir detalhes do usuário, incluindo fotos em miniatura

  • Criar e atualizar grupos

  • Atualizar associação de grupo

  • Paginação para lidar com um grande número de objetos retornados

Isso foi útil para você?
(1500 caracteres restantes)
Agradecemos os seus comentários

Contribuições da comunidade

Mostrar:
© 2014 Microsoft