Uso de Azure DevOps OAuth 2.0 para crear una aplicación web
Azure DevOps Services
Importante
Azure DevOps OAuth está programado para desuso en 2026. Esta información es solo para las aplicaciones de OAuth de Azure DevOps existentes. Para crear nuevas aplicaciones, use OAuth de Microsoft Entra ID para integrarse con Azure DevOps. A partir de febrero de 2025, dejaremos de aceptar nuevas aplicaciones de OAuth de Azure DevOps. Obtenga más información en nuestra entrada de blog.
Azure DevOps es un proveedor de identidades para aplicaciones de OAuth 2.0. Nuestra implementación de OAuth 2.0 permite a los desarrolladores autorizar su aplicación para los usuarios y obtener tokens de acceso para los recursos de Azure DevOps.
Introducción a OAuth de Azure DevOps
1. Registrar la aplicación
Importante
La nueva creación de aplicaciones se bloqueará a partir de febrero de 2025.
Vaya a para
https://app.vsaex.visualstudio.com/app/registerregistrar la aplicación.Seleccione los ámbitos que necesita la aplicación y, a continuación, use los mismos ámbitos al autorizar la aplicación. Si registró la aplicación con las API de versión preliminar, vuelva a registrarse porque los ámbitos que usó están en desuso.
Seleccione Crear aplicación.
Se muestra la página de configuración de la aplicación.
Cuando Azure DevOps Services presenta la página de aprobación de autorización al usuario, usa el nombre de la empresa, el nombre de la aplicación y las descripciones. También usa las direcciones URL del sitio web de la empresa, el sitio web de la aplicación y los términos de servicio y las declaraciones de privacidad.
Cuando Azure DevOps Services solicita la autorización de un usuario y el usuario lo concede, el explorador del usuario se redirige a la dirección URL de devolución de llamada de autorización con el código de autorización. La dirección URL de devolución de llamada debe ser una conexión segura (https) para volver a transferir el código a la aplicación y coincidir exactamente con la dirección URL registrada en la aplicación. Si no es así, se muestra una página de error 400 en lugar de una página que pide al usuario que conceda autorización a la aplicación.
Llame a la dirección URL de autorización y pase el identificador de la aplicación y los ámbitos autorizados cuando quiera que un usuario autorice a la aplicación para acceder a su organización. Llame a la dirección URL del token de acceso cuando desee obtener un token de acceso para llamar a una API de REST de Azure DevOps Services.
La configuración de cada aplicación que registre está disponible en el perfil https://app.vssps.visualstudio.com/profile/view.
2. Autorización de la aplicación
- Si el usuario no autorizó a la aplicación a acceder a su organización, llame a la dirección URL de autorización. Le llama de nuevo con un código de autorización, si el usuario aprueba la autorización.
https://app.vssps.visualstudio.com/oauth2/authorize
?client_id={app ID}
&response_type={Assertion}
&state={state}
&scope={scope}
&redirect_uri={callback URL}
- Agregue un vínculo o un botón al sitio que lleve al usuario al punto de conexión de autorización de 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 pide al usuario que autorice la aplicación.
Suponiendo que el usuario acepta, Azure DevOps Services redirige el explorador del usuario a la dirección URL de devolución de llamada, incluido un código de autorización de corta duración y el valor de estado proporcionado en la dirección URL de autorización:
https://fabrikam.azurewebsites.net/myapp/oauth-callback
?code={authorization code}
&state=User1
3. Obtener un token de acceso y actualización para el usuario
Use el código de autorización para solicitar un token de acceso (y un token de actualización) para el usuario. El servicio debe realizar una solicitud HTTP de servicio a servicio a Azure DevOps Services.
Dirección URL: autorización de la aplicación
POST https://app.vssps.visualstudio.com/oauth2/token
Encabezados de solicitud HTTP: autorización de la aplicación
| Encabezado | Valor |
|---|---|
| Content-Type | application/x-www-form-urlencoded |
Content-Type: application/x-www-form-urlencoded
Cuerpo de la solicitud HTTP: autorización de la aplicación
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}
Reemplace los valores de marcador de posición en el cuerpo de la solicitud de ejemplo anterior:
- {0}: secreto de cliente codificado con dirección URL adquirido cuando se registró la aplicación.
- {1}: dirección URL codificada como "código" proporcionada a través del parámetro de consulta a la
codedirección URL de devolución de llamada. - {2}: dirección URL de devolución de llamada registrada con la aplicación
Ejemplo de C# para formar el cuerpo de la solicitud: autorización de la aplicación
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
);
}
Respuesta: autorización de la aplicación
{
"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 }
}
Nota:
Conserve de forma segura el refresh_token para que la aplicación no necesite pedir al usuario que lo autorice de nuevo. Los tokens de acceso expiran rápidamente y no deben conservarse.
4. Uso del token de acceso
Para usar un token de acceso, inclúyalo como token de portador en el encabezado autorización de la solicitud HTTP:
Authorization: Bearer {access_token}
Por ejemplo, la solicitud HTTP para obtener compilaciones recientes para un proyecto:
GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0
Authorization: Bearer {access_token}
5. Actualizar un token de acceso expirado
Si expira el token de acceso de un usuario, puede usar el token de actualización que adquirió en el flujo de autorización para obtener un nuevo token de acceso. Es como el proceso original para intercambiar el código de autorización de un token de acceso y actualización.
Dirección URL: token de actualización
POST https://app.vssps.visualstudio.com/oauth2/token
Encabezados de solicitud HTTP: token de actualización
| Encabezado | Valor |
|---|---|
| Content-type | application/x-www-form-urlencoded |
| Longitud del contenido | Longitud calculada de la cadena del cuerpo de la solicitud (consulte el ejemplo siguiente) |
Content-Type: application/x-www-form-urlencoded
Content-Length: 1654
Cuerpo de la solicitud HTTP: token de actualización
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2}
Reemplace los valores de marcador de posición en el cuerpo de la solicitud de ejemplo anterior:
- {0}: secreto de cliente codificado con dirección URL adquirido cuando se registró la aplicación.
- {1}: token de actualización con codificación URL para el usuario
- {2}: dirección URL de devolución de llamada registrada con la aplicación
Respuesta: token de actualización
{
"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 }
}
Nota:
Se emite un nuevo token de actualización para el usuario. Conserve este nuevo token y úselo la próxima vez que necesite adquirir un nuevo token de acceso para el usuario.
Ejemplos
Puede encontrar un ejemplo de C# que implemente OAuth para llamar a las API REST de Azure DevOps Services en nuestro ejemplo de GitHub de OAuth de C#.
Regeneración del secreto de cliente
Cada cinco años, el secreto de aplicación expira. Vuelva a generar el secreto de la aplicación para seguir creando y usando tokens de acceso y tokens de actualización. Para ello, seleccione "Regenerar secreto", que confirma que desea completar esta acción.
Al confirmar que desea volver a generar, el secreto de la aplicación anterior ya no funciona y todos los tokens anteriores que se mintieron con este secreto también dejan de funcionar. Asegúrese de que esta rotación de secretos de cliente esté bien para minimizar el tiempo de inactividad de los clientes.
Eliminar la aplicación
Si ya no necesita la aplicación, elimínela del perfil.
Vaya a su perfil en:
https://app.vssps.visualstudio.com/profile/view.Asegúrese de que está en la página correcta del inquilino seleccionando en el menú desplegable debajo del nombre de la barra lateral.
Busque la aplicación en el encabezado Aplicaciones y servicios de la barra lateral izquierda.
Seleccione "Eliminar" en la página de registro de la aplicación. Aparece un modal para confirmar la eliminación.
Una vez eliminado el registro de la aplicación, la aplicación se interrumpe y dejamos de usar nuevos tokens o aceptamos tokens minted para esta aplicación.
Preguntas más frecuentes (P+F)
P: ¿Puedo usar OAuth con mi aplicación de teléfono móvil?
R: No. Azure DevOps Services solo admite el flujo de servidor web, por lo que no hay ninguna manera de implementar OAuth, ya que no se puede almacenar de forma segura el secreto de la aplicación.
P: ¿Qué errores o condiciones especiales necesito controlar en mi código?
R: Asegúrese de controlar las condiciones siguientes:
- Si el usuario deniega el acceso a la aplicación, no se devuelve ningún código de autorización. No use el código de autorización sin comprobar si hay denegación.
- Si el usuario revoca la autorización de la aplicación, el token de acceso ya no es válido. Cuando la aplicación usa el token para acceder a los datos, se devuelve un error 401. Vuelva a solicitar autorización.
P: Quiero depurar mi aplicación web localmente. ¿Puedo usar localhost para la dirección URL de devolución de llamada al registrar mi aplicación?
A. Sí. Azure DevOps Services ahora permite localhost en la dirección URL de devolución de llamada. Asegúrese de usar https://localhost como principio de la dirección URL de devolución de llamada al registrar la aplicación.
P: Obtengo un error HTTP 400 cuando intento obtener un token de acceso. ¿Qué podría ser malo?
R: Compruebe que establece el tipo de contenido en application/x-www-form-urlencoded en el encabezado de solicitud.
P: Obtengo un error HTTP 401 cuando uso un token de acceso basado en OAuth, pero un PAT con el mismo ámbito funciona bien. ¿Por qué?
R: Compruebe que el administrador de la organización no deshabilitó el acceso a aplicaciones de terceros a través de OAuth en https://dev.azure.com/{your-org-name}/_settings/organizationPolicy.
En este escenario, el flujo para autorizar una aplicación y generar un token de acceso funciona, pero todas las API REST devuelven solo un error, como TF400813: The user "<GUID>" is not authorized to access this resource.