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

目次

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

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

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

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:OAuth認証フローをアプリケーションに実装する の手順で利用します。

    • クライアント ID :アプリケーションを cybozu.com へ登録したときに生成される一意の ID
    • クライアントシークレット:アプリケーションを cybozu.com へ登録したときに生成されるシークレット値
    • 認可エンドポイント: OAuth の認可エンドポイント URL
    • トークンエンドポイント: OAuth のトークンエンドポイント URL

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

STEP2:利用者を設定する

OAuth クライアントを使った認証で API を実行するユーザーを、「利用者の設定」で指定します。
クライアント作成後に追加したユーザーも対象とする場合には、都度利用者に設定してください。

  1. OAuth クライアントを利用できるユーザーを設定します。 追加したクライアントで、「利用者の設定」をクリックします。

  2. OAuth を利用を許可するユーザーのチェックボックスを選択します。

  3. 【保存】をクリックします。

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

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

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

  1. 認可要求
  2. ユーザーによる認可
  3. 認可コードの取得
  4. アクセストークンの要求・取得
  5. API の実行

以降の例では、curl を使ってアクセストークンを取得し、Garoon REST API を実行するまでの手順を説明します。

1. 認可要求

認可要求では、ユーザーに、クライアントアプリケーションが情報へアクセスする権限を求めます。
「認可エンドポイント」の URL に次の URL クエリを付与して、認可エンドポイントにアクセスします。

リクエストの例

例では、スコープに 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= で与えられた値が、認可コードです。
次のステップのアクセストークンの取得で利用します。

認可コードの有効期間は 10 分です。
期限が切れた場合は取得し直してください。

URL の例
1
YOUR_REDIRECT_URI?code=YOUR_CODE&state=state1
4. アクセストークンの要求・取得

トークンエンドポイントに POST リクエストを送信して、アクセストークンを取得します。

リクエストヘッダー

アクセストークンを取得するには、リクエストヘッダーに「Authorization」ヘッダーを指定します。
ヘッダーの値は「Basic 」と「クライアント ID:クライアントシークレット を Base64 エンコードした値」を結合した値です。

たとえば、クライアント ID が「clientid」でクライアントシークレットが「clientsecret」の場合、「Authorization」ヘッダーの値は「Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0」です。

リクエストボディ

以下は 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 を使って、アクセストークンを取得し直してください。
リフレッシュトークンには、有効期限がありません。
リフレッシュトークンを使って、アクセストークンを取得する例は、次のとおりです。

以下は 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"

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

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

制限事項

  • パッケージ版 Garoon では、OAuth クライアントの追加、および OAuth クライアントを使用した API の実行はできません。
  • OAuth クライアントは、20 個まで登録できます。
  • リフレッシュトークンは、1 ユーザー 1 OAuth クライアントごとに 10 個まで取得できます。