Búsqueda

Centro de ayuda de integración de InterAction+™

Autorización

  • Actualización

La API en la nube de InterAction+™ utiliza OAuth 2.0 como marco de autorización, lo que permite que las aplicaciones de terceros accedan de forma segura a los datos de usuario de un inquilino, sin que los usuarios tengan que compartir sus contraseñas. La autorización es gestionada por el Servidor de Autorización de InterAction+™, que emite tokens de acceso y de actualización seguros que otorgan acceso controlado a la API en la nube de InterAction+™.

Flujo de autorización OAuth 2.0

Nuestra implementación es compatible con el flujo de concesión de código de autorización de OAuth 2.0, garantizando autenticación y autorización seguras para interacciones entre sistemas. Este flujo asegura que solo los clientes de terceros autenticados y autorizados puedan interactuar de forma segura con la API en la nube de InterAction+™, manteniendo un control estricto sobre los permisos de acceso.

Participantes clave

  • Administrador del inquilino de InterAction+™: Inicia el proceso de autorización para conceder acceso a un cliente de terceros a la API en la nube de InterAction+™. Un administrador debe dar su consentimiento para el acceso a los datos de InterAction+™, asegurando que el acceso a la API solo se otorgue a clientes de terceros autorizados. Además, el administrador debe designar un único usuario para las transacciones de la API. Se recomienda crear y seleccionar un usuario de sistema dedicado, sin datos personales, para este fin.
  • Cliente de terceros: Solicita un token de acceso al Servidor de Autorización de InterAction+™ para interactuar con la API en la nube de InterAction+™ en nombre del inquilino. El acceso solo se concede para los alcances solicitados y dentro de la configuración del cliente de terceros.
  • Proveedor de identidad (IdP) del inquilino: Autentica al administrador del inquilino de InterAction+™ antes de emitir un código de autorización.
  • Servidor de Autorización de InterAction+™: Emite tokens de acceso y de actualización tras una autorización exitosa.

Pasos de autorización

Los pasos descritos desglosan cada solicitud individual realizada al Servidor de Autorización de InterAction+™ durante el flujo de concesión de código de autorización OAuth 2.0. Aunque estos detalles ofrecen una comprensión más profunda del proceso, muchas herramientas (por ejemplo, Postman) y frameworks gestionan estas solicitudes automáticamente. En estos casos, los usuarios solo necesitan configurar la URL de autorización, la URL del token de acceso y la URL del token de actualización para habilitar la autenticación y el intercambio de tokens.

  1. El administrador de inquilinos de InterAction+™ autoriza a un cliente de terceros: Para otorgar acceso a un cliente de terceros a la API en la nube de InterAction+™, el administrador de inquilinos de InterAction+™ debe iniciar el proceso de configuración desde la interfaz del cliente de terceros. Al iniciar este proceso, el cliente de terceros envía una solicitud al endpoint de autorización, lo que solicita al administrador de inquilinos de InterAction+™ que complete los siguientes pasos antes de obtener un código de autorización:
    • Autenticarse con el proveedor de identidad (IdP): El administrador del inquilino de InterAction+™ debe iniciar sesión usando las credenciales de su organización en el IdP para verificar su identidad. Este paso garantiza una autenticación segura antes de conceder el acceso.

    • Conceder consentimiento para el acceso de clientes de terceros: Después de autenticarse, el administrador del inquilino de InterAction+™ revisará y aprobará la solicitud del cliente de terceros para acceder a los datos del inquilino de InterAction+™. 

    • Designar un usuario de API: El administrador del inquilino de InterAction+™ debe asignar un usuario responsable de gestionar las transacciones de la API en la nube de InterAction+™ dentro del inquilino. El administrador del inquilino de InterAction+™ debe asignar un usuario responsable de gestionar las transacciones de la API en la nube de InterAction+™ dentro del inquilino.

    • Endpoint:  

      GET {InterAction+™ Tenant Authority URL}/connect/authorize 

      Parámetro 

      Descripción 
      response_type=code  Solicita un código de autorización.
      client_id  El identificador único del cliente externo.
      redirect_uri  La URL de retorno de OAuth donde se enviará el código de autorización (registrada durante la incorporación del cliente).
      scope  Los permisos solicitados (por ejemplo, openid offline_access public.contact.read).
      state  Un valor aleatorio para prevenir ataques CSRF.

    • Ámbitos: Los ámbitos definen el nivel de acceso otorgado al Cliente de Terceros. El token de acceso a la API de InterAction+™ Cloud emitido por el Servidor de Autorización de InterAction+™ incluye los ámbitos solicitados por el Cliente de Terceros dentro de los límites de su configuración.

      Alcance 

      Descripción 
      openid  Habilita el soporte de OpenID Connect, permitiendo la verificación de identidad.
      offline_access  Permite solicitar un token de actualización, para que el Cliente de Terceros pueda obtener un nuevo token de acceso sin requerir interacción del usuario.
      public.activity.read  Leer actividades
      public.activity.modify  Modificar actividades
      public.contact.read  Leer contactos e información relacionada
      public.contact.modify  Modificar contactos e información relacionada
      public.list.read  Ver listas
      public.list.modify  Modificar listas e información relacionada

    • Ejemplo de solicitud de autorización:  

      {InterAction+™ Tenant Authority URL}/connect/authorize?response_type=code&client_id=third-party-client-id&redirect_uri=https://thirdpartyapp.com/oauth/callback&scope=openid offline_access public.contact.read&state=xyz123 
  2. Intercambiar el código de autorización por tokens de acceso y actualización: Una vez que se obtiene el código de autorización, el cliente de terceros debe intercambiarlo por un token de acceso y un token de actualización haciendo una solicitud al endpoint de tokens.

    • Punto final del token:  

      POST {InterAction+™ Tenant Authority URL}/connect/token 

      Parámetro 

      Descripción 
      grant_type=authorization_code  Especifica el tipo de concesión Authorization Code.
      code  El código de autorización recibido en el paso anterior.
      redirect_uri  La URL de retorno de OAuth donde se enviarán los tokens (registrada durante la incorporación del cliente).
      client_id  El identificador del cliente externo.
      client_secret  El secreto del cliente externo.

    • Ejemplo de solicitud de intercambio de token:

      POST {InterAction+™ Tenant Authority URL}/connect/token
      Content-Type: application/x-www-form-urlencoded
      grant_type=authorization_code&client_id=third-party-client-
id&client_secret=third-party-client-
secret&code=AUTHORIZATION_CODE_FROM_STEP_1&redirect_uri=https://third-
party-app.com/oauth/callback

    • Ejemplo de respuesta de token:

      {
    "id_token": "eyJhbGciOiJIUzI1NiIsInR...",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR...",
    "expires_in": 3600,
    "refresh_token": "def5020072b36c9b...",
    "token_type": "Bearer",
    "scope": "openid public.activity.read …”
}

      Token 

      Description 
      id_token  JWT que contiene la información de autenticación del usuario.
      access_token  Token JWT utilizado para acceder a la API de InterAction+™ Cloud.
      expires_in  Tiempo de expiración del Access Token (en segundos).
      refresh_token  Refresh Token utilizado para solicitar un nuevo Access Token sin interacción del usuario.
      token_type  Siempre Bearer, se utiliza en los encabezados de autorización.
      scope 
             		El nivel de acceso otorgado al Cliente de Terceros.
  3. Realizar solicitudes API con el token de acceso: Una vez que se obtiene el token de acceso, el Cliente de Terceros lo incluye en el encabezado Authorization de las solicitudes API. Este mecanismo garantiza que solo los usuarios autenticados con un token de acceso JWT válido puedan acceder a la InterAction+™ Cloud API.

    • Ejemplo de solicitud API: 

      POST {InterAction+™ Cloud API URL}
      Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR...
      Body: Solicitud GraphQL
  4. Actualización del token de acceso: Dado que los tokens de acceso tienen una vida útil más corta, el token de actualización permite que el Cliente de Terceros obtenga un nuevo token de acceso sin necesidad de que el usuario intervenga.

    • Punto final de token:  

      POST {InterAction+™ Tenant Authority URL}/connect/token 

      Parámetro 

      Descripción 
      grant_type=refresh_token  Especifica el tipo de concesión para obtener el token de actualización.
      refresh_token  El token de actualización recibido en el paso anterior.
      client_id  El identificador del cliente externo.
      client_secret  La clave secreta del cliente externo.

  • Ejemplo de solicitud:

    POST {InterAction+™ Tenant Authority URL}/connect/token 
    Content-Type: application/x-www-form-urlencoded 
    grant_type=refresh_token&client_id=third-party-client-id&client_secret=third-party-client-secret&refresh_token=REFRESH_TOKEN 

  • Ejemplo de respuesta de token de actualización:

    { 
    "id_token": "new_id_token_here",
    "access_token": "new_access_token_here",
    "expires_in": 3600,
    "refresh_token": "new_refresh_token_here",
    "token_type": "Bearer"
     "scope": "openid public.activity.read …”
}

    Token 

    Description 
    id_token  JWT que contiene la información de autenticación del usuario.
    access_token  Token JWT utilizado para acceder a la API de InterAction+™ Cloud.
    expires_in  Tiempo de expiración del Access Token (en segundos).
    refresh_token  Refresh Token utilizado para solicitar un nuevo Access Token sin interacción del usuario.
    token_type  Siempre Bearer, se utiliza en los encabezados de autorización.
    scope  El nivel de acceso otorgado al Cliente de Terceros.

Ciclo de vida del token

  • Vencimiento del Access Token: El Access Token es válido por una hora.
  • Vencimiento del Refresh Token: El Refresh Token es válido por 30 días. Si el Refresh Token vence, el administrador del inquilino de InterAction+™ debe reiniciar el proceso de autorización para obtener nuevos tokens.
  • Revocación de tokens: El administrador del inquilino de InterAction+™ puede revocar los access tokens de un cliente de terceros en cualquier momento, lo que termina inmediatamente el acceso a la API desde la administración del inquilino en CIM. Consulta el Centro de Respuestas de Client Insights para usuarios de Hybrid o SaaS para obtener más información.

Uso del Refresh Token

Nuestra configuración implementa refresh tokens de un solo uso para garantizar una gestión segura de los tokens.

  • Cuando un cliente de terceros utiliza un refresh token para obtener un nuevo access token, se emite un nuevo par de access token y refresh token.
  • El refresh token utilizado previamente se revoca de inmediato y ya no puede usarse.

Si un cliente de terceros envía un refresh token que ya se ha usado o que ha sido reemplazado por un token más reciente, la solicitud fallará con un error porque el token ya no es válido o no está presente en nuestro almacén de tokens.

Mejores prácticas

  • Después de cada actualización exitosa, reemplaza el refresh token almacenado por el nuevo y utiliza solo el token más reciente para futuras solicitudes de actualización.
  • No intentes reutilizar ni volver a usar refresh tokens anteriores.
  • Evita enviar varias solicitudes de actualización en paralelo, ya que la primera solicitud rotará el token y las siguientes que usen el token anterior fallarán.
"Este artículo de ayuda fue traducido con IA y puede contener imprecisiones. Si tienes dudas sobre alguna información, consulta la versión original en inglés."