Usar o Azure DevOps OAuth 2.0

Serviços de DevOps do Azure

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

Visão geral

O Azure DevOps OAuth 2.0 permite que os aplicativos acessem os recursos do Azure DevOps em nome dos usuários. Embora este serviço tenha sido preterido, as aplicações existentes continuam a funcionar até 2026.

Recomendação de migração: comece a planejar sua migração para o Microsoft Entra ID OAuth para garantir o serviço contínuo e o acesso a 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. Gerencie seu registro de aplicativo existente

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

1. Vá para seu perfil do Visual Studio para acessar seus registros de aplicativo.

2. Revise seus escopos configurados e verifique se eles correspondem às necessidades do seu aplicativo.

3. Verifique a configuração do 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 seu 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	O ID atribuído ao seu aplicativo quando ele foi registrado
   response_type	cadeia (de caracteres)	Deve ser Assertion
   state	cadeia (de caracteres)	Um valor de cadeia de caracteres gerado que correlaciona o retorno de chamada com sua solicitação de autorização
   scope	cadeia (de caracteres)	Escopos separados por espaço registados na aplicação. Veja os escopos disponíveis
   redirect_uri	URL	URL de retorno de chamada para seu aplicativo. Deve corresponder exatamente ao URL registrado com o aplicativo

   Exemplo de URL de autorização:

   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 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 um token de atualização:

Detalhes do pedido

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âmetros:

• {0}: segredo do cliente codificado por URL do registo da aplicação
• {1}: código de autorização codificado em URL do retorno de chamada
• {2}: URL de Callback registada com a aplicação

Exemplo de implementação em 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}

Exemplo de solicitação de API:

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:

Pedido:

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âmetros:

• {0}: segredo do cliente codificado por URL
• {1}: token de atualização codificado por URL
• {2}: URL de Callback registada com a aplicação

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 dão suporte a segredos duplos para permitir a rotação sem tempo de inatividade:

Girar segredos

1. Gere um novo segredo em seu perfil do Visual Studio ou por meio das APIs de 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 antigo expire.

5. Repita o processo quando o novo segredo se aproximar da expiração.

Revogação secreta de emergência

Se um segredo for comprometido:

1. Regenere imediatamente o segredo no seu perfil.
2. Atualize seu aplicativo com o novo segredo.
3. Monitore o acesso não autorizado nos registos da aplicação.

Eliminar a aplicação

Para excluir um aplicativo OAuth do Azure DevOps:

1. Vá para o seu perfil do Visual Studio.

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

3. Encontre 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 imediatamente de funcionar.

Planeamento da migração

Lista de verificação de migração

• [ ] Consulte a documentação do Microsoft Entra ID OAuth
• [ ] Identificar todos os aplicativos que usam o Azure DevOps OAuth em sua organização
• [ ] Planejar o cronograma de migração permitindo um tempo de teste adequado
• [ ] Atualizar a arquitetura do aplicativo para suportar o Microsoft Entra ID OAuth
• [ ] Migração de teste em um ambiente de não produção
• [ ] Comunicar alterações aos utilizadores e partes interessadas
• [ ] Concluir a migração antes do prazo de 2026

Benefícios da migração

Elementos de segurança melhorados:

• Suporte à autenticação multifator
• Políticas de Acesso Condicional
• Proteção avançada contra ameaças
• Integração de identidade corporativa

Melhor experiência de desenvolvedor:

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

Apoio a longo prazo:

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

Perguntas frequentes

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

R: Não. Novos registros de aplicativos pararam em abril de 2025. Use o Microsoft Entra ID OAuth para novas aplicações.

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

R: Os aplicativos existentes continuam a funcionar até que o Azure DevOps OAuth seja totalmente preterido em 2026. Planeie a sua migração bem antes deste prazo.

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

R: O Azure DevOps OAuth suporta apenas o fluxo do servidor Web e requer armazenamento seguro de segredos do cliente, tornando-o inadequado para aplicações móveis. O Microsoft Entra ID OAuth oferece um melhor suporte a aplicativos móveis.

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 inválidos
• 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 desativou o acesso a aplicativos de terceiros via OAuth em: https://dev.azure.com/{your-org-name}/_settings/organizationPolicy

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

P: Posso usar localhost para testes?

R: Sim. O OAuth do Azure DevOps dá suporte a https://localhost endereços de retorno de chamada para desenvolvimento e teste locais.

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

R: Implemente o tratamento adequado de erros para:

• Recusa de autorização: Nenhum código de autorização é retornado no retorno de chamada
• Autorização revogada: as chamadas de API retornam erros 401; Solicitar novamente a autorização do usuário

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

Um:

• Azure DevOps OAuth: Preterido, recursos de segurança limitados específicos do Azure DevOps
• Microsoft Entra ID OAuth: Moderno, de nível empresarial, segurança melhorada, suporte a longo prazo

Próximos passos

Para aplicações existentes:

Para novas aplicações:

Conteúdo relacionado

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