OAuth 2.0を使用して、cybozu.comのサービスへのAPIリクエストを承認します。
クライアントタイプはConfidential Clientに対応しています。
グラントタイプはAuthorization Code Grant（認可コードグラント）に対応しています。

cybozu.comへのAPIリクエストをOAuthクライアントを使って認証するために、OAuthクライアントを追加します。
OAuthクライアントの追加は、.com共通管理者のみ操作できます。

1. cybozu.com共通管理を開きます。

2. 「OAuth」をクリックします。
   

   

3. 「高度な連携を設定する」セクションで、【OAuthクライアントの追加】をクリックします。
   

   

4. OAuthクライアントの情報を入力します。

   • クライアント名：クライアントの名前（必須）
   • クライアントロゴ：クライアントのロゴ画像ファイル（省略可）
   • リダイレクトエンドポイント： OAuthクライアントが認可コードを受け取るURL（必須）
     ユーザーがcybozu.comへのアクセスを認可した後に、リダイレクトされるURLです。

   

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（必須）
  OAuthクライアントを追加する
• redirect_uri：OAuthクライアントを追加するで指定したリダイレクトエンドポイント（必須）
  OAuthクライアントを追加する
  • URLは、URLエンコードしてください。
• state：CSRF対策のためのランダムな値（必須）
  例では、「state1」を指定しています。実際には、OAuth 2.0の仕様]にしたがって、ランダムな値を指定してください。
  OAuth 2.0の仕様
• response_type：code（必須）
• scope：スコープ（必須）
  複数指定する場合はスペースで区切ります。
  指定できるスコープは、次を参照してください。
  • kintoneのOAuthスコープ
  • 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以外は、実行できません。

以下は、アクセストークンを使って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の実行はできません。
• OAuthクライアントは、20個まで登録できます。
• リフレッシュトークンは、ひとつのOAuthクライアントあたり1ユーザー10個まで取得できます。