Uso de Azure DevOps OAuth 2.0

Azure DevOps Services

En este artículo se explica cómo funciona OAuth 2.0 de Azure DevOps para las aplicaciones existentes y se proporcionan instrucciones para mantener y migrar las aplicaciones.

Información general

Azure DevOps OAuth 2.0 permite a las aplicaciones acceder a los recursos de Azure DevOps en nombre de los usuarios. Aunque este servicio está en desuso, las aplicaciones existentes seguirán funcionando hasta 2026.

Recomendación de migración: empiece a planear la migración a Microsoft Entra ID OAuth para garantizar el servicio continuo y el acceso a las características de seguridad mejoradas.

Prerrequisitos

Antes de trabajar con aplicaciones de OAuth de Azure DevOps:

Trabajar con aplicaciones de OAuth de Azure DevOps existentes

1. Administrar el registro de aplicaciones existente

En el caso de las aplicaciones existentes, puede ver y administrar la configuración de la aplicación:

1. Vaya al perfil de Visual Studio para acceder a los registros de aplicaciones.

2. Revise los ámbitos configurados y asegúrese de que coinciden con las necesidades de la aplicación.

3. Verifique la configuración de la URL de devolución de llamada y actualice si es necesario.

   

4. Planee su cronograma de migración a Microsoft Entra ID OAuth antes de la fecha límite de desuso en 2026.

2. Autorice la aplicación

El flujo de autorización sigue siendo el mismo para las aplicaciones de OAuth de Azure DevOps existentes:

1. Dirija a los usuarios a la dirección URL de autorización con los parámetros de la aplicación:

   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	Descripción
   client_id	GUID	El identificador asignado a la aplicación cuando se registró
   response_type	cuerda / cadena	Debe ser Assertion
   state	cuerda / cadena	Valor de cadena generado que relaciona la llamada de retorno con su solicitud de autorización
   scope	cuerda / cadena	Ámbitos separados por espacios registrados en la aplicación. Consulte los ámbitos disponibles.
   redirect_uri	URL	URL de devolución de llamada de la aplicación. Debe coincidir exactamente con la dirección URL registrada con la aplicación.

   Dirección URL de autorización de ejemplo:

   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
   

   Después de la autorización del usuario, Azure DevOps lo redirige a la URL de devolución de llamada con el código de autorización:

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

3. Código de autorización de Exchange para el token de acceso

Use el código de autorización para solicitar un token de acceso y un token de actualización:

Detalles de la solicitud

URL

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

Encabezados

Content-Type: application/x-www-form-urlencoded

Cuerpo de la solicitud

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}

Sustitución de parámetros:

• {0}: secreto de cliente con codificación URL desde el registro de aplicaciones
• {1}: código de autorización con codificación URL desde la devolución de llamada
• {2}: URL de callback registrada en la aplicación

Ejemplo de implementación de C#

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

{
    "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 el token de acceso

Incluya el token de acceso como token de portador en las solicitudes de API:

Formato de encabezado de autorización:

Authorization: Bearer {access_token}

Solicitud de API de ejemplo:

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

5. Actualizar tokens de acceso expirados

Cuando expiren los tokens de acceso, use el token de actualización para obtener un nuevo token de acceso:

Solicitud:

POST https://app.vssps.visualstudio.com/oauth2/token
Content-Type: application/x-www-form-urlencoded
Content-Length: 1654

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

Sustitución de parámetros:

• {0}: secreto de cliente con codificación URL
• {1}: token de actualización con codificación URL
• {2}: URL de callback registrada en la aplicación

Respuesta:

{
    "access_token": "{ new access token }",
    "token_type": "{ type of token }",
    "expires_in": "{ time in seconds that the token remains valid }",
    "refresh_token": "{ new refresh token }"
}

Ejemplos de código

Puede encontrar ejemplos de trabajo en nuestro repositorio de ejemplos de autenticación de Azure DevOps.

Administración de secretos de aplicación

Las aplicaciones de OAuth de Azure DevOps admiten secretos duales para habilitar la rotación sin tiempo de inactividad:

Girar secretos

1. Genere un nuevo secreto en el perfil de Visual Studio o a través de las API de secreto de registro.

   

2. Confirme la acción en el cuadro de diálogo modal.

   

3. Actualice la aplicación para usar el nuevo secreto antes de que expire el anterior.

4. Pruebe el nuevo secreto exhaustivamente antes de que expire el secreto anterior.

5. Repita el proceso cuando el nuevo secreto se acerque a la expiración.

Revocación de secretos de emergencia

Si un secreto está en peligro:

1. Regenera inmediatamente el secreto en tu perfil.
2. Actualice la aplicación con el nuevo secreto.
3. Supervise el acceso no autorizado en los registros de la aplicación.

Eliminar la aplicación

Para eliminar una aplicación de OAuth de Azure DevOps:

1. Vaya al perfil de Visual Studio.

2. Seleccione el inquilino correcto en el menú desplegable.

3. Busque la aplicación en Aplicaciones y servicios.

4. Seleccione Eliminar en la página de registro de la aplicación.

   

5. Confirme la eliminación en el cuadro de diálogo modal.

Después de la eliminación, la aplicación y todos sus tokens dejan de funcionar inmediatamente.

El planeamiento de la migración

Lista de comprobación para la migración

• [ ] Revisar la documentación de OAuth de Microsoft Entra ID
• [ ] Identificación de todas las aplicaciones con OAuth de Azure DevOps en su organización
• [ ] Planear la escala de tiempo de migración que permite un tiempo de prueba adecuado
• [ ] Actualizar la arquitectura de la aplicación para admitir microsoft Entra ID OAuth
• [ ] Prueba de la migración en un entorno que no es de producción
• [ ] Comunicar los cambios a los usuarios y las partes interesadas
• [ ] Completar la migración antes de la fecha límite de 2026

Ventajas de la migración

Características de seguridad mejoradas:

• Compatibilidad con la autenticación multifactor
• Directivas de acceso condicional
• Protección contra amenazas avanzada
• Integración de identidades empresariales

Mejor experiencia para desarrolladores:

• Bibliotecas de autenticación modernas (MSAL)
• Plataforma de identidad coherente en todos los servicios de Microsoft
• Mejor administración y almacenamiento en caché de tokens

Soporte técnico a largo plazo:

• Inversión continua y desarrollo de características
• Características de cumplimiento y gobernanza empresariales

Preguntas más frecuentes

P: ¿Puedo crear nuevas aplicaciones de OAuth de Azure DevOps?

R: No. Los nuevos registros de aplicaciones se detuvieron en abril de 2025. Use Microsoft Entra ID OAuth para las nuevas aplicaciones.

P: ¿Cuándo dejará de funcionar mi aplicación de OAuth de Azure DevOps existente?

R: Las aplicaciones existentes siguen funcionando hasta que Azure DevOps OAuth está totalmente en desuso en 2026. Planee la migración antes de esta fecha límite.

P: ¿Puedo usar OAuth con aplicaciones móviles?

R: Azure DevOps OAuth solo admite el flujo del servidor web y requiere almacenamiento seguro de secretos de cliente, lo que hace que no sea adecuado para las aplicaciones móviles. Microsoft Entra ID OAuth proporciona una mejor compatibilidad con aplicaciones móviles.

P: ¿Qué debo hacer si obtengo un error HTTP 400 al solicitar tokens?

R: Entre las causas comunes se incluyen las siguientes:

• Encabezado incorrecto Content-Type (debe ser application/x-www-form-urlencoded)
• Parámetros del cuerpo de la solicitud incorrectamente formateados
• Código de autorización no válido o expirado
• La URL de callback no coincide

P: ¿Por qué obtengo errores HTTP 401 con tokens de OAuth pero no con PAT?

R: Compruebe si el administrador de la organización deshabilitó el acceso a aplicaciones de terceros a través de OAuth en: https://dev.azure.com/{your-org-name}/_settings/organizationPolicy

Cuando está deshabilitado, los procesos de autorización OAuth funcionan, pero las llamadas a la API devuelven TF400813: The user "<GUID>" is not authorized to access this resource.

P: ¿Puedo usar localhost para realizar pruebas?

A. Sí. OAuth de Azure DevOps admite las URL de devolución de llamada https://localhost para desarrollo y pruebas locales.

P: ¿Cómo puedo controlar las revocaciones y denegaciones de autorización?

R: Implemente el control de errores adecuado para:

• Denegación de autorización: no se devuelve ningún código de autorización en la devolución de llamada.
• Autorización revocada: las llamadas API devuelven errores 401; volver a solicitar la autorización del usuario

P: ¿Cuál es la diferencia entre Azure DevOps OAuth y Microsoft Entra ID OAuth?

A.

• Azure DevOps OAuth: características de seguridad limitadas y en desuso, específicas de Azure DevOps
• Microsoft Entra ID OAuth: Seguridad moderna, de nivel empresarial, seguridad mejorada y soporte técnico a largo plazo

Pasos siguientes

Para las aplicaciones existentes:

Para las nuevas aplicaciones:

Contenido relacionado

• Elección del método de autenticación
• Migración a Microsoft Entra ID OAuth
• Revisión de ámbitos de OAuth 2.0 para Azure DevOps
• Administración de autorizaciones de aplicaciones
• Exploración de la referencia de la API REST de Azure DevOps
• Más información sobre la seguridad y la identidad en Azure DevOps