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

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

1. 開啟cybozu.com共通管理員畫面。

2. 點擊「OAuth」。
   

   

3. 在「設定進階整合」部分中，點擊「新增OAuth用戶端」。
   

   

4. 輸入 OAuth 客戶端資訊。

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

   

5. 點擊保存。

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

   

7. 記下以下資訊，例如 OAuth 用戶端 ID：
   在步驟 3 的過程中使用它。
   Step3：在應用程式中實現 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（必填）
  新增 OAuth 用戶端
• redirect_uri：在「新增OAuth用戶端」中指定的重定向終結點（必需）
  新增 OAuth 用戶端
  • URL 必須經過 URL 編碼。
• state：CSRF 度量的隨機值（必填）
  在此示例中，指定了「state1」。在實踐中，請遵循 OAuth 2.0 規範 並指定一個隨機值。
  OAuth 2.0 規範
• response_type：必須
• scope：範圍（必填）
  如果指定多個，請用空格分隔它們。
  有關可以指定的範圍的清單，請參閱以下內容：
  • kintone中的OAuth Scopes
  • Garoon的OAuth範圍

示例請求

在這裡範例中，作用域指定為g:schedule:read
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。
新增 OAuth 用戶端

3. 獲取授權碼

確認重定向 URL 的末尾，並記下code=和 &state=state1 之間的值。
code= 其中給出的值是授權代碼。
它將在下一步中用於獲取訪問令牌。

授權碼的有效期為10分鐘。
如果過期，請重新找回。

示例 URL

1

YOUR_REDIRECT_URI?code=YOUR_CODE&state=state1

4. 請求和獲取訪問令牌

向權杖端點發送 POST 請求以獲取訪問令牌。

請求標頭

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

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

請求內文

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

以下是使用 curl 的請求範例。

1
2
3
4

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_URI&code=YOUR_CODE'

回應內文

傳回包含以下參數的回應：

• access_token：執行 API 時用於身份驗證的訪問令牌
  有效期為1小時。
• refresh_token：刷新令牌，用於在訪問令牌過期時獲取新的訪問令牌
• token_type：令牌類型
  總是bearer指定 .
• expires_in：訪問令牌過期時間（秒）
• scope：訪問令牌中允許的範圍

以下是回應的範例：

1
2
3
4
5
6
7

{
 "access_token" : "YOUR_ACCESS_TOKEN",
 "refresh_token" : "YOUR_REFRESH_TOKEN",
 "token_type" : "bearer",
 "expires_in" : 3600,
 "scope" : "g:schedule:read"
}

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

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

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

以下是使用 curl 的請求範例。

1
2
3
4

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：執行 API 時用於身份驗證的訪問令牌
• token_type：令牌類型
  總是bearer指定 .
• expires_in：訪問令牌過期時間（秒）
• scope：訪問令牌中允許的範圍

1
2
3
4
5
6

{
 "access_token": "YOUR_ACCESS_TOKEN",
 "token_type": "bearer",
 "expires_in": 3600,
 "scope": "g:schedule:read"
}

5. API 的執行

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

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

執行API以使用訪問令牌獲取Garoon REST API的日程預約的示例如下。

1
2

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

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

• 在Garoon的打包版本中，不能使用OAuth用戶端添加OAuth用戶端或執行API。
• 您最多可以註冊 20 個 OAuth 用戶端。
• 每個使用者最多可以獲取 10 個刷新令牌，一個 OAuth 用戶端。