OAuth クライアントを追加する

STEP1：OAuth クライアントを追加する

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

cybozu.com 共通管理を開きます。
「OAuth」をクリックします。
「高度な連携を設定する」セクションで、【OAuth クライアントの追加】をクリックします。
OAuth クライアントの情報を入力します。
- クライアント名：クライアントの名前（必須）
- クライアントロゴ：クライアントのロゴ画像ファイル（省略可）
- リダイレクトエンドポイント： OAuth クライアントが認可コードを受け取る URL（必須）
  ユーザーが cybozu.com へのアクセスを認可した後に、リダイレクトされる URL です。
【保存】をクリックします。
追加した OAuth クライアントの【編集】をクリックします。
OAuth クライアント ID などの次の情報をメモしておきましょう。
STEP3：OAuth認証フローをアプリケーションに実装するの手順で利用します。
- クライアント ID ：アプリケーションを cybozu.com へ登録したときに生成される一意の ID
- クライアントシークレット：アプリケーションを cybozu.com へ登録したときに生成されるシークレット値
- 認可エンドポイント： OAuth の認可エンドポイント URL
- トークンエンドポイント： OAuth のトークンエンドポイント URL

続けて、OAuth クライアントを利用できるユーザーを設定します。

STEP2：連携利用ユーザーを設定する

ユーザーが OAuth クライアントを利用して認証するには、利用するユーザーをあらかじめ指定してください。
OAuth クライアントを作成した後に新規で追加したユーザーが、OAuth クライアントを利用する場合は、「連携利用ユーザーの設定」で対象のユーザーを指定してください。

OAuth クライアントを利用できるユーザーを設定します。追加したクライアントで、「連携利用ユーザーの設定」をクリックします。
OAuth を利用を許可するユーザーのチェックボックスを選択します。
【保存】をクリックします。

STEP3：OAuth認証フローをアプリケーションに実装する

cybozu.com では Authorization Code Grant（認可コードグラント）を利用します。

API を実行するまでに必要な手順は、次のとおりです。

認可要求
ユーザーによる認可
認可コードの取得
アクセストークンの要求・取得
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 スコープ
  - Garoon の OAuth スコープ

リクエストの例

例では、スコープに 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」ヘッダーを指定します。
ヘッダーの値は「Basic 」と「クライアント 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 を実行するときの認証に用いるアクセストークンです。
アクセストークンの有効期限は、1 時間です。

アクセストークンの有効期限が切れた場合

refresh_token を使って、新しくアクセストークンを取得し直してください。
リフレッシュトークンには、有効期限がありません。
リフレッシュトークンを使って、アクセストークンを取得する例は、次のとおりです。

grant_type：refresh_token（必須）
refresh_token：アクセストークンの要求・取得で取得したリフレッシュトークン（必須）
code：認可コードの取得で取得した認可コード（必須）

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


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": "YOUR_ACCESS_TOKEN",
#  "token_type": "bearer",
#  "expires_in": 3600,
#  "scope": "g:schedule:read"
# }

5. APIの実行

取得したアクセストークンを使って、REST API を実行するには、リクエストヘッダーに「Authorization」ヘッダーを指定します。
ヘッダーの値は「Bearer 」とアクセストークンを結合した値です。

指定したスコープで許可されている 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" : {
    ...
  },
  ...
}

cybozu.com 共通管理の IP アドレス制限を利用している場合

OAuth を利用した認証を利用するには、cybozu.com 共通管理で、クライアントアプリケーションの IP アドレスを許可してください。
IP アドレスを許可する設定の詳細は、 IP アドレス制限の設定を参照してください。

制限事項

パッケージ版 Garoon では、OAuth クライアントの追加、および OAuth クライアントを使用した API の実行はできません。
OAuth クライアントは、20 個まで登録できます。
リフレッシュトークンは、1 ユーザー 1 OAuth クライアントごとに 10 個まで取得できます。
認可コードとアクセストークンには、有効期限があります。
有効期限が過ぎた場合は、取得し直してください。
- 認証コードの有効期間： 10 分
- アクセストークンの有効期限： 1 時間

cybozu.com 共通 API ドキュメント