Gerenciar o Azure AD B2C com Microsoft Graph

  • Artigo

O Microsoft Graph permite que você gerencie recursos no diretório do Azure AD B2C. As operações de API do Microsoft Graph a seguir têm suporte para o gerenciamento de recursos do Azure AD B2C, incluindo usuários, provedores de identidade, fluxos de usuário, políticas personalizadas e chaves de política. Cada link nas seções a seguir foca na página correspondente na referência de API do Microsoft Graph para esta operação.

Observação

Você também pode criar de forma programática um diretório do Azure AD B2C em si, juntamente com o recurso correspondente do Azure vinculado a uma assinatura do Azure. Essa funcionalidade não é exposta por meio da API do Microsoft Graph, mas por meio da API REST do Azure. Para obter mais informações, confira Locatários B2C – Criar.

Assista a este vídeo para saber mais sobre a migração do usuário do Azure AD B2C usando a API do Microsoft Graph.

Pré-requisitos

  • Para usar o API do MS Graph e interagir com recursos no locatário do Azure AD B2C, você precisa de um registro de aplicativo que conceda as permissões necessárias. Siga as etapas no artigo Registrar um aplicativo Microsoft Graph para criar um registro de aplicativo que seu aplicativo de gerenciamento pode usar.

Gerenciamento de Usuários

Observação

No momento, o Azure AD B2C não dá suporte a funcionalidades avançadas de consulta em objetos de diretório. Isso significa que não há suporte para os parâmetros de consulta $count, $search e os operadores Não (not), Não é igual a (ne) e Termina com (endsWith) no parâmetro de consulta $filter. Para obter mais informações, confira parâmetros de consulta no Microsoft Graph e funcionalidades avançadas de consulta no Microsoft Graph.

Gerenciamento de número de telefone do usuário

Um número de telefone que pode ser usado por um usuário para entrar usando chamadas de voz ou SMS ou autenticação multifator. Para saber mais, consulte API de métodos de autenticação do Microsoft Entra.

Observe que a operação de lista retorna apenas números de telefone habilitados. O número de telefone a seguir deve ser habilitado para uso com as operações de lista.

Enable phone sign-in

Observação

Um número de telefone representado corretamente é armazenado com um espaço entre o código de país e o número de telefone. Atualmente, o serviço do Azure AD B2C não adiciona esse espaço por padrão.

Endereço de email de redefinição de senha self-service

Um endereço de email que pode ser usado por uma conta de logon de nome de usuário para redefinir a senha. Para saber mais, consulte API de métodos de autenticação do Microsoft Entra.

Método de autenticação de token OATH de software

Um token OATH de software é um gerador de número baseado em software que usa o padrão TOTP (senha de uso único) com base em tempo OATH para autenticação multifator por meio de um aplicativo autenticador. Use a API do Microsoft Graph para gerenciar um token OATH de software registrado para um usuário:

Provedores de identidade

Gerencie os provedores de identidade disponíveis para seus fluxos de usuário em seu locatário do Azure AD B2C.

Fluxo do usuário (beta)

Configure políticas predefinidas para inscrição, logon, inscrição e logon combinados, redefinição de senha e atualização de perfil.

Métodos de autenticação de fluxo de usuário (beta)

Escolha um mecanismo para permitir que os usuários se registrem por meio de contas locais. As contas locais são as contas em que o Azure AD B2C faz a declaração de identidade. Para obter mais informações, confira Tipo de recurso b2cAuthenticationMethodsPolicy .

Políticas personalizadas (beta)

As operações a seguir permitem que você gerencie suas políticas de estrutura confiável do Azure AD B2C, conhecidas como políticas personalizadas.

Chaves de política (beta)

A Identity Experience Framework armazena os segredos referenciados em uma política personalizada para estabelecer a confiança entre os componentes. Esses segredos podem ser chaves/valores simétricos ou assimétricos. No portal do Azure, essas entidades são mostradas como chaves de política.

O recurso de nível superior para chaves de política na API do Microsoft Graph é o conjunto de chaves de estrutura confiável. Cada grupo de chaves contém pelo menos uma Chave. Para criar uma chave, primeiro crie um conjunto de chaves vazio e, em seguida, gere uma chave nesse conjunto. Você pode criar um segredo manual, carregar um certificado ou uma chave PKCS12. A chave pode ser um segredo gerado, uma cadeia de caracteres (como o segredo do aplicativo do Facebook) ou um certificado que você carregar. Se um conjunto de chaves tiver várias chaves, somente uma delas estará ativa.

Conjunto de chaves da política de estrutura confiável

Chave da política de estrutura confiável

Aplicativo

Propriedades de extensão de aplicativo (extensão de diretório)

As propriedades da extensão do aplicativo também são conhecidas como extensões de diretório ou do Microsoft Entra. Para gerenciá-las no Azure AD B2C, use o tipo de recurso identityUserFlowAttribute e seus métodos associados.

Você pode armazenar até 100 valores de extensão de diretório por usuário. Para gerenciar as propriedades de extensão de um diretório para um usuário, use as seguintes APIs de Usuário no Microsoft Graph.

  • Atualizar usuário: para gravar ou remover do objeto do usuário o valor da propriedade de extensão de diretório.
  • Obter um usuário: para recuperar o valor da extensão do diretório para o usuário. A propriedade será retornada por padrão por meio do ponto de extremidade beta, mas somente no $select por meio do ponto de extremidade v1.0.

Para fluxos de usuário, essas propriedades de extensão são gerenciadas usando o portal do Azure. Para políticas personalizadas, o Azure AD B2C cria a propriedade para você, na primeira vez em que a política grava um valor na propriedade de extensão.

Observação

No Microsoft Entra ID, as extensões de diretório são gerenciadas por meio do tipo de recurso extensionProperty e seus métodos associados. No entanto, como eles são usados em B2C por meio do aplicativo b2c-extensions-app que não deve ser atualizado, eles são gerenciados no Azure AD B2C usando o tipo de recurso identityUserFlowAttribute e seus métodos associados.

Uso do locatário

Use a API Obter detalhes da organização para obter sua cota de tamanho de diretório. Você precisa adicionar o parâmetro de consulta $select, conforme mostrado na seguinte solicitação HTTP:

GET https://graph.microsoft.com/v1.0/organization/organization-id?$select=directorySizeQuota

Substitua organization-id pela ID do locatário ou da organização.

A resposta à solicitação acima é semelhante ao seguinte trecho JSON:

{
    "directorySizeQuota": {
        "used": 156,
        "total": 1250000
    }
}

Logs de auditoria

Para obter mais informações sobre como acessar os logs de auditoria do Azure AD B2C, confira Acessar os logs de auditoria do Azure AD B2C.

Acesso Condicional

Recuperar ou restaurar usuários e aplicativos excluídos

Usuários e aplicativos excluídos só poderão ser restaurados se forem excluídos nos últimos 30 dias.

Como gerenciar programaticamente o Microsoft Graph

Quando você quiser gerenciar o Microsoft Graph, você poderá fazer isso como o aplicativo usando as permissões do aplicativo, ou poderá usar as permissões delegadas. Para permissões delegadas, o usuário ou um administrador consente com as permissões que o aplicativo solicita. O aplicativo é delegado com a permissão para atuar como um usuário conectado quando faz chamadas para o recurso de destino. As permissões de aplicativo são usadas por aplicativos que não exigem a presença de um usuário conectado e, portanto, exigem permissões de aplicativo. Por isso, apenas os administradores podem consentir as permissões de aplicativo.

Observação

As permissões delegadas para usuários que se conectam por meio de fluxos de usuário ou políticas personalizadas não podem ser usadas em relação a permissões delegadas para a API do Microsoft Graph.

Exemplo de código: como gerenciar contas de usuários de forma programática

Este exemplo de código é um aplicativo de console do .NET Core que usa o SDK do Microsoft Graph para interagir com a API do Microsoft Graph. O código demonstra como chamar a API para gerenciar programaticamente usuários em um locatário do Azure AD B2C. Você pode baixar o arquivo de exemplo (*.zip), navegar pelo repositório no GitHub ou clonar o repositório:

git clone https://github.com/Azure-Samples/ms-identity-dotnetcore-b2c-account-management.git

Depois de obter o exemplo de código, configure-o para seu ambiente e crie o projeto:

  1. Abra o projeto no Visual Studio ou no Visual Studio Code.

  2. Abra o src/appsettings.json.

  3. Na seção appSettings, substitua your-b2c-tenant pelo nome do locatário e Application (client) ID e Client secret pelos valores para o registro do aplicativo de gerenciamento. Para obter mais informações, confira Registrar um aplicativo Microsoft Graph.

  4. Abra uma janela do console dentro do clone local do repositório, mude para o diretório src e, em seguida, crie o projeto:

    cd src
dotnet build

  5. Execute o aplicativo com o comando dotnet:

    dotnet bin/Debug/netcoreapp3.1/b2c-ms-graph.dll

O aplicativo exibirá uma lista de comandos que você pode executar. Por exemplo, obter todos os usuários, obter um único usuário, excluir um usuário, atualizar a senha de um usuário e importar em massa.

Observação

Para que o aplicativo atualize as senhas da conta de usuário, será necessário conceder a função de administrador de usuários ao aplicativo.

Discussão de código

O código de exemplo usa o SDK do Microsoft Graph, que foi projetado para simplificar a criação de aplicativos de alta qualidade, eficientes e resilientes que acessem o Microsoft Graph.

Qualquer solicitação para a API do Microsoft Graph requer um token de acesso para autenticação. A solução usa o pacote NuGet Microsoft.Graph.Auth que fornece um wrapper baseado em cenário de autenticação da MSAL (Biblioteca de Autenticação da Microsoft) para uso com o SDK do Microsoft Graph.

O método RunAsync no arquivo Program.cs:

  1. Faz a leitura das configurações de aplicativo do arquivo appsettings.json
  2. Inicializa o provedor auth usando o fluxo de concessão de credenciais do cliente OAuth 2.0. Com o fluxo de concessão de credenciais do cliente, o aplicativo conseguirá obter um token de acesso para chamar a API do Microsoft Graph.
  3. Configura o cliente de serviço do Microsoft Graph com o provedor auth:
// Read application settings from appsettings.json (tenant ID, app ID, client secret, etc.)
AppSettings config = AppSettingsFile.ReadFromJsonFile();

// Initialize the client credential auth provider
var scopes = new[] { "https://graph.microsoft.com/.default" };
var clientSecretCredential = new ClientSecretCredential(config.TenantId, config.AppId, config.ClientSecret);
var graphClient = new GraphServiceClient(clientSecretCredential, scopes);

O GraphServiceClient inicializado é usado em UserService.cs para executar as operações de gerenciamento de usuário. Por exemplo, obter uma lista das contas de usuário no locatário:

public static async Task ListUsers(GraphServiceClient graphClient)
{
    Console.WriteLine("Getting list of users...");

    try
    {
        // Get all users
        var users = await graphClient.Users
            .Request()
            .Select(e => new
            {
                e.DisplayName,
                e.Id,
                e.Identities
            })
            .GetAsync();

        // Iterate over all the users in the directory
        var pageIterator = PageIterator<User>
            .CreatePageIterator(
                graphClient,
                users,
                // Callback executed for each user in the collection
                (user) =>
                {
                    Console.WriteLine(JsonSerializer.Serialize(user));
                    return true;
                },
                // Used to configure subsequent page requests
                (req) =>
                {
                    Console.WriteLine($"Reading next page of users...");
                    return req;
                }
            );

        await pageIterator.IterateAsync();
    }
    catch (Exception ex)
    {
        Console.ForegroundColor = ConsoleColor.Red;
        Console.WriteLine(ex.Message);
        Console.ResetColor();
    }
}

Fazer chamadas à API usando os SDKs do Microsoft Graph inclui informações sobre como ler e gravar informações do Microsoft Graph, usar $select para controlar as propriedades retornadas, fornecer parâmetros de consulta personalizados e usar os parâmetros de consulta $filter e $orderBy.

Próximas etapas