Usar o Azure DevOps OAuth 2.0 para criar um aplicativo Web

Serviços de DevOps do Azure

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 Azure DevOps OAuth

1. Registe a sua aplicação

1. Aceda a https://app.vsaex.visualstudio.com/app/register para registar a sua aplicação.

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

3. Selecione Criar aplicativo.

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

   

   • Quando os Serviços de DevOps do Azure apresentam a página de aprovação de autorização ao usuário, ele usa o nome da empresa, o nome do aplicativo e as descrições. Ele também usa as URLs do site da sua empresa, do site do aplicativo e dos termos de serviço e declarações de privacidade.

     

   • Quando os Serviços de DevOps do Azure solicitam a autorização de um usuário e o usuário a concede, o navegador do usuário é redirecionado para sua 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. Se isso não acontecer, 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 dos Serviços de DevOps do Azure.

As configurações para cada aplicativo que você registrar 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 seu site que leve o usuário ao ponto de extremidade de autorização dos Serviços de DevOps do Azure:

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

Os Serviços de DevOps do Azure pedem ao usuário para autorizar seu aplicativo.

Supondo que o usuário aceite, os Serviços de DevOps do Azure redirecionam 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 token de atualização) para o usuário. Seu serviço deve fazer uma solicitação HTTP de serviço a serviço para os Serviços de DevOps do Azure.

URL - autorizar aplicação

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}: URL codificado "código" fornecido através do parâmetro de consulta para o code seu URL de retorno de chamada
• {2}: URL de retorno de chamada registrado com o aplicativo

Exemplo de C# para formar o corpo da solicitação - autorizar aplicativo

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 - atualizar token

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 - atualizar token

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 registrado com o aplicativo

Resposta - atualizar token

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

Exemplos

Você pode encontrar um exemplo de C# que implementa OAuth para chamar APIs REST dos Serviços de DevOps do Azure em nosso exemplo de GitHub OAuth em C#.

Regenerar o segredo do cliente

A cada cinco anos, o segredo do seu aplicativo expira. Regenere o segredo do seu aplicativo para continuar a criar e usar tokens de acesso e atualizar tokens. 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 secreta do cliente para minimizar qualquer tempo de inatividade do cliente.

Eliminar a aplicação

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

1. Aceda ao 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 sob o 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 mais frequentes (FAQ)

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

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

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

R: Certifique-se de que lida 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 retorna. Solicite autorização novamente.

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

R: Sim. Os Serviços de DevOps do Azure agora permitem 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 utilizo um token de acesso baseado em OAuth, mas uma PAT com o mesmo âmbito funciona bem. Porquê?

R: Verifique se o administrador da sua organização não desativou 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 predefinidas e acesso ao Azure DevOps
• Gerenciar autorizações