OAuth 2.0 を使って cybozu.com の REST API を Postman で叩く方法

目次

はじめに

2018 年 11 月版のアップデートで、OAuth クライアント機能が追加されました。
詳細は OAuthクライアントの使用 を参照ください。

しかし、「OAuth 対応されて何がうれしいの?」と何だかよくわかっていない方も多いのではないでしょうか?
この記事では、OAuth 対応されたことによるメリットと OAuth を利用して認証する機能を使って実際に API を実行する例を紹介します。

メリット

パスワード認証を使用すると、cybozu.com 製品の API を実行する際、cybozu.com 製品の ID やパスワードの情報を連携先のサービスに渡さなければなりません。
この認証方法では、連携先のサービスにユーザーのもつすべての権限を付与することと同じ状態で、特定の権限の付与はできません。
また、ユーザがパスワードを変更するたび、認証に影響が出てしまいます。

今回 OAuth 対応されたことにより、OAuth 2.0 というプロトコルを利用して、cybozu.com 製品の ID やパスワードの情報を連携先のサービスに渡すことなく、特定の権限を連携先のサービスに付与できます。
また、ユーザーがパスワードを変更した際も、API の認証に影響がないため、メンテナンスのコストがかかりません。

手順

今回は、Postman から OAuth を利用して認証する機能を使って、 レコードの一括取得API を実行する例を紹介します。

Postman (External link) とは、Web API を開発するためのツールです。
Postman を使用することで、Web API の実行に必要な設定の作成・管理ができ、cybozu.com 製品の REST API を簡単に実行できます。
Postman は、 こちら (External link) からダウンロードできます。

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

OAuth クライアントを追加する を参考に設定していきます。
STEP1 の「リダイレクトエンドポイント」に、https://oauth.pstmn.io/v1/browser-callback を入力します。
上記以外の設定は記事のとおりです。

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

Postman から OAuth 認証フローを実行します。 アプリ版のPostman (External link) を使用してください。

  1. 「Authorization」タブの「TYPE」に「OAuth 2.0」、「Add authorization data to」に「Request Headers」を選択し、「Get New Access Token」をクリックします。

  2. ポップアップが表示されるので、必要な項目を入力します。


    以下の情報を入力します。
    公式ドキュメントは こちら (External link)

    • Token Name:任意の名前
    • Grant Type:Authorization Code
    • Callback URL:https://oauth.pstmn.io/v1/browser-callback
    • Auth URL:認可エンドポイント
    • Access Token URL:トークンエンドポイント
    • Client ID:クライアントID
    • Client Secret:クライアントシークレット
    • Scope(Aptional):k:app_record:read その他のスコープは こちら
    • State:クロスサイトリクエストフォージェリを防ぐためのランダムな文字列を指定します。
  3. 入力したら「Request Token」をクリックし、cybozu.com の認証画面が表示されるので、ログインします。
    ログインすると、以下のような画面が表示されるので「許可」をクリックして認可要求を承認します。

  4. 認可要求を承認すると、Token が作成されます。
    Postman 上の「Token」が「アクセストークン」に該当します。
    先ほど作成した Token を選択し、「Use Token」をクリックします。


    Authorization タブの Access Token にアクセストークンが設定されます。

  5. URL に「https://(サブドメイン名).cybozu.com/k/v1/records.json?app=(アプリ ID)」と入力し、「Send」をクリックします。


    レコードの情報の取得ができました。

おわりに

OAuth 対応されたことによるメリットと実際に API を実行する手順はご理解いただけたでしょうか?
OAuth を利用して認証する機能を使うことで、安全に cybozu.com 製品の API を実行できます。

注意事項

Postman で取得したアクセストークンの有効期間は 10 分です。

information

この Tips は、2018 年 11 月版 kintone で動作を確認しています。