Pular para o conteúdo principal
O PlayFab oferece suporte à autenticação do Microsoft Entra ID (anteriormente Azure Active Directory) para chamar as APIs Admin, Server e de entidade. Com a autenticação do Entra ID, você entra com sua identidade Microsoft e usa um token de acesso delegado em vez de uma chave secreta de desenvolvedor. Seu aplicativo gerencia a experiência de entrada usando fluxos padrão de cliente público do OAuth 2.0, como código de autorização com PKCE, código de dispositivo ou concessão implícita.
A autenticação do Entra ID é uma alternativa às chaves secretas de desenvolvedor para chamadas às APIs Admin, Server e a algumas APIs de entidade. As APIs Client e de entidade voltadas para jogadores continuam usando tíquetes de sessão e tokens de entidade obtidos por meio da entrada do jogador. Somente as APIs de entidade que podem ser chamadas com um token de entidade de título podem ser usadas com o Entra ID. Para obter mais informações sobre chaves secretas, confira Gerenciamento de chaves secretas.

Por que usar a autenticação do Entra ID

As chaves secretas de desenvolvedor são simples de usar, mas a autenticação do Entra ID oferece várias vantagens:
  • Sem segredos compartilhados: os fluxos de cliente público não exigem um segredo do cliente. Os tokens têm curta duração e são restritos ao usuário conectado.
  • Responsabilidade individual: cada chamada à API está vinculada a uma identidade de usuário específica, facilitando a auditoria de quem fez o quê.
  • Acesso condicional: sua organização pode aplicar políticas do Entra ID, como restrições de IP, autenticação multifator (MFA) e verificações de conformidade do dispositivo.

Como funciona a autenticação do Entra ID

Se você nunca trabalhou com o Microsoft Entra ID, ele é o serviço de identidade na nuvem da Microsoft, o mesmo sistema de identidade usado pelo Microsoft 365, pelas contas de desenvolvedor do XBOX e pelo Azure. Em vez de o PlayFab emitir para o seu estúdio uma chave secreta de longa duração, sua ferramenta solicita ao Entra ID que conecte um desenvolvedor e retorne um token de acesso de curta duração. O PlayFab confia nos tokens que o Entra ID emite para usuários que são membros do seu estúdio. Três partes estão envolvidas:
  • O desenvolvedor. Você, conectado com uma conta Microsoft (pessoal) ou uma conta corporativa ou de estudante (Entra ID).
  • Um registro de aplicativo no Entra ID. Ele representa a ferramenta que chama o PlayFab: uma CLI, um script de build, um painel interno e assim por diante. Ele informa ao Entra ID que “este aplicativo tem permissão para solicitar tokens de acesso do PlayFab em nome de um usuário conectado”.
  • O serviço PlayFab. O PlayFab está registrado no Entra ID com a ID de aplicativo 448adbda-b8d8-4f33-a1b0-ac58cf44d4c1 e expõe uma permissão delegada chamada plugin. Quando seu código solicita o escopo 448adbda-b8d8-4f33-a1b0-ac58cf44d4c1/plugin, o Entra ID emite um token que o PlayFab aceita.
Uma chamada típica tem esta aparência:
  1. Seu código usa a Biblioteca de Autenticação da Microsoft (MSAL) para iniciar uma entrada, geralmente uma janela pop-up do navegador ou um prompt de código de dispositivo.
  2. O usuário entra com sua identidade Microsoft e consente que seu aplicativo chame o PlayFab em nome dele.
  3. A MSAL retorna um token de acesso (um JWT) e armazena em cache um token de atualização para que as chamadas futuras possam ignorar o prompt.
  4. Seu código envia o token no cabeçalho Authorization: Bearer <token> em cada solicitação do PlayFab.
  5. O PlayFab valida o token, mapeia-o para o usuário correspondente do estúdio e autoriza a chamada com base na função desse usuário.
Para ver as definições dos termos do Entra ID usados ao longo deste artigo, confira o Glossário no final.

Pré-requisitos

  • Uma conta Microsoft com suporte do Entra ID (uma conta corporativa ou de estudante) ou uma conta Microsoft pessoal (MSA).
  • Um título do PlayFab. Para obter mais informações, confira Criar uma conta do PlayFab.
  • Permissões para registrar aplicativos no seu locatário do Microsoft Entra ID.
  • O usuário que faz a chamada deve ser adicionado ao estúdio do PlayFab e designado como title admin. Para obter mais informações sobre funções, confira Funções de usuário do PlayFab.

Registrar um aplicativo cliente público no Entra ID

Você precisa registrar um aplicativo no seu locatário do Entra ID para que seu código possa solicitar tokens delegados em nome de um usuário conectado. Para fluxos de cliente público (SPA, código de dispositivo, implícito), nenhum segredo do cliente é necessário.
  1. Entre no portal do Azure.
  2. Pesquise e selecione App registrations e, em seguida, selecione New registration.
  3. Insira um nome para o aplicativo (por exemplo, PlayFab API Client).
  4. Em Supported account types, selecione a opção que corresponde aos requisitos da sua organização. Para obter a máxima flexibilidade, selecione Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts. Essa opção permite que qualquer conta Microsoft se autentique.
  5. Configure o Redirect URI com base no tipo de aplicativo:
    • Para um aplicativo de página única (SPA), selecione Single-page application (SPA) e insira seu URI de redirecionamento (por exemplo, http://localhost:3000).
    • Para um aplicativo nativo ou de console que usa o fluxo de código de dispositivo, selecione Public client/native (mobile & desktop) e insira http://localhost.
  6. Selecione Register. Na página de visão geral, anote a Application (client) ID. Você precisará desse valor ao solicitar tokens.
  7. Adicione a permissão da API do PlayFab ao seu registro de aplicativo:
    1. No portal do Azure, navegue até o registro do aplicativo e selecione API permissions.
    2. Selecione Add a permission > APIs my organization uses.
    3. Pesquise a ID de aplicativo do PlayFab 448adbda-b8d8-4f33-a1b0-ac58cf44d4c1 e selecione-a.
    4. Selecione Delegated permissions, marque a permissão plugin e selecione Add permissions.
Se o seu cenário exigir um cliente confidencial (aplicativo Web), você também precisará criar um segredo do cliente em Certificates & secrets. Este artigo se concentra em fluxos de cliente público, que não exigem um segredo. Para obter mais informações sobre fluxos de cliente confidencial, confira Plataforma de identidade da Microsoft e fluxo de código de autorização do OAuth 2.0.

Configurar o acesso ao estúdio do PlayFab

O PlayFab valida os tokens do Entra ID em relação à associação ao estúdio. O usuário que faz a chamada deve ser adicionado ao estúdio do PlayFab e receber a função apropriada.
  1. Peça a um administrador do estúdio para entrar no Game Manager.
  2. Navegue até a seção Users do estúdio.
  3. Selecione Add User e insira o email da conta Microsoft do desenvolvedor que precisa de acesso à API.
  4. Selecione Microsoft como o provedor de autenticação.
  5. Atribua ao usuário uma função que inclua acesso às APIs Admin ou Server. No mínimo, o usuário deve ser title admin dos títulos nos quais precisa chamar APIs.
  6. Selecione Add user para enviar o convite.
Para obter mais informações sobre como adicionar usuários e atribuir funções, confira Autenticação de contas para o PlayFab Game Manager.

Obter um token de acesso

Seu aplicativo é responsável por conectar o usuário e obter um token de acesso delegado do Entra ID. Os exemplos a seguir mostram fluxos comuns de cliente público.

Fluxo interativo do navegador (recomendado para aplicativos de área de trabalho e de console)

O fluxo interativo do navegador abre uma janela do navegador do sistema para a entrada. É a opção recomendada para aplicativos de área de trabalho e ferramentas de desenvolvimento local.

Código de autorização com PKCE (recomendado para SPAs)

O fluxo de código de autorização com Proof Key for Code Exchange (PKCE) é a abordagem recomendada para aplicativos de página única. O exemplo em JavaScript a seguir usa a Biblioteca de Autenticação da Microsoft (MSAL):

Chamar APIs do PlayFab com o token de acesso

Inclua o token de acesso do Entra ID no cabeçalho Authorization como um token Bearer nas suas solicitações à API do PlayFab, em vez de usar o cabeçalho X-SecretKey.

Exemplo de solicitação

Você não pode usar X-SecretKey e Authorization: Bearer na mesma solicitação. Use um método de autenticação por chamada.

Exemplo em C#

O exemplo a seguir usa a Biblioteca de Autenticação da Microsoft (MSAL) para obter um token e chama a API Server/GetTime. Substitua your-client-id pela Application (client) ID do seu registro de aplicativo.

Exemplo em Node.js

O exemplo a seguir usa a biblioteca @azure/msal-node para obter um token e chama a API Server/GetTime. Substitua your-client-id pela Application (client) ID do seu registro de aplicativo.

Atualização de token

Os tokens de acesso do Entra ID têm curta duração (normalmente de 60 a 90 minutos). Se você estiver usando a MSAL, chame AcquireTokenSilent (C#) ou verifique o cache de tokens antes de cada solicitação; a MSAL gerencia a atualização automaticamente quando um token de atualização em cache está disponível. Se você estiver gerenciando tokens manualmente, solicite um novo token usando o mesmo fluxo de entrada antes que o atual expire.
Se um token expirar durante o uso, o PlayFab retornará uma resposta 401 Unauthorized. Seu aplicativo deve tratar esse erro solicitando um novo token e repetindo a chamada.

Solução de problemas

Exemplos de respostas de erro

Um 401 Unauthorized do PlayFab quando o token Bearer está ausente, malformado ou expirado tem esta aparência:
Um 403 Forbidden do PlayFab quando o usuário conectado está autenticado, mas não tem permissões de administrador no título, tem esta aparência:

Limitações

Atualmente, os SDKs do PlayFab não oferecem suporte à autenticação do Entra ID. Para chamar APIs do PlayFab com um token do Entra ID hoje, use chamadas HTTP diretas e defina você mesmo o cabeçalho Authorization: Bearer <token>, conforme mostrado nos exemplos em C# e Node.js. O suporte nos SDKs está planejado para uma versão futura.

Glossário

Confira também

Última modificação em 6 de outubro de 2026