Usar o Azure DevOps OAuth 2.0 para criar um aplicativo Web
Serviços de DevOps do Azure
Importante
Essas informações são apenas para aplicativos OAuth existentes do Azure DevOps. Novos desenvolvedores de aplicativos devem usar o Microsoft Entra ID OAuth para integrar com o Azure DevOps.
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
Aceda a
https://app.vsaex.visualstudio.com/app/registerpara registar a sua aplicação.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.
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.
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
- 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 | Type | Notas |
|---|---|---|
| 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. |
| âmbito | string | Escopos registrados no aplicativo. Espaço separado. 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. |
- 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=88e2dd5f-4e34-45c6-a75d-524eb2a0399e
&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
| Cabeçalho | Value |
|---|---|
| Tipo de Conteúdo | 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}: URL codificado "código" fornecido através do parâmetro de consulta para o
codeseu 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 }
}
Importante
Persista 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 persistentes.
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
| Cabeçalho | Value |
|---|---|
| Tipo de conteúdo | application/x-www-form-urlencoded |
| Comprimento do conteúdo | Comprimento calculado da cadeia de caracteres 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 - 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 }
}
Importante
Um novo token de atualização é emitido para o usuário. Persista 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 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 5 anos, o segredo da sua candidatura expira. Espera-se que você regenere o segredo do aplicativo para continuar a ser capaz de criar e usar tokens de acesso e atualizar tokens. Para fazer isso, você pode clicar no botão "Regenerar segredo", que exibirá uma caixa de diálogo para confirmar que você deseja concluir esta ação.
Quando você confirmar que deseja regenerar, o segredo do aplicativo anterior não funcionará mais e todos os tokens anteriores cunhados com esse segredo também deixarão de funcionar. Certifique-se de cronometrar bem essa rotação secreta do cliente para minimizar qualquer tempo de inatividade do cliente.
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.
P: Posso usar o OAuth com os pontos de extremidade SOAP e APIs REST?
R: Não. O OAuth só é suportado nas APIs REST.
P: Como posso obter detalhes de anexos para meu item de trabalho usando APIs REST do Azure DevOps?
R: Siga os seguintes passos:
Obter os detalhes do item de trabalho com Itens de trabalho - Obter a API REST do item de trabalho:
GET https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}Para obter os detalhes dos anexos, adicione o seguinte parâmetro ao URL:
$expand=allCom os resultados, obtém-se a propriedade das relações. Lá você pode encontrar o URL dos anexos, e dentro do URL você pode encontrar o ID. Por exemplo:
$url = https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/434?$expand=all&api-version=6.0 $workItem = Invoke-RestMethod -Uri $url -Method Get -ContentType application/json $split = ($workItem.relations.url).Split('/') $attachmentId = $split[$split.count - 1] # Result: 1244nhsfs-ff3f-25gg-j64t-fahs23vfs
Artigos relacionados
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários