Usar o Azure DevOps OAuth 2.0 para criar um aplicativo Web

Azure DevOps Services

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

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.

   

   • 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.

     

   • 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}

2. 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

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

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

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

Amostras

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.

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.

   

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.

Artigos relacionados

• Escolhendo o método de autenticação correto
• Usar o Microsoft Entra ID OAuth
• Permissões e acesso padrão para o Azure DevOps
• Gerenciar autorizações