Share via

Uso de Azure DevOps OAuth 2.0 para crear una aplicación web

  • Artículo

Azure DevOps Services

Importante

Esta información es solo para las aplicaciones de OAuth de Azure DevOps existentes. Los nuevos desarrolladores de aplicaciones deben usar OAuth de Microsoft Entra ID para integrarse con Azure DevOps.

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

  1. Vaya a para https://app.vsaex.visualstudio.com/app/register registrar la aplicación.

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

  3. Seleccione Crear aplicación.

    Se muestra la página de configuración de la aplicación.

    Screenshot showing Applications settings for your app.

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

      Screenshot showing Visual Studio Codespaces authorization page with your company and app information.

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

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

  1. 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}
Parámetro Tipo Notas
client_id GUID Identificador asignado a la aplicación cuando se registró.
response_type string Assertion
state string Puede ser cualquier valor. Normalmente, un valor de cadena generado que correlaciona la devolución de llamada con su solicitud de autorización asociada.
scope string Ámbitos registrados con la aplicación. Separados por espacios. Consulte los ámbitos disponibles.
redirect_uri URL Dirección URL de devolución de llamada de la aplicación. Debe coincidir exactamente con la dirección URL registrada con la aplicación.
  1. 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=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

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 Value
Tipo de contenido 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 code direcció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 }
}

Importante

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 Value
Tipo de contenido application/x-www-form-urlencoded
Content-Length 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 }
}

Importante

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 5 años, el secreto de aplicación expirará. Se espera que vuelva a generar el secreto de la aplicación para poder crear y usar tokens de acceso y tokens de actualización. Para ello, puede hacer clic en el botón "Regenerar secreto", que mostrará un cuadro de diálogo para confirmar que desea completar esta acción.

Screenshot confirming secret regeneration.

Al confirmar que desea volver a generar, el secreto de la aplicación anterior ya no funcionará y todos los tokens anteriores mintidos con este secreto también dejarán de funcionar. Asegúrese de que esta rotación de secretos de cliente esté bien para minimizar el tiempo de inactividad de los clientes.

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 ha deshabilitado 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.

P: ¿Puedo usar OAuth con los puntos de conexión SOAP y las API REST?

R: No. OAuth solo se admite en las API REST en este momento.

P: ¿Cómo puedo obtener detalles de los datos adjuntos de mi elemento de trabajo mediante las API REST de Azure DevOps?

R: En primer lugar, obtenga los detalles del elemento de trabajo con elementos de trabajo- Obtener la API REST del elemento de trabajo:

GET https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}

Para obtener los detalles de los datos adjuntos, debe agregar el siguiente parámetro a la dirección URL:

$expand=all

Con los resultados, obtendrá la propiedad relations. Allí puede encontrar la dirección URL de los datos adjuntos y, dentro de la dirección URL, puede encontrar el identificador. Por ejemplo:

$url = https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/434?$expand=all&api-version=5.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