Usar o Azure DevOps OAuth 2.0

Azure DevOps Services

Este artigo explica como o Azure DevOps OAuth 2.0 funciona para aplicativos existentes e fornece diretrizes para manter e migrar seus aplicativos.

Visão geral

O Azure DevOps OAuth 2.0 permite que os aplicativos acessem recursos do Azure DevOps em nome dos usuários. Embora esse serviço seja preterido, os aplicativos existentes continuam funcionando até 2026.

Recomendação de migração: comece a planejar sua migração para o Microsoft Entra ID OAuth para garantir o serviço e o acesso contínuos aos recursos de segurança aprimorados.

Pré-requisitos

Antes de trabalhar com aplicativos OAuth do Azure DevOps:

Trabalhando com aplicativos OAuth do Azure DevOps existentes

1. Gerenciar seu registro de aplicativo existente

Para aplicativos existentes, você pode exibir e gerenciar as configurações do aplicativo:

1. Acesse seu perfil do Visual Studio para acessar os registros do aplicativo.

2. Examine os escopos configurados e verifique se eles correspondem às necessidades do aplicativo.

3. Verifique a configuração da URL de retorno de chamada e atualize se necessário.

   

4. Planeje seu cronograma de migração para o Microsoft Entra ID OAuth antes do prazo de descontinuação de 2026.

2. Autorize seu aplicativo

O fluxo de autorização permanece o mesmo para aplicativos OAuth do Azure DevOps existentes:

1. Direcione os usuários para a URL de autorização com os parâmetros do aplicativo:

   https://app.vssps.visualstudio.com/oauth2/authorize
           ?client_id={app ID}
           &response_type=Assertion
           &state={state}
           &scope={scope}
           &redirect_uri={callback URL}
   

   Parâmetro	Tipo	Descrição
   client_id	GUID	A ID atribuída ao seu aplicativo quando ele foi registrado
   response_type	cadeia	Precisa ser Assertion
   state	cadeia	Um valor de cadeia de caracteres gerado que correlaciona o retorno de chamada com sua solicitação de autorização
   scope	cadeia	Escopos separados por espaço registrados no aplicativo. Consulte os escopos disponíveis
   redirect_uri	URL	URL de retorno de chamada para seu aplicativo. Deve corresponder exatamente à URL registrada com o aplicativo

   URL de autorização de exemplo:

   https://app.vssps.visualstudio.com/oauth2/authorize
           ?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
           &response_type=Assertion
           &state=User1
           &scope=vso.work%20vso.code_write
           &redirect_uri=https://fabrikam.azurewebsites.net/myapp/oauth-callback
   

   Após a autorização do usuário, o Azure DevOps redireciona para a sua URL de retorno de chamada com o código de autorização.

   https://fabrikam.azurewebsites.net/myapp/oauth-callback
           ?code={authorization code}
           &state=User1
   

3. Código de autorização do Exchange para token de acesso

Use o código de autorização para solicitar um token de acesso e atualizar o token:

Solicitar detalhes

URL

POST https://app.vssps.visualstudio.com/oauth2/token

cabeçalhos

Content-Type: application/x-www-form-urlencoded

Corpo da solicitação

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}

Substituição de parâmetro:

• {0}: segredo do cliente codificado em URL do registro do aplicativo
• {1}: autorização codificada em URL do callback
• {2}: URL de retorno de chamada registrada no aplicativo

Exemplo de implementação de C#

public string GenerateRequestPostData(string appSecret, string authCode, string callbackUrl)
{
   return String.Format("client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}",
               HttpUtility.UrlEncode(appSecret),
               HttpUtility.UrlEncode(authCode),
               callbackUrl
        );
}

Resposta

{
    "access_token": "{ access token for the user }",
    "token_type": "{ type of token }",
    "expires_in": "{ time in seconds that the token remains valid }",
    "refresh_token": "{ refresh token to use to acquire a new access token }"
}

4. Use o token de acesso

Inclua o token de acesso como um token de portador em suas solicitações de API:

Formato do cabeçalho de autorização:

Authorization: Bearer {access_token}

Solicitação de API de exemplo:

GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0
Authorization: Bearer {access_token}

5. Atualizar tokens de acesso expirados

Quando os tokens de acesso expirarem, use o token de atualização para obter um novo token de acesso:

Pedir:

POST https://app.vssps.visualstudio.com/oauth2/token
Content-Type: application/x-www-form-urlencoded
Content-Length: 1654

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2}

Substituição de parâmetro:

• {0}: segredo do cliente codificado em URL
• {1}: token de atualização codificado em URL
• {2}: URL de retorno de chamada registrada no aplicativo

Resposta:

{
    "access_token": "{ new access token }",
    "token_type": "{ type of token }",
    "expires_in": "{ time in seconds that the token remains valid }",
    "refresh_token": "{ new refresh token }"
}

Exemplos de código

Você pode encontrar exemplos de trabalho em nosso repositório de exemplos de autenticação do Azure DevOps.

Gerenciando segredos do aplicativo

Os aplicativos OAuth do Azure DevOps oferecem suporte a segredos duplos para habilitar a rotação de tempo de inatividade zero:

Alternar segredos

1. Gere um novo segredo em seu perfil do Visual Studio ou por meio das APIs do Segredo de Registro.

   

2. Confirme a ação na caixa de diálogo modal.

   

3. Atualize seu aplicativo para usar o novo segredo antes que o antigo expire.

4. Teste o novo segredo completamente antes que o segredo antigo expire.

5. Repita o processo quando o novo segredo estiver próximo do vencimento.

Revogação de segredo de emergência

Se um segredo estiver comprometido:

1. Regenere imediatamente o segredo em seu perfil.
2. Atualize seu aplicativo com o novo segredo.
3. Monitore o acesso não autorizado nos logs do seu aplicativo.

Excluir seu aplicativo

Para excluir um aplicativo OAuth do Azure DevOps:

1. Acesse seu perfil do Visual Studio.

2. Selecione o locatário correto no menu suspenso.

3. Localize seu aplicativo em Aplicativos e serviços.

4. Selecione Excluir na página de registro do aplicativo.

   

5. Confirme a exclusão na caixa de diálogo modal.

Após a exclusão, o aplicativo e todos os seus tokens param de funcionar imediatamente.

Planejamento da migração

Lista de verificação de migração

• [ ] Examine a documentação do Microsoft Entra ID OAuth
• [ ] Identificar todos os aplicativos usando o OAuth do Azure DevOps em sua organização
• [ ] Planejar a linha do tempo de migração permitindo tempo de teste adequado
• [ ] Atualizar a arquitetura do aplicativo para dar suporte ao Microsoft Entra ID OAuth
• [ ] Testar a migração em um ambiente de não produção
• [ ] Comunicar alterações a usuários e stakeholders
• [ ] Concluir a migração antes do prazo final de 2026

Benefícios da migração

Recursos de segurança aprimorados:

• Suporte à autenticação multifator
• Políticas de acesso condicional
• Proteção avançada contra ameaças
• Integração de identidade empresarial

Melhor experiência do desenvolvedor:

• Bibliotecas de autenticação modernas (MSAL)
• Plataforma de identidade consistente entre os serviços da Microsoft
• Melhor gerenciamento e cache de token

Suporte a longo prazo:

• Investimento contínuo e desenvolvimento de funcionalidades
• Recursos de conformidade e governança da empresa

Perguntas frequentes

P: Ainda posso criar novos aplicativos OAuth do Azure DevOps?

R: Não. Novos registros de aplicativo pararam em abril de 2025. Use Microsoft Entra ID OAuth para novos aplicativos.

P: Quando meu aplicativo OAuth do Azure DevOps existente deixará de funcionar?

R: Os aplicativos existentes continuam funcionando até que o OAuth do Azure DevOps seja totalmente preterido em 2026. Planeje sua migração bem antes desta data limite.

P: Posso usar o OAuth com aplicativos móveis?

R: O OAuth do Azure DevOps dá suporte apenas ao fluxo do servidor Web e requer armazenamento seguro de segredos do cliente, tornando-o inadequado para aplicativos móveis. O Microsoft Entra ID OAuth fornece melhor suporte ao aplicativo móvel.

P: O que devo fazer se receber um erro HTTP 400 ao solicitar tokens?

R: As causas comuns incluem:

• Cabeçalho incorreto Content-Type (deve ser application/x-www-form-urlencoded)
• Parâmetros do corpo da solicitação malformados
• Código de autorização inválido ou expirado
• URL de retorno de chamada incompatível

P: Por que recebo erros HTTP 401 com tokens OAuth, mas não com PATs?

R: Verifique se o administrador da sua organização desabilitou o acesso a aplicativos de terceiros por meio do OAuth em: https://dev.azure.com/{your-org-name}/_settings/organizationPolicy

Quando desabilitado, os fluxos de autorização do OAuth funcionam, mas as chamadas à API retornam TF400813: The user "<GUID>" is not authorized to access this resource.

P: Posso usar o localhost para teste?

R: Sim. O Azure DevOps OAuth dá suporte a URLs de callback https://localhost para desenvolvimento e teste local.

P: Como posso lidar com negações e revogações de autorização?

R: Implementar o tratamento de erros adequado para:

• Negação de autorização: nenhum código de autorização é retornado no retorno de chamada
• Autorização revogada: chamadas à API retornam erros 401; solicitar novamente a autorização do usuário

P: Qual é a diferença entre o OAuth do Azure DevOps e o Microsoft Entra ID OAuth?

R:

• OAuth do Azure DevOps: descontinuado, específico do Azure DevOps, com recursos de segurança limitados
• Microsoft Entra ID OAuth: moderno, de nível empresarial, segurança aprimorada, suporte a longo prazo

Próximas etapas

Para aplicativos existentes:

Para novos aplicativos:

Conteúdo relacionado

• Escolha seu método de autenticação
• Migrar para o Microsoft Entra ID OAuth
• Examinar os escopos do OAuth 2.0 para o Azure DevOps
• Gerenciar autorizações de aplicativo
• Explorar a referência da API REST do Azure DevOps
• Saiba mais sobre segurança e identidade no Azure DevOps