Documentos de API

Cómo agregar clientes de OAuth

OAuth 2.0 se puede usar para autenticar aplicaciones que se encuentran fuera de Kintone para ejecutar solicitudes de API de Kintone. OAuth 2.0 proporciona una forma segura para que la aplicación acceda a los datos de Kintone, ya que no requiere que los usuarios almacenen su usuario y contraseñas de Kintone en la aplicación.

Para usar OAuth 2.0 con Kintone, primero debe registrar su aplicación con Kintone. Su aplicación deberá admitir el flujo de autorización de OAuth para obtener el token de acceso que se puede usar para ejecutar las API de Kintone.

Para obtener más información sobre OAuth 2.0, consulte el sitio oficial: OAuth 2.0 (External link)

Contenido

Registre su aplicación en Kintone

Su aplicación primero debe registrarse en Kintone a través de la Integración para generar las credenciales de OAuth. Siga los pasos a continuación para registrar su solicitud:

  1. Inicie sesión en Kintone, haga clic en el icono de ajustes en el menú superior derecho de Kintone y navegue hasta el Administración de usuarios y sistemas página.

  2. Haga clic en OAuth debajo Administración del sistema.

  3. Haga clic en el botón verde Agregar cliente OAuth debajo de Configurar servicios avanzados.

  4. Introduzca los detalles del cliente OAuth.

    • Nombre del cliente (obligatorio): El nombre de la aplicación. Los usuarios verán este nombre cuando se les pida que concedan acceso a la aplicación.
    • Logotipo del cliente (Opcional): El logotipo de la aplicación. Los usuarios verán este logotipo cuando se les pida que concedan acceso a la aplicación.
    • Punto de conexión de redireccionamiento (obligatorio): La URL a la kintone.com redirigirá al usuario después de conceder acceso a la aplicación.

  5. Clic Salvar agregará el cliente y se generará automáticamente la siguiente información:

    • ID de cliente: Un identificador único que se crea cuando la aplicación se registra en kintone.com.
    • Secreto de cliente: Valor secreto que se crea cuando la aplicación se registra en kintone.com.
    • Punto de conexión de autorización: La dirección URL del punto de conexión de autorización de OAuth.
    • Punto de conexión del token: La dirección URL del punto de conexión del token de OAuth.

  6. Haga clic en Configurar usuarios junto al cliente agregado, para establecer qué usuarios de su dominio de Kintone tienen permiso para interactuar con el cliente. Cuando el cliente se registra inicialmente en kintone.com, de forma predeterminada, ningún usuario puede interactuar con la aplicación hasta que se les conceda permiso a través de esta configuración.

  7. Del Configurar usuarios configuración, elija qué usuarios podrán interactuar con el cliente para procesar el flujo de OAuth y haga clic en guardar. El cliente OAuth solo se habilitará para aquellos que estén seleccionados con la casilla de verificación en esta configuración.

    Tenga en cuenta que cuando se crea un nuevo usuario en Kintone, la casilla de verificación para el nuevo usuario está desactivada de forma predeterminada y el cliente OAuth está deshabilitado para el usuario.

Implementación del marco de autorización de OAuth en la aplicación

kintone.com utiliza concesiones de código de autorización para el flujo de proceso de OAuth.

Flujo de concesión de código de autorización

Los pasos necesarios para ejecutar una API de Kintone son los siguientes:

  1. Solicitud de autorización
  2. Aprobación del usuario
  3. Recuperación del código de autorización
  4. Solicitud de token de acceso
  5. Ejecución de API

En los pasos siguientes se muestra un ejemplo de ejecución de cada tipo de API de protocolo OAuth mediante curl.

1. Solicitud de autorización

Se accede a la siguiente URL para solicitar la autorización como cliente del usuario. A modo de ejemplo, K:app_record:read se especifica en el ámbito.

1
2

https://{subdomain}.kintone.com/oauth2/authorization
?client_id={your_client_id}&redirect_uri={your_redirect_url}&state=state1&response_type=code&scope=k%3Aapp_record%3Aread

Los detalles de los parámetros son los siguientes:

Parámetro Obligatorio Descripción
client_id Sí El ID de cliente único.
redirect_uri Sí El punto de conexión de redireccionamiento. Asegúrese de codificar la URL.
state Sí Un valor aleatorio para evitar CSRF como se define en OAuth 2.0
características técnicas. En este ejemplo, se especifica el valor "state1".
response_type Sí Especificar code.
scope Sí El ámbito de aplicación. Consulte el siguiente artículo para obtener más detalles sobre el ámbito:
Ámbitos de permisos de OAuth
Al especificar varios ámbitos, cada ámbito debe estar separado por una coma.

2. Aprobación del usuario

En la siguiente página que aparece, haga clic en Conceder para aprobar la solicitud de autorización.

El usuario será navegado a la Punto de conexión de redireccionamiento URL, especificada en el paso 4 de la siguiente sección:
Registre su aplicación en Kintone

3. Recuperación del código de autorización

Cuando se aprueba la autorización, el navegador accede a la URL de redireccionamiento. El state y el parámetro code se agregan a la URL. Trate el code como código de autorización. Copie el archivo code parámetro.

1

{your_redirect_url}?code={your_code}&state=state1

4. Solicitud de token de acceso

El token de acceso se genera mediante el código de autorización recuperado.

Los detalles de los parámetros necesarios son los siguientes:

Encabezado de solicitud

En el caso de la Authorization , establezca el valor conectando los siguientes valores:

  • La cadena "Basic"
  • Un ID de cliente y un secreto de cliente codificados en Base64, con el formato "ClientID:ClientSecret"

Por ejemplo, si el identificador de cliente es "clientid" y el secreto de cliente es "clientsecret", especifique "Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0".

Cuerpo de la solicitud

Parámetro Obligatorio Descripción
grant_type Sí Especificar authorization_code.
redirect_uri Sí El punto de conexión de redireccionamiento, que debe ser el mismo valor indicado en el paso 1. Asegúrese de codificar la URL.
code Sí El código de autorización recuperado en el paso anterior.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

curl -X POST https://{subdomain}.kintone.com/oauth2/token \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -H "Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0" \
 -d "grant_type=authorization_code&redirect_uri={your_redirect_url}&code={your_code}"

# response
{
   "access_token" : "P8RSOtjFudcBkpPMjcFKjkxIy_XdctPG",
   "refresh_token" : "p51R155m0aj-XR2WV1TABR5NA9s3TAT0",
   "token_type" : "bearer",
   "expires_in" : 3600,
   "scope" : "k:app_record:read"
}

El token de acceso se incluye en la respuesta que se puede usar para llamar a la API. Los tokens de acceso son válidos para 1 hora. Si el token de acceso caduca, utilice el comando refresh token para generar un nuevo token de acceso. El token de actualización no tiene fecha de expiración.

Los detalles de los parámetros necesarios para usar el token de actualización son los siguientes:

Parámetro Obligatorio Descripción
grant_type Sí refresh_token
refresh_token Sí Token de actualización obtenido de la siguiente sección:
Solicitud de token de acceso

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

curl -X POST https://{subdomain}.kintone.com/oauth2/token \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -H "Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0" \
 -d "grant_type=refresh_token&refresh_token={your_refresh_token}"

# response
{
   "access_token":"2YotnFZFEjr1zCsicMWpAA",
   "token_type" : "bearer",
   "expires_in":3600,
   "scope" : "k:app_record:read"
}

5. Ejecución de API

Ejecute la API de Kintone con el token de acceso recuperado configurando el token de acceso en el archivo Authorization: Bearer encabezado. Solo las API definidas en el ámbito se pueden usar con este token de acceso.

En el siguiente ejemplo, el método Obtener API de registro se ejecuta.

1
2
3
4
5
6

curl -H "Authorization: Bearer {your_access_token}" "https://{subdomain}.kintone.com/k/v1/record.json?app={appID}&id={recordID}"

# response
{
  "record": [...]
}

Para obtener más información sobre Obtener API de registro, consulte el siguiente artículo:
Obtener registro

Notas importantes

  • Las características del cliente OAuth no se pueden usar desde dominios de Kintone que usan Restricciones de IP, a menos que la IP del cliente OAuth esté incluida en la lista blanca en la configuración de restricción de IP. Para obtener más información sobre Restricciones de IP+, consulte el siguiente artículo de la ayuda de Kintone:
    Restricciones de direcciones IP (External link)
  • Los tokens de actualización no caducan.

Limitaciones

  • Se pueden registrar hasta 20 clientes OAuth
  • Se pueden generar hasta 10 tokens de actualización a partir de 1 cliente OAuth para 1 usuario.
  • Los códigos de autorización y los tokens de acceso tienen tiempos de caducidad. Los códigos/tokens caducados devolverán errores.
    • Los códigos de autorización son válidos para: 10 minutos.
    • Los tokens de acceso son válidos para 1 hora.