検索
Close
カテゴリー内の他の記事

OAuthクライアントの使用（β）

作成日
更新日
サイト更新情報をフォロー
API更新情報をフォロー
フォローする

Index


OAuth 2.0を使用して、アプリケーションからcybozu.comへのAPIリクエストを承認することができます。
クライアントタイプはConfidential Client、グラントタイプはAuthorization Code Grant（認可コードグラント）のみに対応しています。

こちらの機能は動作を保証するものではありません。 

OAuthクライアントをcybozu.comに登録する

cybozu.comへのAPIリクエストを認証するために使用できるOAuthクライアントを登録する必要があります。

  1. 「cybozu.com共通管理」画面にアクセスします。
  2. 「cybozu.com共通管理」画面の「システム管理」の、「外部連携」をクリックします。
  3. 「高度な連携を設定する」の、「OAuth クライアントの追加」をクリックします。

    OAuth__________.png

     
  4. 以下の情報を入力します。
    • クライアント名：必須。クライアントの名前です。
    • クライアントロゴ：省略可。クライアントのロゴ画像です。
    • リダイレクトエンドポイント：必須。OAuthクライアントが認可コードを受け取るURLです。ユーザーがcybozu.comへのアクセスを認可した後にこのURLにリダイレクトされます。

      OAuth_________.png

  5. 「保存」をクリックすると、クライアントが追加され、次の項目が自動的に生成されます。
    • クライアントID：アプリケーションをcybozu.comに登録したときに生成される一意のIDです。
    • クライアントシークレット：アプリケーションをcybozu.comに登録したときに生成されるシークレット値です。
    • 認可エンドポイント：OAuthの認可エンドポイントURLです。
    • トークンエンドポイント：OAuthのトークンエンドポイントURLです。
  6. 追加したクライアントの「連携利用ユーザーの設定」をクリックします。
    __________.png

  7. 「連携利用ユーザーの設定」画面で、OAuthを利用を許可するユーザーにチェックを入れ、「保存」をクリックします。
    この設定が有効になっているユーザーのみ、OAuthクライアントを利用可能です。

    ___________.png

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

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

Authorization Code Grant Flow（認可コードグラントフロー）

_____.png

API実行のために必要な手順は次の通りです。

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

以下、curlでOAuthプロトコルの各種APIを実行する手順の例です。

1. 認可要求

クライアントとしてユーザーに認可を求めるため、以下のURLにアクセスします。
例では、スコープに「g:schedule:read」を指定します。

  • client_id：必須。クライアントIDを指定します。
  • redirect_uri：必須。リダイレクトエンドポイントを指定します。URLエンコードしてください。
  • state：必須。OAuth 2.0の仕様に従って、CSRF対策のためのランダムな値を指定します。例では、「state1」を指定します。
  • response_type：必須。codeを指定します。
  • scope：必須。スコープを指定します。スコープはこちらを参照してください。
https://{subdomain}.cybozu.com/oauth2/authorization
?client_id={your_client_id}&redirect_uri={your_redirect_url}&state=state1&response_type=code&scope=g%3aschedule%3aread

2. ユーザーによる認可

以下のような認可画面が表示されるので「許可」をクリックして認可要求を承認します。

________.png

3. 認可コードの取得

認可が承認されたら、リダイレクトURLに遷移します。
その際、stateパラメータとcodeパラメータが付与されており、codeパラメータが認可コードに該当します。
codeパラメータの部分をコピーしておきます。

{your_redirect_url}?code={your_code}&state=state1

4. アクセストークンの要求・取得

取得した認可コードを使って、アクセストークンを取得します。
下記のcurlコマンドを実行します。
codeには先の手順でコピーしたcodeを使います。

  • grant_type：必須。authorization_codeを指定します。
  • redirect_uri：必須。リダイレクトエンドポイントを指定します。URLエンコードしてください。
  • code：必須。認可コードを指定します。
  • client_id：クライアントIDを指定します。OAuthクライアントの認証にBasic認証を用いる場合は不要です。
  • client_secret：クライアントシークレットを指定します。OAuthクライアントの認証にBasic認証を用いる場合は不要です。
curl -X POST 
-H "Content-Type: application/x-www-form-urlencoded" "https://{subdomain}.cybozu.com/oauth2/token"
-d "grant_type=authorization_code&
    redirect_uri={your_redirect_url}&
    code={your_code}&
    client_id={your_client_id}&
    client_secret={your_client_secret}"

# response 
{
 "access_token" : "P8RSOtjFudcBkpPMjcFKjkxIy_XdctPG",
 "refresh_token" : "p51R155m0aj-XR2WV1TABR5NA9s3TAT0",
 "token_type" : "bearer",
 "expires_in" : 3600,
 "scope" : "g:schedule:read"
}

レスポンスにaccess_tokenが含まれるので、これを使ってAPIが実行できます。
アクセストークンの有効期限は1時間です。
アクセストークンの期限が切れた場合は、リフレッシュトークンを使って新しいアクセストークンを取得することが出来ます。

curl -X POST 
-H "Content-Type: application/x-www-form-urlencoded" "https://{subdomain}.cybozu.com/oauth2/token"
-d "grant_type=refresh_token&
    refresh_token={your_refresh_token}&
    client_id={your_client_id}&
    client_secret={your_client_secret}"

# response 
{
 "access_token":"2YotnFZFEjr1zCsicMWpAA",
 "token_type" : "bearer",
 "expires_in":3600,
 "scope" : "g:schedule:read"
}

補足: client_idとclient_secretを用いたクライアント認証は、POSTのパラメータ以外にBasic認証にも対応しています。

5. APIの実行

取得したアクセストークンを使ってAPIを実行します。 アクセストークンはAuthorizationヘッダにBearerトークンとして指定します。 1.認可要求リクエストに指定したスコープのAPIしか実行できません。

例では、「/v1/schedule/events/{id}」を実行します。

curl -H "Authorization: Bearer {your_access_token}" "https://{subdomain}.cybozu.com/g/api/v1/schedule/events/{id}"

# response
{
  "id": [...]
}

スコープ

kintone

Scope 説明

k:app_record:read

アプリのレコードの取得

k:app_record:write

アプリのレコードの登録、更新、削除

k:app_settings:read

アプリの設定の取得

k:app_settings:write

アプリの設定の変更

k:file:read

ファイルのダウンロード

k:file:write

ファイルのアップロード

Garoon

Scope 説明

g:schedule:read

スケジュール予定、施設、施設グループの取得

g:schedule:write

スケジュール予定の登録、更新、削除

g:notification:read

通知の取得

g:notification:write

通知の登録

g:base:read

ユーザー、組織情報の取得

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

OAuthクライアント機能はcybozu.com共通管理のBasic認証やセキュアアクセスが必要な環境からは利用できません。
利用するには『OAuthクライアント』のIPアドレスを許可する必要があります。

制限事項

  • OAuthクライアントは最大で20個まで登録できます。
  • リフレッシュトークンは１ユーザー１OAuthクライアントごとに10個まで取得できます。
  • 認可コードとアクセストークンには有効期限があります。 有効期限が切れるとエラーを返します。
    • 認証コードの有効期間は10分です。
    • アクセストークンの有効期限は1時間です。

記事に関するフィードバック

直接的に記事と関連がないご質問はcybozu developer コミュニティをご活用ください。

ログインしてコメントを残してください。