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個まで取得できます。