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-ac58cf44d4c1e expõe uma permissão delegada chamadaplugin. Quando seu código solicita o escopo448adbda-b8d8-4f33-a1b0-ac58cf44d4c1/plugin, o Entra ID emite um token que o PlayFab aceita.
- 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.
- O usuário entra com sua identidade Microsoft e consente que seu aplicativo chame o PlayFab em nome dele.
- 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.
- Seu código envia o token no cabeçalho
Authorization: Bearer <token>em cada solicitação do PlayFab. - 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.
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.- Entre no portal do Azure.
- Pesquise e selecione App registrations e, em seguida, selecione New registration.
-
Insira um nome para o aplicativo (por exemplo,
PlayFab API Client). - 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.
-
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.
- Para um aplicativo de página única (SPA), selecione Single-page application (SPA) e insira seu URI de redirecionamento (por exemplo,
- Selecione Register. Na página de visão geral, anote a Application (client) ID. Você precisará desse valor ao solicitar tokens.
-
Adicione a permissão da API do PlayFab ao seu registro de aplicativo:
- No portal do Azure, navegue até o registro do aplicativo e selecione API permissions.
- Selecione Add a permission > APIs my organization uses.
- Pesquise a ID de aplicativo do PlayFab
448adbda-b8d8-4f33-a1b0-ac58cf44d4c1e selecione-a. - 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.- Peça a um administrador do estúdio para entrar no Game Manager.
- Navegue até a seção Users do estúdio.
- Selecione Add User e insira o email da conta Microsoft do desenvolvedor que precisa de acesso à API.
- Selecione Microsoft como o provedor de autenticação.
- 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.
- Selecione Add user para enviar o convite.
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çalhoAuthorization 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 APIServer/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, chameAcquireTokenSilent (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
Um401 Unauthorized do PlayFab quando o token Bearer está ausente, malformado ou expirado tem esta aparência:
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çalhoAuthorization: Bearer <token>, conforme mostrado nos exemplos em C# e Node.js. O suporte nos SDKs está planejado para uma versão futura.
