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:
Log into Kintone and navigate to the User & System Administration page.
Click on Integrations under System Administration.
Click on the green Add OAuth client button under Set up advanced services.
Enter in the details of the OAuth client.
- 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.
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.
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.
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.
Be aware that when a new user is created in Kintone, the check box for the new user is unchecked by default, and the OAuth client is disabled for the user.
Implementing the OAuth Authorization Framework to your Application
kintone.com uses Authorization Code Grants for the OAuth process flow.
Authorization Code Grant Flow
The steps necessary for running a Kintone API are as follows:
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.
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.
The details of the parameters are as follows:
For the Authorization header, set the value by connecting the following values:
- The string "Basic "
- A Base64 encoded Client ID and Client Secret, in the format of "ClientID:ClientSecret"
For example, if the client ID is "clientid" and the client secret is "clientsecret", specify "Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0".
- 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 retrieved in the previous step.
The access token is included in the response which can be used to call the API. Access tokens are valid for 1 hour. If the access token expires, use the refresh token to generate a new access token.
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 is run.
Scope is an OAuth 2.0 mechanism that places a limit on an OAuth token and thus limiting an application's access to a user's account. It does not grant additional permissions beyond the user's access.
For more information on Scopes, refer to OAuth 2.0's Scope article.
|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|
- 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.
- Refresh tokens do not expire.
- 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.