使用OAuth2.0授權cybozu.com服務的API請求。
支援的用戶端類型為ConfidentialClient。
支援的授權類型為AuthorizationCodeGrant（授權碼模式）。

授權碼授權流程圖請參閱以下內容。
Step3：在應用程式中實作OAuth認證流程

若要使用OAuth用戶端對cybozu.com的API請求進行認證，需先新增OAuth用戶端。
僅cybozu.com共通管理員才能新增OAuth用戶端。

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

2. 點擊「OAuth」。
   

   

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

   

4. 輸入OAuth用戶端資訊。

   • 用戶端名稱：用戶端名稱（必填）
   • 用戶端標誌：用戶端的標誌圖片（選項）
   • 重導端點（RedirectEndpoint）：OAuth用戶端接收授權碼的URL（必填）
     使用者授權cybozu.com存取後，會被重導至此URL。
     此URL需事先於整合服務中登記／確認。
     • 例：https://app.example.com/oauth/callback

   

5. 點選【儲存】。

6. 在新增的OAuth用戶端列中，點選鉛筆形狀的編輯圖示。

   

7. 記下以下資訊，例如OAuth用戶端ID：
   將在STEP3中使用。
   Step3：在應用程式中實作OAuth認證流程

   • 用戶端ID：在cybozu.com中新增應用程式時產生的唯一ID
   • 用戶端金鑰：在cybozu.com中新增應用程式時產生的金鑰值
   • 授權端點：OAuth授權端點URL
   • 權杖端點：OAuth權杖端點URL

   

接下來，設定允許使用OAuth用戶端的使用者。

在「設定使用者」畫面，可設置允許哪些使用者透過OAuth用戶端進行身份驗證來運行API。
在新增用戶端后，可變更使用者。

1. 設置可以使用OAuth用戶端的使用者。 在您添加的用戶端中，點擊「設定使用者」。
   

   

2. 勾選允許使用OAuth的使用者。
   

   

3. 點選【儲存】。

cybozu.com採用Authorization Code Grant（授權碼模式）。

執行API所需的步驟如下：

1. 授權請求
2. 使用者授權
3. 獲取授權碼
4. 請求/獲取存取令牌
5. API執行

以下示例介紹使用curl獲取存取權杖並執行Garoon REST API的步驟。

1.授權請求

授權請求是向使用者發出請求，要求使用者授權應用程式存取資料。
請將以下URL查詢參數附加至授權端點URL：

• client_id：在「新增OAuth用戶端」中新增的用戶端ID（必要）
  步驟1：新增OAuth用戶端
• redirect_uri：在「新增OAuth用戶端」中指定的重新導向端點（必要）
  步驟1：新增OAuth用戶端
  • URL必須經過URL編碼。
• state：用於CSRF防護的隨機字串（必填）
  在範例中，指定state1。
  在實踐中，請遵循OAuth2.0規範並指定一個隨機值。
  OAuth2.0規範
• response_type：code（必須）
• scope：授權範圍（必填）
  如果指定多個，請用空格分隔它們。
  有關可以指定的範圍的清單，請參閱以下內容：
  • kintone中的OAuthScopes
  • 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。
步驟1：新增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用戶端」中指定的重新導向端點（必要）
  步驟1：新增OAuth用戶端
  URL必須經過URL編碼。
• code：透過「取得授權碼」取得的授權碼（必填）
  3. 取得授權碼

以下是使用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：在「請求/取得存取權杖」中取得的更新權杖（必要）
  4. 請求/取得存取權杖

以下是使用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。

以下是執行使用存取權杖取得Garoon REST API預約的API的範例。

1
2

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

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

• 套裝版Garoon無法新增OAuth用戶端，也無法使用OAuth用戶端執行API。
• 最多可以新增20個OAuth用戶端。
• 一個OAuth用戶端中，一個使用者最多可獲取10個更新權杖。