> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Autenticação do Microsoft Entra ID para APIs do PlayFab
> Autentique-se nas APIs Admin, Server e de entidade do PlayFab com tokens delegados do Microsoft Entra ID usando fluxos do OAuth 2.0, como PKCE, código de dispositivo ou concessão implícita.
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](/pt-BR/services/playfab/live-service-management/gamemanager/secret-key-management).
## 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 ` 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](#glossary) 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](/pt-BR/services/playfab/identity/dev-identity/pfab-account).
* 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](/pt-BR/services/playfab/identity/dev-identity/permissions/playfab-user-roles).
## 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](https://portal.azure.com).
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](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow).
## 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](https://developer.playfab.com).
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](/pt-BR/services/playfab/identity/dev-identity/authentication/aad-authentication).
## 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.
```csharp theme={null}
using Microsoft.Identity.Client;
// Build an MSAL public client app. The client ID identifies your Entra app
// registration; "common" lets users sign in from any Entra tenant or with a
// personal Microsoft account.
var app = PublicClientApplicationBuilder.Create("your-client-id")
.WithAuthority("https://login.microsoftonline.com/common")
.WithDefaultRedirectUri()
.Build();
// The scope identifies the PlayFab API and the delegated permission ("plugin")
// your app is requesting on behalf of the signed-in user.
string[] scopes = ["448adbda-b8d8-4f33-a1b0-ac58cf44d4c1/plugin"];
AuthenticationResult result;
try
{
// Try to get a token from MSAL's cache without prompting the user.
// This succeeds on subsequent runs while the cached refresh token is valid.
var accounts = await app.GetAccountsAsync();
result = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault())
.ExecuteAsync();
}
catch (MsalUiRequiredException)
{
// No cached token, or it expired and can't be refreshed silently.
// Open the system browser so the user can sign in interactively.
result = await app.AcquireTokenInteractive(scopes)
.WithUseEmbeddedWebView(false)
.ExecuteAsync();
}
// The access token is what you send to PlayFab in the Authorization header.
string accessToken = result.AccessToken;
```
### 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):
```javascript theme={null}
import { PublicClientApplication } from "@azure/msal-browser";
// MSAL config. clientId is your Entra app registration's Application (client) ID.
// "common" lets users sign in from any tenant or with a personal account.
// redirectUri must match a Single-page application redirect URI on the app registration.
const msalConfig = {
auth: {
clientId: "your-client-id",
authority: "https://login.microsoftonline.com/common",
redirectUri: "http://localhost:3000"
}
};
const msalInstance = new PublicClientApplication(msalConfig);
await msalInstance.initialize();
// loginPopup runs the auth code + PKCE flow in a pop-up window. The scope
// asks Entra ID for a delegated token that PlayFab will accept.
const loginResponse = await msalInstance.loginPopup({
scopes: ["448adbda-b8d8-4f33-a1b0-ac58cf44d4c1/plugin"]
});
// Send this token to PlayFab in the Authorization header.
const accessToken = loginResponse.accessToken;
```
## 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
```http theme={null}
POST https://{titleId}.playfabapi.com/Server/GetPlayerProfile
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...
{
"PlayFabId": "ABCDEF1234567890"
}
```
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.
```csharp theme={null}
using Microsoft.Identity.Client;
using System.Net.Http.Headers;
using System.Text;
// PlayFab API endpoint. Every title gets its own subdomain on playfabapi.com.
string titleId = "YOUR_TITLE_ID";
string host = $"{titleId}.playfabapi.com";
string url = $"https://{host}/Server/GetTime";
// MSAL configuration.
// clientId - your Entra app registration's Application (client) ID.
// authority - "common" lets any Entra tenant or personal Microsoft account sign in.
// scopes - the PlayFab application ID + the "plugin" delegated permission.
string clientId = "your-client-id";
string authority = "https://login.microsoftonline.com/common";
string[] scopes = ["448adbda-b8d8-4f33-a1b0-ac58cf44d4c1/plugin"];
// Build the MSAL public client. Public clients (desktop, CLI, mobile) don't use
// a client secret; tokens are bound to the signed-in user instead.
var app = PublicClientApplicationBuilder.Create(clientId)
.WithAuthority(authority)
.WithDefaultRedirectUri()
.Build();
AuthenticationResult authResult;
try
{
// Reuse a cached token if MSAL has one. Avoids prompting on every run.
var accounts = await app.GetAccountsAsync();
authResult = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault())
.ExecuteAsync();
}
catch (MsalUiRequiredException)
{
// First run, or the cached token expired. Open the system browser to sign in.
authResult = await app.AcquireTokenInteractive(scopes)
.WithUseEmbeddedWebView(false)
.ExecuteAsync();
}
// Call PlayFab. Replace X-SecretKey with an Authorization: Bearer header
// containing the Entra ID access token.
using var httpClient = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, url);
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", authResult.AccessToken);
request.Content = new StringContent("{}", Encoding.UTF8, "application/json");
var response = await httpClient.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine($"Status: {response.StatusCode}");
Console.WriteLine($"Response: {body}");
```
### 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.
```javascript theme={null}
import { PublicClientApplication } from "@azure/msal-node";
import open from "open";
// PlayFab API endpoint for your title.
const titleId = "YOUR_TITLE_ID";
const host = `${titleId}.playfabapi.com`;
const url = `https://${host}/Server/GetTime`;
// MSAL configuration.
// clientId - your Entra app registration's Application (client) ID.
// authority - "common" accepts any Entra tenant or personal Microsoft account.
const msalConfig = {
auth: {
clientId: "your-client-id",
authority: "https://login.microsoftonline.com/common",
},
};
const pca = new PublicClientApplication(msalConfig);
// Token request:
// scopes - PlayFab application ID + the "plugin" delegated permission.
// redirectUri - must match a Public client redirect URI on the app registration.
// openBrowser - MSAL calls this to launch the user's default browser for sign-in.
const tokenRequest = {
scopes: ["448adbda-b8d8-4f33-a1b0-ac58cf44d4c1/plugin"],
redirectUri: "http://localhost:3000",
openBrowser: async (url) => { await open(url); },
successTemplate: "Authentication complete. You can close this window.
",
};
// Sign the user in and obtain a delegated access token.
const authResult = await pca.acquireTokenInteractive(tokenRequest);
// Call PlayFab with the token in the Authorization header instead of X-SecretKey.
const response = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${authResult.accessToken}`,
},
body: JSON.stringify({}),
});
const body = await response.json();
console.log(`Status: ${response.status}`);
console.log("Response:", JSON.stringify(body, null, 2));
```
## 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
| Problema | Causa | Resolução |
| - | - | - |
| `401 Unauthorized` | O token expirou ou é inválido | Entre novamente e solicite um novo token |
| `403 Forbidden` | O usuário não tem a função necessária no título | Verifique a associação ao estúdio e a função title admin no Game Manager |
| `AADSTS50076: Need multifactor authentication` | A política de acesso condicional exige MFA | Conclua o desafio de MFA e tente novamente |
| `AADSTS700016: Application not found` | A ID do cliente está incorreta ou o aplicativo não está no locatário esperado | Verifique a ID do cliente e a ID do locatário |
### Exemplos de respostas de erro
Um `401 Unauthorized` do PlayFab quando o token Bearer está ausente, malformado ou expirado tem esta aparência:
```json theme={null}
{
"code": 401,
"status": "Unauthorized",
"error": "NotAuthenticated",
"errorCode": 1074,
"errorMessage": "Invalid \"Authorization\" header."
}
```
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:
```json theme={null}
{
"code": 403,
"status": "Forbidden",
"error": "NotAuthorizedByTitle",
"errorCode": 1191,
"errorMessage": "Developer does not have admin permission for this title."
}
```
## 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 `, conforme mostrado nos exemplos em [C#](#c-example) e [Node.js](#nodejs-example). O suporte nos SDKs está planejado para uma versão futura.
## Glossário
| Termo | Significado |
| - | - |
| **Locatário** | Um diretório isolado no Entra ID. Sua empresa tem um; as contas Microsoft pessoais usam um locatário compartilhado chamado *consumers*. A autoridade `common` usada nos exemplos permite que os usuários entrem a partir de qualquer locatário. |
| **Registro de aplicativo** | O registro no Entra ID que descreve seu aplicativo cliente (sua ID do cliente, os URIs de redirecionamento permitidos e as permissões de API solicitadas). |
| **Permissão delegada** | Uma permissão que seu aplicativo recebe *em nome de* um usuário conectado, em vez de agir por conta própria. |
| **Cliente público** | Um cliente que não pode armazenar um segredo com segurança: um aplicativo de área de trabalho ou móvel, uma CLI ou um aplicativo Web de página única. Os clientes públicos usam fluxos como código de autorização com PKCE ou código de dispositivo em vez de um segredo do cliente. |
| **Escopo** | A permissão de API que seu código solicita ao Entra ID. Para o PlayFab, o escopo é `448adbda-b8d8-4f33-a1b0-ac58cf44d4c1/plugin`. |
| **MSAL** | Biblioteca de Autenticação da Microsoft. A biblioteca de cliente oficial que implementa todos esses fluxos para que você não precise criar solicitações OAuth manualmente. |
## Confira também
* [Gerenciamento de chaves secretas](/pt-BR/services/playfab/live-service-management/gamemanager/secret-key-management)
* [Autenticação de contas para o PlayFab Game Manager](/pt-BR/services/playfab/identity/dev-identity/authentication/aad-authentication)
* [Funções de usuário do PlayFab](/pt-BR/services/playfab/identity/dev-identity/permissions/playfab-user-roles)
* [Política de acesso à API](/pt-BR/services/playfab/api-references/api-access-policy)
* [Documentação do Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/fundamentals/whatis)
## Related topics
- [Conectando o Grafana ao Insights](/pt-BR/services/playfab/data-analytics/legacy/connectivity/connecting-grafana-to-insights.md)
- [Autenticação de contas Microsoft para o PlayFab](/pt-BR/services/playfab/identity/dev-identity/authentication/aad-authentication.md)
- [Autenticação](/pt-BR/services/playfab/identity/player-identity/authentication/index.md)
- [Autenticação do PlayFab com a entrada com o Google Play Games no Unity](/pt-BR/services/playfab/identity/player-identity/platform-specific-authentication/google-sign-in-unity.md)
- [Autenticar seu serviço com as APIs da Microsoft Store](/pt-BR/publishing/xstore-commerce/xstore-authenticating-service.md)