Autorización del acceso a las API REST con OAuth 2.0

Azure DevOps Services

Autentique a los usuarios de la aplicación web para el acceso a la API REST, de modo que la aplicación no siga solicitando nombres de usuario y contraseñas. Azure DevOps Services el protocolo OAuth 2.0 para autorizar a la aplicación para un usuario y generar un token de acceso. Use este token al llamar a las API REST desde la aplicación.

Cuando llame a Azure DevOps Services API para ese usuario, use el token de acceso de ese usuario. Los tokens de acceso expiran, por lo que debe actualizar el token de acceso si ha expirado.

Para obtener un ejemplo de C# del flujo general, vea vsts-auth-samples.

Registro de la aplicación

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

Asegúrese de seleccionar 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 registrarla porque los ámbitos que usó ahora están en desuso.

Cuando Azure DevOps Services 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 las declaraciones de términos de servicio y privacidad.

Cuando Azure DevOps Services solicita la autorización de un usuario y el usuario la 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 transferir el código de vuelta a la aplicación. Debe 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.

Al registrar la aplicación, se muestra la página de configuración de 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 desee 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 Azure DevOps Services API REST.

La configuración de cada aplicación que registre está disponible en el perfil https://app.vssps.visualstudio.com/profile/view .

Autorización de la aplicación

Si el usuario aún no ha autorizado a la aplicación para acceder a su organización, llame a la dirección URL de autorización.

https://app.vssps.visualstudio.com/oauth2/authorize
        ?client_id={app ID}
        &response_type={Assertion}
        &state={state}
        &scope={scope}
        &redirect_uri={callback URL}

Azure DevOps Services pide al usuario que autorice la aplicación. Controla la autenticación y, a continuación, le llama con un código de autorización, si el usuario aprueba la autorización.

Agregue un vínculo o botón al sitio que lleve al usuario al punto de conexión Azure DevOps Services autorización:

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 solicita 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

Obtener un token de acceso y actualización para el usuario

Ahora usa 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 para Azure DevOps Services.

Dirección URL: autorización de la aplicación

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

Encabezados de solicitud HTTP: autorizar aplicación

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

Cuerpo de la solicitud HTTP: autorizar 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 en dirección URL adquirido cuando se registró la aplicación
• {1}: el "código" codificado en la dirección URL proporcionado a través del code parámetro de consulta a la 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 }
}

Uso del token de acceso

Para usar un token de acceso, inscluyéndolo como token de portador en el encabezado Authorization 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}

Actualización de 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 para un token de acceso y actualización.

URL: token de actualización

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

Encabezados de solicitud HTTP: token de actualización

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 en 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 }
}

Ámbitos

Registre la aplicación y use ámbitos para indicar qué permisos Azure DevOps Services requiere la aplicación. Cuando los usuarios autorizan a la aplicación a acceder a su organización, la autorizan para esos ámbitos. La solicitud de la autorización pasa los mismos ámbitos que registró.

Para obtener más información, vea Crear datos adjuntos o seguimiento de elementos de trabajo.

Ejemplos

Puede encontrar un ejemplo de C# que implementa OAuth para llamar a Azure DevOps Services API REST en nuestro ejemplo de OAuth GitHub C#.

Preguntas más frecuentes (P+F)

P: ¿Puedo usar OAuth con mi aplicación de teléfono móvil?

A. 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?

A: 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 la 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 como el principio de la dirección URL de https://localhost devolución de llamada al registrar la aplicación.

P: Aparece un error HTTP 400 al intentar obtener un token de acceso. ¿Qué podría estar mal?

A: Compruebe que establece el tipo de contenido en application/x-www-form-urlencoded en el encabezado de solicitud.

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

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

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

A. En primer lugar, obtenga los detalles del elemento de trabajo con la API REST Elementos de trabajo- Obtener 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 parámetro siguiente a la dirección URL:

$expand=all

Con los resultados, obtiene la propiedad de relaciones. 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

Artículos relacionados

• Selección del método de autenticación adecuado
• Permisos y acceso predeterminados para Azure DevOps