Referencia de puntos de conexión de autorización de OAuth2

Descripción general

Las aplicaciones que utilizan recursos protegidos de Datadog deben ser autorizadas por un usuario antes de que puedan acceder a las API de Datadog en nombre del usuario. Estos endpoints dirigen a la aplicación a través del flujo de concesión de código de autorización.

Solicite autorización a un usuario

GET /oauth2/v1/authorize

Descripción general

Para iniciar el flujo de concesión de código de autorización, una aplicación realiza una solicitud GET al punto de conexión de autorización de Datadog. Esto redirige al usuario al flujo de concesión de autorización de Datadog y muestra una página de consentimiento con la lista de alcances solicitados por su aplicación y una solicitud para que el usuario autorice el acceso. Esto también devuelve el sitio de Datadog desde el cual se realiza la solicitud.

Solicitud

En la solicitud de autorización, la aplicación construye el URI de redireccionamiento añadiendo los siguientes parámetros al componente de consulta del URI utilizando el formato application/x-www-form-urlencoded:

Parámetro de URLDescripción
redirect_uriEl punto de conexión de redireccionamiento de su aplicación después de que un usuario concede o deniega el acceso.
client_idEl ID de cliente de su cliente OAuth2.
response_typeEl tipo de respuesta debe ser code para este flujo de concesión.
code_challenge (si PKCE está habilitado)Una transformación de code_verifier. Datadog recomienda utilizar SHA-256 para calcular el desafío de código.
code_challenge_method (si PKCE está habilitado)Se admite el método utilizado para calcular el desafío de código. SHA-256, o S256.

Ejemplo de solicitud

Para mostrar la página de consentimiento de Datadog, redirija a los usuarios al punto de conexión con los parámetros especificados:

https://app.datadoghq.com/oauth2/v1/authorize?redirect_uri=http://localhost:500/oauth_redirect&client_id=abcdefghijklmnopqrstuvwxyz_123456789&response_type=code&code_challenge=12345&code_challenge_method=S256

Respuesta de éxito

Si un usuario concede correctamente la solicitud de acceso, su aplicación obtiene un código de autorización y redirige al usuario al URI de redireccionamiento con la autorización code, así como el parámetro domain, en el componente de consulta.

Respuesta de error

Si la solicitud falla debido a un redirect_uri o client_id no válido, el usuario no es redirigido al URI especificado; en su lugar, se muestra una página de error de Datadog.

Si un usuario deniega la autorización, o la solicitud falla por otros motivos, el usuario es redirigido al redirect_uri con un parámetro error en el componente de consulta.

Obtener un código de autorización

POST /oauth2/v1/authorize

Descripción general

Cuando un usuario hace clic en el botón Autorizar en la página de consentimiento, se envía automáticamente una solicitud POST al punto de conexión de autorización para verificar la solicitud y devolver un código de autorización único. El usuario es redirigido al redirect_uri de su aplicación con el parámetro de código de autorización en el componente de consulta.

Solicitud

Su aplicación no necesita realizar esta solicitud de autorización. Este paso es una respuesta a la solicitud de autorización de usuario anterior y es solicitado automáticamente por Datadog cuando un usuario autoriza correctamente una aplicación.

Intercambiar código de autorización por token de acceso

POST /api/v2/oauth2/token

Descripción general

Una vez que se devuelve un código de autorización de la solicitud de autorización, su aplicación puede intercambiar este código por un token de acceso y un token de actualización. El código de autorización se extrae del URI de redireccionamiento y se envía en una solicitud POST al punto de conexión de token de OAuth2 de Datadog.

Los tokens de acceso de Datadog son tokens de corta duración con un tiempo de vida (TTL) de 1 hora que otorgan acceso a las API de Datadog. Los tokens de actualización para clientes OAuth de Marketplace son tokens de larga duración sin expiración (TTL de infinito) que se utilizan para obtener automáticamente un nuevo token de acceso cada vez que caduca. Cuando un usuario revoca su autorización, debe volver a autorizar un nuevo conjunto de tokens de acceso y de actualización para la aplicación (el token de actualización caduca).

Solicitud

La solicitud de token de acceso se realiza con los siguientes parámetros en el cuerpo de la solicitud POST con el formato application/x-www-form-urlencoded:

Parámetro de cuerpo HTTPDescripción
redirect_uriEl mismo punto de conexión de redireccionamiento enviado en las solicitudes de autorización.
client_idEl ID de cliente de su cliente OAuth2.
client_secret (si se emitió)El secreto de cliente de su cliente confidencial OAuth2.
grant_typeEl tipo de concesión debe ser authorization_code para recibir su token de acceso y token de actualización iniciales, y el tipo de concesión debe ser refresh_token para recibir cualquier token de acceso y actualización posterior.
code_verifier (si PKCE está habilitado)El verificador de código sin procesar utilizado para derivar el desafío de código enviado en las solicitudes de autorización.
codeEl código de autorización generado y devuelto desde la solicitud POST de autorización anterior.

Ejemplo de solicitud

Utilice este comando cURL para realizar una solicitud de token de acceso:

curl -X POST \
    -d "grant_type=authorization_code&client_id=$CLIENT_ID
    client_secret=$CLIENT_SECRET&redirect_uri=$REDIRECT_URI
    code_verifier=$CODE_VERIFIER&code=$CODE" \
    "https://api.datadoghq.com/api/v2/oauth2/token"

Respuesta de éxito

Si la solicitud de token de acceso es válida y está autorizada, la respuesta del token devuelve un código de estado 200 OK con el token de acceso y el token de actualización contenidos en el cuerpo de la respuesta HTTP.

Respuesta de error

Las solicitudes fallidas realizadas a los puntos de conexión de token deben ser manejadas por la aplicación, como redirigir a los usuarios a una página de error adecuada en la aplicación.

Si un cliente confidencial con un secreto de cliente emitido realiza una solicitud de token sin proporcionar el parámetro client_secret, se devuelve un código de estado 401 Unauthorized.

Si una solicitud de token falla por otros motivos, como una solicitud mal formada o un código de autorización no válido, se devuelve un código de estado 400 Bad Request (a menos que se especifique lo contrario) con un parámetro error.

Revocar tokens

POST /oauth2/v1/revoke

Descripción general

Los usuarios pueden revocar los tokens de acceso o de actualización en cualquier momento. Cuando se revocan, los tokens ya no se pueden usar para acceder a las API de Datadog. Para revocar un token determinado, su aplicación realiza una solicitud POST al punto de conexión de revocación de tokens de Datadog.

Solicitud

La solicitud de revocación se realiza con los siguientes parámetros en el cuerpo de la solicitud HTTP POST con el formato application/x-www-form-urlencoded:

Parámetro del cuerpo HTTPDescripción
client_idEl ID de cliente de su cliente OAuth2.
client_secret (si se emitió)El secreto de cliente de su cliente confidencial OAuth2.
tokenLa cadena de token que se va a revocar.
token_type_hint (opcional)Una sugerencia sobre el tipo de token que se va a revocar para ayudar a optimizar la búsqueda de tokens. Por ejemplo, access_token o refresh_token.

Ejemplo de código

Utilice este comando cURL para realizar una solicitud de revocación:

curl -X POST \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -d 'client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&token=$TOKEN_TO_REVOKE' \
    "https://api.datadoghq.com/oauth2/v1/revoke" \ 

Respuesta de éxito

Si un token se ha revocado correctamente, o si el parámetro token no es válido, la respuesta de revocación devuelve un código de estado 200 OK.

Respuesta de error

Si una solicitud de token falla por cualquier motivo, como parámetros faltantes o no válidos, se devuelve un código de estado 400 Bad Request (a menos que se especifique lo contrario) con un parámetro error.

Crear una clave de API en nombre de un usuario

POST /api/v2/api_keys/marketplace

Descripción general

Una vez que haya recibido un token de acceso o de actualización de OAuth válido, puede usarlo para crear una clave de API en nombre del usuario que autoriza.

Una clave de API, creada a través de este punto de conexión, es la única forma de enviar datos a Datadog a través de OAuth. Solo puede existir una clave de API por organización de Datadog, y el valor de la clave de API se muestra una vez después de la creación, así que guárdelo adecuadamente.

Para acceder a este punto de conexión, el contexto privado API_KEYS_WRITE debe estar asociado con su cliente OAuth.

Si tiene problemas para configurar este contexto, comuníquese con marketplace@datadog.com.

Ejemplo de solicitud

Utilice este comando cURL para realizar una solicitud al punto de conexión api_keys:

curl -X POST \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    "https://api.datadoghq.com/api/v2/api_keys/marketplace"

Respuesta de éxito

Si la solicitud de token de acceso o de token de actualización es válida y está autorizada, se devuelve lo siguiente:

{
  "data": {
    "type": "api_keys",
    "attributes": {
      "created_at": "2021-05-06T16:32:07.411970+00:00",
      "key": "ffffffffffffffffffffffffffffffff",
      "last4": "ffff",
      "modified_at": "2021-05-06T16:32:07.411970+00:00",
      "name": "Marketplace Key for App foobar"
    },
    "relationships": {
      "created_by": {
        "data": {
          "type": "users",
          "id": "abcdefgh-abcd-abcd-abcd-abcdefghijkl"
        }
      },
      "modified_by": {
        "data": {
          "type": "users",
          "id": "abcdefgh-abcd-abcd-abcd-abcdefghijkl"
        }
      }
    },
    "id": "abcdefgh-abcd-abcd-abcd-abcdefghijkl01234"
  }
}

Lecturas adicionales

Documentación, enlaces y artículos útiles adicionales: