【OAuth2.0】aurlからBacklog API を使ってみよう

はじめに

こんにちは植木和樹＠上越妙高オフィスです。本日はクラスメソッド内でも利用者の多いツールaurlのご紹介です。

• GitHub - classmethod/aurl: Command line utility to make HTTP request with OAuth2

ツールの説明にはこうあります。

aurl is a command-line tool that process OAuth 2.0 dance and manage access/refresh tokens automatically.

OAuth 2.0のアクセストークン取得を裏でやりとりしてくれて、得られたトークンで指定したURL（API）を叩いてくれるツールです。

今回はBacklogが提供しているAPIに aurl でアクセスしてユーザー情報を取得してみたいと思います。

（前準備）API Gateway + Lambda でコールバックURLを用意する

BacklogのOAuth 2.0認可ではAuthorization Code Grantのみ対応しています。認証が完了するとコールバックURLに認可コードを付けてリダイレクトされるため、受け取り用のURLを用意します。

Serverless Frameworkを使ってAPI Gateway + Lambdaでサクッと作ります。

2つのファイルをダウンロードしたらデプロイコマンドでAPI GatewayとLambdaファンクションが作成されます。

$ sls deploy

Serverless: Packaging service...
Serverless: Uploading CloudFormation file to S3...
Serverless: Uploading service .zip file to S3 (301 B)...
Serverless: Updating Stack...
Serverless: Checking Stack update progress...
..............
Serverless: Stack update finished...
Service Information
service: oauth2cb
stage: prod
region: us-east-1
api keys:
  None
endpoints:
  GET - https://xxxxxxxxxx.execute-api.us-east-1.amazonaws.com/prod/oauth2/callback
functions:
  callback: oauth2cb-prod-callback

endpointsに出力されたURLは後ほど使うのでメモしておいてください。

環境設定

Backlog CLIENT_ID, CLIENT_SECRETを入手する

Backlogアプリケーション登録画面でアプリケーション（aurl）を登録します。

• Backlog Developers

Redirect URIとアプリケーション名を入力してアプリケーションを登録します。CLIENT_IDとCLIENT_SECRETが発行されるのでメモしておいてください。

aurl プロファイルを作成する

aurlのプロファイルは ~/.aurl/profiles にあるのでエディタで開きます。

今回backlogというプロファイルで作成するので下記を貼り付けてください。

~/.aurl/profiles

[backlog]
auth_server_auth_endpoint = https://YOUR_SPACE.backlog.jp/OAuth2AccessRequest.action
auth_server_token_endpoint = https://YOUR_SPACE.backlog.jp/api/v2/oauth2/token
redirect = https://YOUR_RESTAPI_ID.execute-api.us-east-1.amazonaws.com/prod/oauth2/callback
client_id = YOUR_CLIENT_ID
client_secret = YOUR_CLIENT_SECRET

• YOUR_SPACE ... お使いのBacklogスペースID
• YOUR_RESTAPI_ID ... 作成されたAPI GatewayのID（sls deployした際に表示されたendpoint URLを記載してください）
• YOUR_CLIENT_ID ... Backlogアプリケーション登録画面で取得したCLIENT_ID
• YOUR_CLIENT_SECRET ... 同 CLIENT_SECRET

動作確認

aurlのプロファイルを指定してBacklogのAPIにアクセスしてみましょう。/api/v2/users/myselfで認証したユーザーの情報を取得してみます。

$ aurl --profile backlog "https://YOUR_SPACE.backlog.jp/api/v2/users/myself" | jq "."
Open browser and get code from https://YOUR_SPACE.backlog.jp/OAuth2AccessRequest.action?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fexample.com%2Fv1%2Foauth2%2Fcallback&response_type=code&scope=root&state=xxxxxxxxxxxxx

Enter code:

初回実行時はまだアクセストークンがないため、認可コードを取得するためにブラウザが起動します。ブラウザでBacklogにログインすると登録したBacklogアプリケーションにアクセスを許可して良いか確認されますので「許可する」をクリックします。

コールバックURLにリダイレクトされます。URLパラメーターに認可コードが付与されてますのでコピーします。

aurlのコマンドに戻ります。Enter code:で入力待ちになっているので認可コードを貼り付けて実行します。

あなた自身のユーザー情報が取得できれば成功です！

{
  "id": 1234567890,
  "userId": "ueki",
  "name": "CM植木和樹",
  "roleType": 1,
  "lang": null,
  "mailAddress": "ueki.kazuki@example.com",
  "nulabAccount": {
    "nulabId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "CM植木和樹",
    "uniqueId": "cm_uekikazuki"
  }
}

重要な補足

今回BacklogのCLIENT_SECRETをaurlのプロファイルに記載しましたが、これを多人数で共有すべきではありません！。CLIENT_SECRETはパスワードのようなものなので、信頼がおける場所に保管し漏れてはいけないもののためです。

BacklogにはOAuth 2.0以外にAPI Keyを用いた認証・認可が可能です。API Key方式ではAPIキーがユーザーと紐付いているため、API操作はすべてそのユーザーの権限で行われます。 そのため各ユーザー個別にBacklogのAPIにアクセスする際にはAPI Key方式を採用するのが良いでしょう。

• 認証と認可 | Backlog Developer API | Nulab

まとめ

aurlを使えばOAuth 2.0認可フレームワークが使えるAPIの利用がお手軽にできます。

今回はBacklogを利用しましたが、aurlのプロファイル設定を各サイトにあわせて修正すればいろいろなサイトで利用することが可能です。 実際のシステムではお好みのプログラミング言語を使って実装していくかと思いますが、APIでどんな情報がとれるのか手軽に確認するときなどに aurl を活用いただけるのではないでしょうか。