Compartilhar via

Usar o Azure DevOps OAuth 2.0 para criar um aplicativo Web

  • Artigo

Azure DevOps Services

Importante

O OAuth do Azure DevOps está programado para ser preterido em 2026. Essas informações são apenas para aplicativos OAuth existentes do Azure DevOps. Para criar novos aplicativos, use o Microsoft Entra ID OAuth para integração com o Azure DevOps. A partir de fevereiro de 2025, deixaremos de aceitar novos aplicativos OAuth do Azure DevOps. Saiba mais em nossa postagem no blog.

O Azure DevOps é um provedor de identidade para aplicativos OAuth 2.0. Nossa implementação do OAuth 2.0 permite que os desenvolvedores autorizem seu aplicativo para usuários e obtenham tokens de acesso para recursos do Azure DevOps.

Introdução ao OAuth do Azure DevOps

1. Registre seu aplicativo

Importante

A criação de novos aplicativos será bloqueada a partir de fevereiro de 2025.

  1. https://app.vsaex.visualstudio.com/app/register Acesse para registrar seu aplicativo.

  2. Selecione os escopos de que seu aplicativo precisa e use os mesmos escopos ao autorizar seu aplicativo. Se você registrou seu aplicativo usando as APIs de visualização, registre-se novamente porque os escopos usados agora estão preteridos.

  3. Selecione Criar aplicativo.

    A página de configurações do aplicativo é exibida.

    Captura de tela mostrando as configurações de aplicativos para seu aplicativo.

    • Quando Azure DevOps Services apresenta a página de aprovação de autorização ao usuário, ela usa o nome da empresa, o nome do aplicativo e as descrições. Ele também usa as URLs do site da sua empresa, site do aplicativo e termos de serviço e políticas de privacidade.

      Captura de tela mostrando a página de autorização do Visual Studio Codespaces com as informações da sua empresa e do aplicativo.

    • Quando Azure DevOps Services solicita a autorização de um usuário e o usuário a concede, o navegador do usuário é redirecionado para a URL de retorno de chamada de autorização com o código de autorização. O URL de retorno de chamada deve ser uma conexão segura (https) para transferir o código de volta para o aplicativo e corresponder exatamente ao URL registrado em seu aplicativo. Caso contrário, uma página de erro 400 será exibida em vez de uma página solicitando que o usuário conceda autorização ao seu aplicativo.

  4. Chame a URL de autorização e passe a ID do aplicativo e os escopos autorizados quando quiser que um usuário autorize seu aplicativo a acessar sua organização. Chame a URL do token de acesso quando quiser obter um token de acesso para chamar uma API REST do Azure DevOps Services.

As configurações de cada aplicativo que você registra estão disponíveis no seu perfil https://app.vssps.visualstudio.com/profile/view.

2. Autorize seu aplicativo

  1. Se o usuário não autorizou seu aplicativo a acessar sua organização, chame a URL de autorização. Ele liga de volta com um código de autorização, se o usuário aprovar a autorização.
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 Observações
client_id GUID A ID atribuída ao seu aplicativo quando ele foi registrado.
response_type string Assertion
state string Pode ser qualquer valor . Normalmente, um valor de cadeia de caracteres gerado que correlaciona o retorno de chamada com sua solicitação de autorização associada.
scope string Escopos registrados com o aplicativo. Espaço separado. Consulte os escopos disponíveis.
redirect_uri URL URL de retorno de chamada para seu aplicativo. Deve corresponder exatamente à URL registrada no aplicativo.
  1. Adicione um link ou botão ao site que leve o usuário ao ponto de extremidade de autorização Azure DevOps Services:
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

Azure DevOps Services solicita que o usuário autorize seu aplicativo.

Supondo que o usuário aceite, Azure DevOps Services redireciona o navegador do usuário para sua URL de retorno de chamada, incluindo um código de autorização de curta duração e o valor de estado fornecido na URL de autorização:

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

3. Obter um token de acesso e atualização para o usuário

Use o código de autorização para solicitar um token de acesso (e um token de atualização) para o usuário. Seu serviço deve fazer uma solicitação HTTP de serviço a serviço para Azure DevOps Services.

URL - autorizar aplicativo

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

Cabeçalhos de solicitação HTTP - autorizar aplicativo

Cabeçalho Valor
Content-Type application/x-www-form-urlencoded 
Content-Type: application/x-www-form-urlencoded

Corpo da solicitação HTTP - autorizar aplicativo

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}

Substitua os valores de espaço reservado no corpo da solicitação de exemplo anterior:

  • {0}: Segredo do cliente codificado por URL adquirido quando o aplicativo foi registrado
  • {1}: "código" codificado por URL fornecido por meio do code parâmetro de consulta para seu URL de retorno de chamada
  • {2}: URL de retorno de chamada registrada no aplicativo

Exemplo de C# para formar o corpo da solicitação – aplicativo de autorização

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 - autorizar aplicativo

{
    "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 }
}

Observação

Mantenha o refresh_token com segurança para que seu aplicativo não precise solicitar que o usuário autorize novamente. Os tokens de acesso expiram rapidamente e não devem ser mantidos.

4. Use o token de acesso

Para usar um token de acesso, inclua-o como um token de portador no cabeçalho Authorization da sua solicitação HTTP:

Authorization: Bearer {access_token}

Por exemplo, a solicitação HTTP para obter compilações recentes para um projeto:

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

5. Atualizar um token de acesso expirado

Se o token de acesso de um usuário expirar, você poderá usar o token de atualização adquirido no fluxo de autorização para obter um novo token de acesso. É como o processo original para trocar o código de autorização por um token de acesso e atualização.

URL - token de atualização

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

Cabeçalhos de solicitação HTTP - token de atualização

Cabeçalho Valor
Content-type application/x-www-form-urlencoded
Comprimento do conteúdo Comprimento da cadeia de caracteres calculado do corpo da solicitação (consulte o exemplo a seguir) 
Content-Type: application/x-www-form-urlencoded
Content-Length: 1654

Corpo da solicitação HTTP - token de atualização

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

Substitua os valores de espaço reservado no corpo da solicitação de exemplo anterior:

  • {0}: Segredo do cliente codificado por URL adquirido quando o aplicativo foi registrado
  • {1}: Token de atualização codificado por URL para o usuário
  • {2}: URL de retorno de chamada registrada no aplicativo

Resposta - token de atualização

{
    "access_token": { access token for this user },
    "token_type": { type of token },
    "expires_in": { time in seconds that the token remains valid },
    "refresh_token": { new refresh token to use when the token has timed out }
}

Observação

Um novo token de atualização é emitido para o usuário. Mantenha esse novo token e use-o na próxima vez que precisar adquirir um novo token de acesso para o usuário.

Exemplos

Você pode encontrar um exemplo de C# que implementa o OAuth para chamar APIs REST do Azure DevOps Services em nosso exemplo do GitHub do OAuth em C#.

Regenerar segredo do cliente

A cada cinco anos, o segredo do aplicativo expira. Regenere o segredo do aplicativo para continuar a criar e usar tokens de acesso e tokens de atualização. Para fazer isso, selecione "Regenerar segredo", que confirma que você deseja concluir esta ação.

Captura de tela confirmando a regeneração secreta.

Quando você confirma que deseja regenerar, o segredo do aplicativo anterior não funciona mais e todos os tokens anteriores cunhados com esse segredo também param de funcionar. Certifique-se de cronometrar bem essa rotação de segredo do cliente para minimizar qualquer tempo de inatividade do cliente.

Excluir seu aplicativo

Se você não precisar mais do app, exclua-o do seu perfil.

  1. Acesse seu perfil em: https://app.vssps.visualstudio.com/profile/view.

  2. Verifique se você está na página do locatário correto selecionando no menu suspenso abaixo do seu nome na barra lateral.

  3. Encontre o aplicativo no cabeçalho Aplicativos e serviços na barra lateral esquerda.

  4. selecione "Excluir" na página de registro do aplicativo. Um modal aparece para confirmar sua exclusão.

    Captura de tela da página de metadados do aplicativo com o botão excluir destacado

  5. Depois de excluir o registro do aplicativo, o aplicativo é interrompido e paramos de cunhar novos tokens ou aceitar tokens cunhados para este aplicativo.

Perguntas frequentes (FAQs)

P: Posso usar o OAuth com meu aplicativo para celular?

R: Não. Azure DevOps Services dá suporte apenas ao fluxo do servidor Web, portanto, não há como implementar o OAuth, pois você não pode armazenar com segurança o segredo do aplicativo.

P: Quais erros ou condições especiais preciso tratar no meu código?

R: Certifique-se de lidar com as seguintes condições:

  • Se o usuário negar o acesso ao aplicativo, nenhum código de autorização será retornado. Não use o código de autorização sem verificar se há negação.
  • Se o usuário revogar a autorização do aplicativo, o token de acesso não será mais válido. Quando seu aplicativo usa o token para acessar dados, um erro 401 é retornado. Solicite autorização novamente.

P: Quero depurar meu aplicativo Web localmente. Posso usar localhost para a URL de retorno de chamada ao registrar meu aplicativo?

A: Sim. Azure DevOps Services agora permite localhost em sua URL de retorno de chamada. Certifique-se de usar https://localhost como o início do URL de retorno de chamada ao registrar seu aplicativo.

P: Recebo um erro HTTP 400 quando tento obter um token de acesso. O que pode estar errado?

R: Verifique se você definiu o tipo de conteúdo como application/x-www-form-urlencoded no cabeçalho da solicitação.

P: Recebo um erro HTTP 401 quando uso um token de acesso baseado em OAuth, mas um PAT com o mesmo escopo funciona bem. Por quê?

R: Verifique se o administrador da sua organização não desabilitou o acesso a aplicativos de terceiros via OAuth em https://dev.azure.com/{your-org-name}/_settings/organizationPolicy. Nesse cenário, o fluxo para autorizar um aplicativo e gerar um token de acesso funciona, mas todas as APIs REST retornam apenas um erro, como TF400813: The user "<GUID>" is not authorized to access this resource.