How to add OAuth clients

 

OAuth 2.0 can be used to authenticate applications that lie outside of Kintone to run Kintone API requests. OAuth 2.0 provides a secure way for your application to access Kintone data, as it does not require users to store their Kintone user and passwords on the application.

To use OAuth 2.0 with Kintone, you must first register your application with Kintone. Your application will need to support the OAuth authorization flow to obtain the access token that can be used to run Kintone's APIs.

Register your application to Kintone

Your application must first be registered to Kintone through the Integration settings to generate the OAuth credentials. Follow the steps below to register your application:

  1. Log into Kintone and navigate to the User & System Administration page.

  2. Click on Integrations under System Administration.

  3. Click on the green Add OAuth client button under Set up advanced services.

    oauth1.png

  4. Enter in the details of the OAuth client.

    oauth2.png

    • Client name (required): The name of the application. Users will view this name when they are asked to grant access to your application.
    • Client logo (optional): The logo of the application. Users will view this logo when they are asked to grant access to your application.
    • Redirect endpoint (required): The URL where kintone.com will redirect the user to, after granting access to the application.


  5. Clicking Save will add the client and the following information will be automatically generated:
    • Client ID: A unique ID that is created when your application is registered to kintone.com.
    • Client secret: A secret value that is created when your application is registered to kintone.com.
    • Authorization endpoint: The URL of the OAuth authorization endpoint.
    • Token endpoint: The URL of the OAuth token endpoint.


  6. Click on Set allowed users next to the added client, to set which users in your Kintone domain have permission to interact with the client. When the client is initially registered to kintone.com, by default no users are able to interact with the application, until they are given permission through this setting.

    setupadvancedservices.png

  7. From the Set Allowed Users settings screen, choose which users will be able to interact with the client to process the OAuth flow and click save. The OAuth client will only be enabled for those who are selected with the check box in this setting.

    __________2018-11-08___7.41.02.png

Implementing the OAuth Authorization Framework to your Application

kintone.com uses Authorization Code Grants for the OAuth process flow.

Authorization Code Grant Flow

OAuth___.png


The steps necessary for running a Kintone API are as follows:

  1. Authorization request
  2. User approval
  3. Authorization code retrieval
  4. Access token request
  5. API Execution

The next steps show an example of running each OAuth protocol API type using curl.

1. Authorization request

The following URL is accessed in order to request authorization as the client from the user. As an example, k:app_record:read is specified in the scope.

The details of the parameters are as follows:

  • client_id (required): The unique client ID.
  • redirect_uri (required): The redirect endpoint. Make sure to encode the URL.
  • state (required): A random value in order to prevent CSRF as is defined in the OAuth 2.0 specifications. In this example, the value "state1" is specified.
  • response_type (required): Specify code.
  • scope (required): The scope. Refer to the Scope section for more details on the scope.

2. User approval

On the following page that appears, click Allow to approve the authorization request.

authenticateclient.PNG

3. Authorization code retrieval

When the authorization is approved, the browser accesses the redirect URL. The state parameter and the code parameter are added to the URL. Treat the code parameter as the authorization code. Copy the code parameter.

4. Access token request

The access token is generated using the retrieved authorization code.
Run the following curl command. For the code parameter, use the code that was copied from the previous step.

The details of the parameters are as follows:

  • grant_type (required): Specify authorization_code.
  • redirect_uri (required): The redirect endpoint, which must be the same value stated in Step 1. Make sure to encode the URL.
  • code (required): The authorization code.
  • client_id: The unique client ID.
  • client_secret: The client secret.

The access token is included in the response which can be used to run the API. Access tokens are valid for 1 hour. If the access token expires, use the refresh token to generate a new access token.

Note that instead of including the client_id and client_secret in the POST parameter of the request, they can be included in the Authorization: Basic header.

5. API Execution

Run the Kintone API using the retrieved access token by setting the access token in the Authorization: Bearer header. Only the APIs defined in the scope can be used with this access token.

In the example below, the Get Record API "/v1/record.json?app={appID}&id={recordID}" is run.

Scopes

Kintone

Scope Description
k:app_record:read View records
k:app_record:write Add, edit, or delete records
k:app_settings:read View the Kintone App settings
k:app_settings:write Change the Kintone App settings

 

Important Notes

OAuth client features cannot be used from Kintone domains that use IP restrictions, unless the IP of the OAuth Client is white-listed on the IP restriction settings.

Limitations

  • Up to 20 OAuth clients can be registered
  • Up to 10 refresh tokens can be generated from 1 OAuth client for 1 user..
  • Authorization codes and access tokens have expiry times. Expired codes/tokens will return errors.
    • Authorization codes are valid for 10 minutes.
    • Access tokens are valid for 1 hour.
Was this article helpful?
0 out of 0 found this helpful
Do you have any questions or issues related to this article?
Please share your views with us in the Community forums!