Index
OAuth 2.0を使用して、アプリケーションからcybozu.comへのAPIリクエストを承認することができます。
クライアントタイプはConfidential Client、グラントタイプはAuthorization Code Grant(認可コードグラント)のみに対応しています。
OAuthクライアントをcybozu.comに登録する
cybozu.comへのAPIリクエストを認証するために使用できるOAuthクライアントを登録する必要があります。
- 「cybozu.com共通管理」画面にアクセスします。
- 「cybozu.com共通管理」画面の「システム管理」の、「OAuth」をクリックします。
- 「高度な連携を設定する」の、「OAuth クライアントの追加」をクリックします。
- 以下の情報を入力します。
- クライアント名:必須。クライアントの名前です。
- クライアントロゴ:省略可。クライアントのロゴ画像です。
- リダイレクトエンドポイント:必須。OAuthクライアントが認可コードを受け取るURLです。ユーザーがcybozu.comへのアクセスを認可した後にこのURLにリダイレクトされます。
- 「保存」をクリックすると、クライアントが追加され、次の項目が自動的に生成されます。
- クライアントID:アプリケーションをcybozu.comに登録したときに生成される一意のIDです。
- クライアントシークレット:アプリケーションをcybozu.comに登録したときに生成されるシークレット値です。
- 認可エンドポイント:OAuthの認可エンドポイントURLです。
- トークンエンドポイント:OAuthのトークンエンドポイントURLです。
- 追加したクライアントの「連携利用ユーザーの設定」をクリックします。
- 「連携利用ユーザーの設定」画面で、OAuthを利用を許可するユーザーにチェックを入れ、「保存」をクリックします。
この設定が有効になっているユーザーのみ、OAuthクライアントを利用可能です。
デフォルト値は無効になっているため、新規ユーザー追加時にご注意ください。
OAuth認証フローをアプリケーションに実装する
cybozu.comではAuthorization Code Grant(認可コードグラント)を利用します。
Authorization Code Grant Flow(認可コードグラントフロー)
API実行のために必要な手順は次の通りです。
- 認可要求
- ユーザーによる認可
- 認可コードの取得
- アクセストークンの要求・取得
- 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. ユーザーによる認可
以下のような認可画面が表示されるので「許可」をクリックして認可要求を承認します。
3. 認可コードの取得
認可が承認されたら、リダイレクトURLに遷移します。
その際、stateパラメータとcodeパラメータが付与されており、codeパラメータが認可コードに該当します。
codeパラメータの部分をコピーしておきます。
{your_redirect_url}?code={your_code}&state=state1
4. アクセストークンの要求・取得
取得した認可コードを使って、アクセストークンを取得します。
下記のcurlコマンドを実行します。
リクエストヘッダー
- Authorization ヘッダーに、次の値を指定します。
「Basic 」と、クライアントIDとクライアントシークレットを「:」(半角コロン)でつないで Base64 エンコードした値
例えば、クライアント ID が「clientid」でクライアントシークレットが「clientsecret」の場合、「Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0」を指定します。
リクエストボディ
- grant_type:必須。authorization_code を指定します。
- redirect_uri:必須。リダイレクトエンドポイントを指定します。URLエンコードしてください。
- code:必須。3. で取得した認可コードを指定します。
curl -X POST https://{subdomain}.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}"
# 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 https://{subdomain}.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}"
# response
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type" : "bearer",
"expires_in":3600,
"scope" : "g:schedule:read"
}
5. APIの実行
取得したアクセストークンを使ってAPIを実行します。 アクセストークンはAuthorizationヘッダにBearerトークンとして指定します。 1.認可要求リクエストに指定したスコープのAPIしか実行できません。
例では、「/v1/schedule/events/{id}」を実行します。
curl https://{subdomain}.cybozu.com/g/api/v1/schedule/events/{id}
-H "Authorization: Bearer {your_access_token}"
# response
{
"id": [...]
}
スコープ
kintone
Garoon
Scope | 説明 | メソッド | URI |
---|---|---|---|
g:schedule:read |
スケジュール予定、施設、施設グループの取得 |
GET |
|
POST |
|||
g:schedule:write |
スケジュール予定の登録、更新、削除 |
POST |
|
PUT |
|||
PATCH |
|||
DELETE |
|||
g:schedule.facility:read |
管理者による施設または施設グループの取得 |
GET |
|
g:schedule.facility:write |
管理者による施設または施設グループの登録、更新、削除 |
POST |
|
PATCH |
|||
DELETE |
|||
g:workflow:read |
ワークフロー申請データの取得 |
GET |
|
g:workflow.form:read |
ワークフロー申請フォームを構成している項目の取得 |
GET |
|
g:notification:read |
通知の取得 |
GET |
|
g:notification:write |
通知の登録 |
POST |
|
g:base:read |
ユーザー、組織情報の取得 |
GET |
|
g:presence:read |
在席情報の取得 |
GET |
|
g:presence:write |
在席情報の更新 |
PATCH |
|
g:system.api.proxy:read |
プロキシ API 設定の取得 |
GET |
|
g:system.api.proxy:write |
プロキシ API 設定の登録、更新、削除
|
POST |
|
PATCH |
|||
DELETE |
|||
g:system.plugin:read |
プラグインの基本設定の取得 |
GET |
cybozu.com共通管理のIPアドレス制限を利用している場合の注意事項
IP アドレス制限を設定している環境では、OAuth を利用した認証を利用できません。
利用するには、cybozu.com 共通管理で、クライアントアプリケーションの IP アドレスを許可してください。
IP アドレスを許可する設定の詳細は、IP アドレス制限の設定 を参照してください。
制限事項
- パッケージ版 Garoon では、OAuth クライアントの追加、および OAuth クライアントを使用した API の実行はできません。
- OAuthクライアントは最大で20個まで登録できます。
- リフレッシュトークンは1ユーザー1OAuthクライアントごとに10個まで取得できます。
- 認可コードとアクセストークンには有効期限があります。 有効期限が切れるとエラーを返します。
- 認証コードの有効期間は10分です。
- アクセストークンの有効期限は1時間です。
スコープについて「k:space:read」および「k:space:write」を指定するとinvalid_scopeエラーが返ってくるのですが、このスコープ名は正しいでしょうか?
もしくは何かしらのの事情ですでにdeprecatedになっているのでしょうか。
「k:app_record:read」など他のスコープについては正常に返ってくることを確認しております。
よろしくお願い致します。
Takashi Ogiwara 様
お世話になっております。cybozu developer network 運営でございます。
ご指摘頂いた通り、スコープについての記載に誤りがありました。ご迷惑をおかけし申し訳ありません。
現状「k:space:read」「k:space:write」は非対応のため、記事を修正いたしました。
引き続きよろしくお願いいたします。
返信ありがとうございます。スペースのメンバーの取得(以下リンク)を行いたいのですが、現状は不可能という理解であっておりますでしょうか。
もしくは別の認証方法にて使用することができるのでしょうか。
よろしくお願い致します。
https://developer.cybozu.io/hc/ja/articles/202166220
Takashi Ogiwara 様
お世話になっております。cybozu developer network 運営局です。
はい、ご認識の通り、スペースのメンバーについては、OAuth を使った認証では取得できません。
スペースのメンバーの取得 API は、パスワード認証またはセッション認証で利用できます。
https://developer.cybozu.io/hc/ja/articles/201941754#step7
初歩的な質問ですが、oauthユーザーのパスワードを管理者が変更した場合、当該oauthを使用しているプラグインなどは、どうなるのでしょうか?
(トークンが無効になって、再度発行しなければならない?)
スコープについて、ここに書いている以外のURIで使用することはできないのでしょうか?
例えば、カーソルを作成する
のURIはスコープ一覧に掲載されていませんが、OAuthクライアントを使用してAPIによるカーソル作成は可能でしょうか。
また、可能な場合スコープには何を設定すべきでしょうか。
野口 真吾 様
お世話になっております。cybozu developer network 事務局です。
回答にお時間がかかってしまい申し訳ありません。
OAuth クライアントの連携利用ユーザーがパスワードを変更した場合、トークンを再度発行する必要はございません。
Piri-kara 様
お世話になっております。cybozu developer network 事務局です。
回答にお時間がかかってしまい申し訳ありません。
スコープについてのご質問ですが、本記事に記載していない URI は使用することができません。
認可要求先のエンドポイントが以下のように指定されていますが、こちらはクラウド版の場合のように思います。
パッケージ版の場合、認可要求先のエンドポイントはどのように指定すれば良いでしょうか?
Oauth認証を行なった際、access_tokenを取得したユーザのIDを取得する方法はありますでしょうか?
kkaneda 様
お世話になっております。cybozu developer network 事務局です。
回答にお時間をいただき申し訳ありません。
本記事の内容は cybozu.com での操作のため、パッケージ版ではクライアントの追加はできません。
Tsunetomo 様
お世話になっております。cybozu developer network 事務局です。
認可コードを使ってアクセストークンを取得したユーザーの ID を取得することはできません。