使用 OAuth 2.0 授權對 cybozu.com 服務的 API 請求。
用戶端類型對應於機密用戶端。
授權類型對應於授權代碼授予。

添加 OAuth 用戶端以使用 OAuth 用戶端對 cybozu.com 的 API 請求進行身份驗證。
只有 .com 公共管理員才能新增 OAuth 用戶端。

1. cybozu.com 開放中央管理。

2. 點擊 OAuth。
   

   

3. 在「配置高級集成」部分中，按兩下「添加 OAuth 用戶端」。
   

   

4. 輸入 OAuth 客戶端資訊。

   • 用戶端名稱：用戶端名稱（必填）
   • 用戶端徽標：用戶端徽標圖像檔（選擇）
   • 重定向端點：OAuth 用戶端接收授權代碼的 URL（必填）
     用戶在授權訪問 cybozu.com 後重定向到的URL。

   

5. 點擊保存。

6. 按下您添加的 OAuth 用戶端的鉛筆形編輯圖示。

   

7. 記下以下資訊，例如 OAuth 用戶端 ID：
   步驟3：在應用程式中實現 OAuth 身份驗證流程 在此過程中使用。

   • 用戶端 ID ：向 cybozu.com 註冊應用程式時生成的唯一 ID
   • 客戶端密碼：向 cybozu.com 註冊應用程式時生成的金鑰值
   • 授權端點：OAuth 授權端點 URL
   • 令牌終結點：OAuth 令牌終結點 URL

   

接下來，配置可以使用 OAuth 用戶端的使用者。

通過在「訂閱者設置」中使用 OAuth 用戶端進行身份驗證來指定將運行 API 的使用者。
如果要定位創建用戶端后添加的使用者，請每次都將其設置為使用者。

1. 設置可以使用 OAuth 用戶端的使用者。 在您添加的用戶端中，按兩下訂閱者設置。
   

   

2. 選中要允許使用 OAuth 的用戶的複選框。
   

   

3. 點擊保存。

cybozu.com 使用授權代碼授予。

執行 API 所需的步驟如下：

1. 授權請求
2. 允許使用者編輯
3. 取得記錄
4. 請求和檢索訪問令牌
5. 執行 API

以下示例介紹使用curl獲取訪問令牌並執行Garoon REST API的步驟。

1. 授權請求

授權請求要求使用者授予用戶端應用程式訪問信息的許可權。
向授權終端節點 URL 授予以下 URL 查詢以存取授權終端節點：

• client_id： 在添加 OAuth 用戶端中添加了用戶端 ID（必需）
• redirect_uri： 添加 OAuth 用戶端中指定的重定向終結點（必需）
  • URL 必須經過 URL 編碼。
• state：CSRF 對策的隨機值（必填）
  在此示例中，指定了"state1"。在實踐中， 請遵循 OAuth 2.0 規範 並指定一個隨機值。
• response_type：code（必填）
• scope：範圍（必填）
  • 如果指定多個，請用空格分隔它們。
  • 有關可以指定的範圍的清單，請參閱以下內容：
    • kintone中的OAuth Scopes

示例請求

在這裡範例中，作用域指定為 g:schedule:read

1

https://sample.cybozu.com/oauth2/authorization?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&state=state1&response_type=code&scope=g:schedule:read

2. 允許使用者編輯

顯示"將從（用戶端名稱）執行以下操作"螢幕時，按下"允許"。

導航到添加 OAuth 用戶端的「重定向終結點」中指定的 URL。

3. 取得記錄

檢查重定向 URL 的末尾，並code= 記下 和 &state=state1 之間的值。
code= 其中給出的值是授權代碼。它用於請求和獲取訪問令牌。

示例 URL

1

YOUR_REDIRECT_URI?code=YOUR_CODE&state=state1

4. 請求和檢索訪問令牌

向令牌終結點發送 POST 請求以獲取訪問令牌。

請求標頭

若要獲取訪問令牌，請在請求標頭中指定"Authorization"標頭。
標頭的值是"基本"和"用戶端 ID:用戶端密碼 Base64 編碼值"的組合。

例如，如果用戶端 ID 為"clientid"，用戶端密碼為"clientsecret"，則"Authorization"標頭的值為"Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0"。

請求正文

• grant_type：authorization_code（必填）
• redirect_uri： 重定向在添加 OAuth 用戶端中指定的終結點（必需）
  • URL 必須經過 URL 編碼。
• code： 獲取 授權碼中獲取的授權碼（必填）

示例請求

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

curl -X POST https://sample.cybozu.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}'

# 回應
# {
#  "access_token" : "P8RSOtjFudcBkpPMjcFKjkxIy_XdctPG",
#  "refresh_token" : "p51R155m0aj-XR2WV1TABR5NA9s3TAT0",
#  "token_type" : "bearer",
#  "expires_in" : 3600,
#  "scope" : "g:schedule:read"
# }

回應中的 access_token 值是執行 API 時用於身份驗證的訪問令牌。
訪問令牌將在一小時後過期。

當訪問令牌過期時會發生什麼情況？

refresh_token 以獲取新的訪問令牌。
刷新令牌不會過期。
以下是使用刷新令牌獲取訪問令牌的範例。

• grant_type：refresh_token（必填）
• refresh_token： 在請求和獲取 訪問令牌中獲取的刷新令牌（必需）

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

curl -X POST https://sample.cybozu.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'

# 回應
# {
#  "access_token" : "P8RSOtjFudcBkpPMjcFKjkxIy_XdctPG",
#  "refresh_token" : "p51R155m0aj-XR2WV1TABR5NA9s3TAT0",
#  "token_type" : "bearer",
#  "expires_in" : 3600,
#  "scope" : "g:schedule:read"
# }

5. API 的執行

要使用獲取的訪問令牌執行 REST API，請在請求標頭中指定"Authorization"標頭。
標頭的值是"Bearer"和訪問令牌的組合。

不能運行指定範圍允許的 API 以外的任何 API。

運行 API 的範例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

curl https://example.cybozu.com/g/api/v1/schedule/events/1 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# 回應
# {
#   "id": "1",
#   "creator" : {
#     ...
#   },
#   ...
# }

若要使用 OAuth 身份驗證，請在 cybozu.com Common Administration 中允許用戶端應用程式的 IP 位址。
有關配置要允許的IP位址的詳細資訊， 請參閱配置 IP位址限制。

• 在Garoon的打包版本中，不能使用OAuth用戶端添加OAuth用戶端或執行API。
• 您最多可以註冊 20 個 OAuth 用戶端。
• 每個使用者最多可以獲取 10 個刷新令牌，一個 OAuth 用戶端。
• 授權代碼和訪問令牌具有到期日期。
  如果到期日期已過，請重新取回。
  • 驗證碼有效期：10 分鐘
  • 訪問令牌過期：1 小時