OAuth クライアントを追加する
OAuth 2.0 を使用して、cybozu.com のサービスへの API リクエストを承認します。
クライアントタイプは Confidential Client に対応しています。
グラントタイプは Authorization Code Grant(認可コードグラント)に対応しています。
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 クライアントを使った認証で API を実行するユーザーを、「利用者の設定」で指定します。
クライアント作成後に追加したユーザーも対象とする場合には、都度利用者に設定してください。
-
OAuth クライアントを利用できるユーザーを設定します。 追加したクライアントで、「利用者の設定」をクリックします。
-
OAuth を利用を許可するユーザーのチェックボックスを選択します。
-
【保存】をクリックします。
STEP3:OAuth認証フローをアプリケーションに実装する
cybozu.com では Authorization Code Grant(認可コードグラント)を利用します。
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:スコープ(必須)
- 複数指定する場合はスペースで区切ります。
- 指定できるスコープは、次を参照してください。
リクエストの例
例では、スコープに
g:schedule:read
を指定しています。
|
|
2. ユーザーによる認可
「(クライアント名)から次の操作が実行されます」画面が表示されたら、【許可】をクリックします。
OAuth クライアントを追加する の「リダイレクトエンドポイント」で指定した URL へ遷移します。
3. 認可コードの取得
リダイレクトされた URL の末尾を確認し、code=
と &state=state1
の間の値をメモしておきます。
この code=
で与えられた値が、認可コードです。アクセストークンの要求・取得で利用します。
URL の例
|
|
4. アクセストークンの要求・取得
トークンエンドポイントに POST リクエストを送信して、アクセストークンを取得します。
リクエストヘッダー
アクセストークンを取得するには、リクエストヘッダーに「Authorization」ヘッダーを指定します。
ヘッダーの値は「Basic 」と「クライアント ID:クライアントシークレット
を Base64 エンコードした値」を結合した値です。
たとえば、クライアント ID が「clientid」でクライアントシークレットが「clientsecret」の場合、「Authorization」ヘッダーの値は「Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0」です。
リクエストボディ
- grant_type:
authorization_code
(必須) - redirect_uri:
OAuth クライアントを追加する で指定したリダイレクトエンドエンドポイント(必須)
- URL は、URL エンコードしてください。
- code: 認可コードの取得 で取得した認可コード(必須)
リクエストの例
|
|
レスポンスの access_token
の値が、API を実行するときの認証に用いるアクセストークンです。
アクセストークンの有効期限は、1 時間です。
アクセストークンの有効期限が切れた場合
refresh_token
を使って、新しくアクセストークンを取得し直してください。
リフレッシュトークンには、有効期限がありません。
リフレッシュトークンを使って、アクセストークンを取得する例は、次のとおりです。
- grant_type:
refresh_token
(必須) - refresh_token: アクセストークンの要求・取得 で取得したリフレッシュトークン(必須)
- code: 認可コードの取得 で取得した認可コード(必須)
|
|
5. APIの実行
取得したアクセストークンを使って、REST API を実行するには、リクエストヘッダーに「Authorization」ヘッダーを指定します。
ヘッダーの値は「Bearer 」とアクセストークンを結合した値です。
指定したスコープで許可されている API 以外は、実行できません。
API の実行例
|
|
cybozu.com 共通管理の IP アドレス制限を利用している場合
OAuth を利用した認証を利用するには、cybozu.com 共通管理で、クライアントアプリケーションの IP アドレスを許可してください。
IP アドレスを許可する設定の詳細は、
IP アドレス制限の設定
を参照してください。
制限事項
- パッケージ版 Garoon では、OAuth クライアントの追加、および OAuth クライアントを使用した API の実行はできません。
- OAuth クライアントは、20 個まで登録できます。
- リフレッシュトークンは、1 ユーザー 1 OAuth クライアントごとに 10 個まで取得できます。
- 認可コードとアクセストークンには、有効期限があります。
有効期限が過ぎた場合は、取得し直してください。- 認証コードの有効期間: 10 分
- アクセストークンの有効期限: 1 時間