API 認証の準備
APIを利用する場合、Developer Consoleで API の設定を行う必要があります。
テナントにドメインが複数ある（グループ会社の）場合、特定ドメインに対してのみ API 呼び出し可能な認証情報 (Access Token) を発行することができます。
また、テナント内のすべてのドメインに対して API 呼び出し可能な認証情報 (Access Token) を発行することもできます。
API リクエスト URL
LINE WORKS Bot Platform API のリクエスト URL 形式は、下記の通りです。
- https://apis.worksmobile.com/{API ID}/...
ドメインごとの API ID は、 Developer Console から確認できます。
図 1 API ID 発行の例
API ID が未発行の場合は、 Developer Console で発行をクリックして新規発行してください。発行された API ID は、下記のように利用します。
- https://apis.worksmobile.com/xxxwwTrYrbIot/...
サービス API
サービス API のコンシューマーキー
サービス API コンシューマーキーは、サービス API を呼び出す際にヘッダーに含める値です。 Developer Console にて確認できます。
図 2 サービス API のコンシューマーキー発行の例
サービス API コンシューマーキーを発行する前に、Redirect URL 登録をクリックして Redirect URL を登録する必要があります。
- https の URL を登録する必要があります。
- Redirect URL は、最大100個まで登録可能です。
- 登録された Redirect URL は、サービス API の Authorization Code の発行を受ける時に渡される redirect_uri パラメータの URL と一致しているかどうかを確認する時に使用されます。
サービス API コンシューマーキーの発行が未発行の場合は、発行をクリックして発行してください。
- Step 1 でコンシューマーキーごとのサービス API の利用範囲を指定します。利用範囲についての詳細はサービスAPIの利用範囲を確認してください。特定用途のみでサービス API を利用する場合には、コンシューマーキーを分けて利用範囲を適切に制限してください。
- Step 2 でコンシューマーキーで発行する Access Token(後述) の有効期間を指定します。7～365 日の間で設定することができます。
- Token 自動延長を設定すると、そのコンシューマーキーで発行された Access Token が使用されるたびに有効期間を自動延長します。
- サービス API コンシューマーキーは最大 5 個まで発行できます。
発行されたコンシューマーキーは、ソースコード内で下記のように利用します。
PostMethod method = new PostMethod(url);
method.setRequestHeader("consumerKey", "LQwDde6x8eV4ROOCOdSW");
サービス API Authorization Code の発行
サービス API を利用する際は、ヘッダーに Access Token を含める必要があります。Access Token の発行には、Authorization Code が必要となります。Authorization Code を発行する際は 必ず下記の URL から LINE WORKS のログイン画面を呼び出す必要があります。
ID/パスワードをパラメータとして渡す等でログイン画面やユーザー操作をスキップすることはできません。
Request URL
- https://auth.worksmobile.com/ba/{API ID}/service/authorize
HTTP Method
GET
Request
下記の項目を GET で渡します。
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
| client_id | String | Y | サービス API コンシューマーキー(例: LQwDde6x8eV4ROOCOdSW) |
| redirect_uri | String | Y | Authorization Code 発行後のリダイレクト先 URL。事前に URL エンコードしてください。 |
| state | String | Y | CSRF を防止するために用いる任意の値 |
| domain | String | N | ドメイン名。(ライトプランおよびスタンダードプランを使用中かつグループ名を使用している場合は、グループ名) SSO機能を利用する場合は必須。 |
Response
LINE WORKS ログインページを通じてログインに成功した場合、Authorization Code が発行されて Request 内の redirect_uri に遷移します。
利用メンバーがすでにログイン済みの場合はログインページは表示されず、そのまま Authorization Code が発行されて Request 内の redirect_uri に遷移します。
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
| code | String | Y | Authorization Code Authorization Code は一回限り有効。有効期間は 1 時間。 |
| state | String | Y | Authorization Code発行リクエスト時に渡した state 値 |
エラー発生
不正なパラメータやログイン不可能なドメイン、あるいは内部エラーが発生した場合などはエラーページを通じてエラー内容を表示します。
サービス API Access Token の発行
サービス API を呼び出す際にヘッダーに含める Access Token を発行します。発行された Access Token は、ソースコード内で下記のように使用します。
注意
- Authorization タイプは 'Bearer' を明示してください。'Bearer' と 'Token' の間には空白(space)を必ず入れてください。
PostMethod method = new PostMethod(url);
method.setRequestHeader("consumerKey", "LQwDde6x8eV4ROOCOdSW");
method.setRequestHeader("Authorization", "Bearer AAAAr1xaQrD3iGx2eyQ0/U3mu4OBJzC0HYNF");
Request URL
https://auth.worksmobile.com/ba/{API ID}/service/token
HTTP Method
GET/POST
Request
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
| client_id | String | Y | サービス API コンシューマーキー(例: LQwDde6x8eV4ROOCOdSW) |
| code | String | Y | Authorization Code |
| domain | String | N | ドメイン名。(ライトプランおよびスタンダードプランを使用中かつグループ名を使用している場合は、グループ名) SSO機能を利用する場合は必須。 |
Response
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
| errorCode | String | Y | 成功・失敗の応答コード |
| access_token | String | Y | Access Token Open API を呼び出す際にヘッダーに含む値 |
| refresh_token | String | Y | Refresh Token |
| expire_in | String | Y | Access Token の有効期間 |
Error Code
| エラーコード | 説明 |
|---|---|
| 00 | 成功 |
| 107 | パラメータエラー |
| 502 | accessToken 発行時のエラー |
| 99 | 不明なエラー |
サービス API Access Token の更新
Refresh Token を利用してサービス API Access Token の有効期間を更新することができます。
Request URL
https://auth.worksmobile.com/ba/{API ID}/service/token/refresh
HTTP Method
GET/POST
Request
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
| client_id | String | Y | サービス API コンシューマーキー(例: LQwDde6x8eV4ROOCOdSW) |
| refresh_token | String | Y | Refresh Token |
Response
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
| errorCode | String | Y | 成功・失敗の応答コード |
| access_token | String | Y | Access Token Open API を呼び出す際にヘッダーに含む値 |
| expire_in | String | Y | Access Token の有効期間 |
Error Code
| エラーコード | 説明 |
|---|---|
| 00 | 成功 |
| 107 | パラメータエラー |
| 502 | accessToken 発行時のエラー |
| 99 | 不明なエラー |
サーバー API
サーバー API のコンシューマーキー
サーバー API コンシューマーキーは、サーバー API を呼び出す際にヘッダーに含める値です。コンシューマーキーは Developer Console にて確認できます。
図 3 サーバー API コンシューマーキーの発行例
サーバー API コンシューマーキーが未発行の場合、発行をクリックして発行します。
- Step 1 でコンシューマーキーごとのサーバー API の利用範囲を指定します。利用範囲についての詳細は サーバーAPI の利用範囲を確認してください。特定用途のみで API を利用する場合には、コンシューマーキーを分けて利用範囲を適切に制限してください。
- Partner API を使用する場合、Step 1 で全カテゴリを選択する必要があります。
- Step 2 でコンシューマーキーで発行する Server Token(後述) の有効期間を指定します。7～365 日の間で設定することができます。
- Token 自動延長を設定すると、そのコンシューマーキーで発行された Token が使用されるたびに有効期間を自動延長します。
- サーバー API コンシューマーキーは最大 5 個まで発行できます。
- サーバー API コンシューマーキーを削除すると、連携している Server list(IP タイプ、ID タイプ) の各サーバー情報も削除されます。
発行したコンシューマーキーは、ソースコード内で下記のように使用します。
PostMethod method = new PostMethod(url);
method.setRequestHeader("consumerKey", "dz0jtXyXc9Zo953HdjZA");
サーバー API の Server Token
Server Token は、サーバー API を呼び出す際にヘッダーに含める値です。 Developer Console にて確認できます。固定 IP タイプと ID 登録タイプの 2 種類があります。
Server Token(固定 IP タイプ)
利用サーバーの IP を用いた認証形式です。Server List にて追加ボタンをクリックすると、下記のように IP を登録して Access Token を発行する画面が表示されます。
図 4 Token 発行画面
- サーバー名は、任意です。区別しやすい名前を入力してください。
- Key 選択で連携するサーバー API コンシューマーキーを選択します。Token 発行後は、他のコンシューマーキーに変更することはできません。
- IP に API を利用するサーバーのグローバル IP を入力します。その後、発行をクリックすると Token が発行されます。IP に入力された値と利用時のサーバーのグローバル IP が異なる場合、API 認証に失敗します。
- 複数のグローバル IP をまとめて登録したり、範囲で指定することはできません。
IP 登録と token 発行を完了すると、下記のように Server List に表示されます。
図 5 固定 IP タイプの Token 発行例
IP をクリックすると詳細情報が表示され、 token を取得することができます。
Server Token (ID 登録タイプ)
Developer Console で発行されたサーバー ID を用いて Token を発行する認証形式です。
JWT(JSON Web Token RFC-7519) を利用した「two-legged OAuth 2.0 API」を呼び出して
Token を発行します.
サーバー ID 発行及び認証キーのダウンロード
- Server List(ID 登録タイプ)で追加をクリックします。
- 任意のサーバー名を入力して連携するサーバー API コンシューマーキーを選択すると、32 桁のサーバー ID が発行されます。
- 各サーバー ID ごとに発行される認証キーをダウンロードして保存します。
図 6 ID 登録タイプのサーバー追加例
サーバー ID は以下のような形式です。
f7eee8dbddd5430a96086068ab8b47d0
ダウンロードする認証キーは以下のような形式です。
-----BEGIN RSA PRIVATE KEY-----
MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCePC4qTZPJVBeo
IXTxkJx+Ny2Dg6mUSy5ec53Ennf6omFBctFZynKsG7/aJ4XFbkPBQskP4U9BBvSL
6iBurLgQ7uAbXbRzqbso5+lLJH9Asw0kkkMSJggRY5jaQwfp4l63Ll3LEC0vrbjL
SW4WFgPPBL1FyeHP9g06nkLINTHy++1csYXJXZqjkxNLYnx1Cdwj6+4L4q3HDqIn
IxNzryPaZgOj54I851IZhoy2JgOjMyouRl40pjWBUEh/N4ijoqxCfC3ZXlQmb+a0
A8fYyEhVmlL6mBMdgWdj9RiECXyy0Clmv5ZdTEzt4U7O482/nPmRh5stNyfx9QF9
oEfDmx2xAgMBAAECggEAUJqHSbVK2vujMVoZoBPyI7knzh57e7bwX9y1OTsgEuQ0
dopuajbeQx2/lPkdA30vtnq2wQgcvxsz5zHUY4xIFxgXwNjy2xhS5nt8M3Lb/7E1
uLNoxw3ofjMl4cjTdyiA5v8PeCk9W1Q7FhLJqSZ9ui7H240DIlRMWNfVXPb8ArHR
AjCB6gMIZhYDtQxq76mKxcVZgHnBB9I8dHcjvD+wfbGyX4H0RzTzCMNC4JrTKSIt
y51GMma+jhZ86vcwPQs6bHPBrEbZOw1ZWVMHJOc40lkGj0KzU9jjhguXr6BITLtz
HRrRFgdghpwdYTrUshLpCxJkK/I8UBUnXsAdISl7IQKBgQD155+FlO0Iy3htNS7E
J/uHuC7ExEK01utHgKOoP0pSXmDBmUkAitr0xbvhpnxEEk6bBZdIdhuF/HeXRcJU
T310PIRvIvtRq6bcK31UeelQKMRnp1I0ltj9J/+cutmScN9CbdqY2D9JoXCpk3h/
grhvlmjr68lINtzU8GxSMhffiwKBgQCkuy2TS4eOZnDTxD3nUpqsJugrwBW/IydP
ENhubhhIVUtBDPp/arFPDRJqfqgvjgeoY60L7mpo7uBWa4vwghFJBNDtRj2rKysK
HTI3zaz9QT/7FtYyxCgFY2lijDVv1RVIM91V+aregYfdgeer4HI54Kcv2eNZ2rz0
on6G809fMwKBgFC/DhK/JFaO+aximkivGFkokbLq/zyClh+UjijhH3aMpxjrTJ1w
+xUFGPyvvn5bxJQC8fpJTiBhFqQFtBobQAa7GIGl6wCWbOQ/I5hpr8Myn8uplcTP
A9GdIMJGWMtNZQJbMDygRafX6zbDxf2Y3xdFPI67jgy4dys1B1y2NkChAoGAcTnO
y61gkTpMVuJOAk++zJE5h8jRqb0J6ciUWuMFgcJOpXm8PBQjp0g+3kAMbhNbpBxO
9yJ6tYFrZTsqxrdAFkZfLJfZD2vue1cyCzUtsC1HQtihhedZ8sovx3LD0AhQRn6P
peaj0aiKsG/3wyXUnX+SqstC/6Hfuu5ttWhLqA0CgYBTNRjoRdAJcKzlkdO5Pt/d
Mm/NffywAmsaCrEigGHGs2Kgcz8D2ZrqU8SMUQJODIddAtA7IWHORIvbCIvd2ZHT
k6DEtV+QtGpXZSsIwi6Dl62oive4nZ/9yGxWYRIXugvvVMcJVGQdH+INz5/9X30/
j0+0lyfdNTYtuXlMebHUag==
-----END RSA PRIVATE KEY-----
Server Token を発行する API の呼び出し
Server Token の発行手順は以下の通りです。
図 7 Server Token リクエストの流れ
1. JWT 生成 - RFC-7519
JWT は以下の形式を使用してください。
{header BASE64 エンコード}.{JSON Claim set BASE64 エンコード}.{signature BASE64 エンコード}
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9
.eyJpc3MiOiI0NmM0ZjI4MWY4MTE0OGM5Yjg0NmM1OTI2MmFlNTg4OCIsImlhdCI6MTQ5MjUwNDY3MiwiZXhwIjoxNDkyNTA2NDcyfQ
.aICZ8qvYFKSJT6VdrmEcs6siCHaCgFkqpVs5VALKhf98sZjguppp-bOy9MpNlNepfSF0IyrdG3JavHLUYBz1NEVVZJwEm39f7gODmnt-_kGfDo1YtOqnclP1gM8oiObF2AH2Eneh3XuyeVeZbKAZmp6I_ZOf8AGayVVui61CsDPbUIPZSKUnbW1-vlXboTlojxJhvHznpYSNanHSrg5Nht2VO5sOeclEgPqg3J8Y6XOT60u8Morv5wHUy8a0QyO0yWCT5OJdXeVj94qfDAM15a1Puw9PfQOPm7QhOarvCJ8cOSqo9PHluq9-KZ1WXmfxSo-_itTb8y2YRT3kd21maQ
header にて RSA SHA-256 アルゴリズムを明示します。
{"alg":"RS256","typ":"JWT"}
この値を BASE64 エンコードすると以下のようになります。
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
JSON Claim set の情報は以下の通りです。
| パラメータ | 説明 |
|---|---|
| iss | Developer Console で発行されたサーバー ID |
| iat | JWT 生成日時。 UNIX 時間で指定 (単位:sec) |
| exp | JWT 満了日時。 UNIX 時間で指定 (単位:sec) |
例) 以下の条件の場合
- サーバー ID: 46c4f281f81148c9b846c59262ae5888
- JWT 生成日時: 2017-04-18 17:37:52
- JWT 満了日時: 2017-04-18 18:07:52 (30 分後満了)
JSON 形式での表示
{
"iss":"46c4f281f81148c9b846c59262ae5888",
"iat":1492504672,
"exp":1492506472
}
この値を BASE64 エンコードすると、以下のようになります。
eyJpc3MiOiI0NmM0ZjI4MWY4MTE0OGM5Yjg0NmM1OTI2MmFlNTg4OCIsImlhdCI6MTQ5MjUwNDY3MiwiZXhwIjoxNDkyNTA2NDcyfQ
header と Claim set を .で組み合わせると {header BASE64 エンコード}.{JSON Claim set BASE64 エンコード}は以下のようになります。
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI0NmM0ZjI4MWY4MTE0OGM5Yjg0NmM1OTI2MmFlNTg4OCIsImlhdCI6MTQ5MjUwNDY3MiwiZXhwIjoxNDkyNTA2NDcyfQ
2. JWT 電子署名(signature) - RFC-7515
電子署名は JWS(JSON Web Signature RFC-7515) 規約を遵守します。
先に生成した JWT header と body の byte array を、Developer Console でダウンロードした認証キーを用いて RSA SHA-256 アルゴリズム(header で定めた RS256)で暗号化し BASE64 エンコードします。
上記で生成した {header BASE64 エンコード}.{JSON Claim set BASE64 エンコード} を電子署名して BASE64 エンコードすると {signature BASE64 エンコード} は以下のようになります。
aICZ8qvYFKSJT6VdrmEcs6siCHaCgFkqpVs5VALKhf98sZjguppp-bOy9MpNlNepfSF0IyrdG3JavHLUYBz1NEVVZJwEm39f7gODmnt-_kGfDo1YtOqnclP1gM8oiObF2AH2Eneh3XuyeVeZbKAZmp6I_ZOf8AGayVVui61CsDPbUIPZSKUnbW1-vlXboTlojxJhvHznpYSNanHSrg5Nht2VO5sOeclEgPqg3J8Y6XOT60u8Morv5wHUy8a0QyO0yWCT5OJdXeVj94qfDAM15a1Puw9PfQOPm7QhOarvCJ8cOSqo9PHluq9-KZ1WXmfxSo-_itTb8y2YRT3kd21maQ
最終的に完成した JWT{header BASE64エンコード}.{JSON Claim set BASE64 エンコード}.{signature BASE64 エンコード} は以下のようになります。
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiI0NmM0ZjI4MWY4MTE0OGM5Yjg0NmM1OTI2MmFlNTg4OCIsImlhdCI6MTQ5MjUwNDY3MiwiZXhwIjoxNDkyNTA2NDcyfQ.aICZ8qvYFKSJT6VdrmEcs6siCHaCgFkqpVs5VALKhf98sZjguppp-bOy9MpNlNepfSF0IyrdG3JavHLUYBz1NEVVZJwEm39f7gODmnt-_kGfDo1YtOqnclP1gM8oiObF2AH2Eneh3XuyeVeZbKAZmp6I_ZOf8AGayVVui61CsDPbUIPZSKUnbW1-vlXboTlojxJhvHznpYSNanHSrg5Nht2VO5sOeclEgPqg3J8Y6XOT60u8Morv5wHUy8a0QyO0yWCT5OJdXeVj94qfDAM15a1Puw9PfQOPm7QhOarvCJ8cOSqo9PHluq9-KZ1WXmfxSo-_itTb8y2YRT3kd21maQ
以降の Token リクエストでは、生成した JWT を assertion パラメータとして渡します。
参考
- JWT 生成については、ライブラリの利用を推奨します。
- 一例として、Java の場合には以下のようなライブラリを利用できます。
https://github.com/jwtk/jjwt
https://github.com/auth0/java-jwt
https://bitbucket.org/b_c/jose4j/wiki/Home
https://bitbucket.org/connect2id/nimbus-jose-jwt/wiki/Home
3. LINE WORKS 認証サーバーへの Token リクエスト - RFC-7523
Request URL
- https://auth.worksmobile.com/b/{API ID}/server/token
HTTP Method
POST
content-type : application/x-www-form-urlencoded; charset=UTF-8
Request
下記の項目を POST で送信する。
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
| grant_type | String | Y | URL エンコードされた String 値 urn:ietf:params:oauth:grant-type:jwt-bearer |
| assertion | String | Y | JWT |
POST /b/jp1PrJVEbjpFi/server/token HTTP/1.1
Host: auth.worksmobile.com
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiI0NmM0ZjI4MWY4MTE0OGM5Yjg0NmM1OTI2MmFlNTg4OCIsImlhdCI6MTQ5MjUwNDY3MiwiZXhwIjoxNDkyNTA2NDcyfQ.aICZ8qvYFKSJT6VdrmEcs6siCHaCgFkqpVs5VALKhf98sZjguppp-bOy9MpNlNepfSF0IyrdG3JavHLUYBz1NEVVZJwEm39f7gODmnt-_kGfDo1YtOqnclP1gM8oiObF2AH2Eneh3XuyeVeZbKAZmp6I_ZOf8AGayVVui61CsDPbUIPZSKUnbW1-vlXboTlojxJhvHznpYSNanHSrg5Nht2VO5sOeclEgPqg3J8Y6XOT60u8Morv5wHUy8a0QyO0yWCT5OJdXeVj94qfDAM15a1Puw9PfQOPm7QhOarvCJ8cOSqo9PHluq9-KZ1WXmfxSo-_itTb8y2YRT3kd21maQ
Response
| パラメータ | タイプ | 説明 |
|---|---|---|
| access_token | String | Server Token |
| token_type | String | Bearer |
| expires_in | String | Server Token の有効期限 有効期限は 24 時間(86400 秒)となり、この時間を過ぎると自動的に失効します。 ただし, Developer Console 上で Server API Consumer Key の「Ｔoken 自動延長」がチェックされており、 24 時間以内に再度 Server API が利用された場合には、その利用時点から 24 時間に自動延長されます。 |
{
"access_token":"AAAA/KM+LBNADalmequDgJsBc6pt9o+c2VydmVySWQ+vDbccdzZjec5Hy+dWnUz79laysFBlEg1MmzLuu/6/4l61R4yZTWlGrYcv2KjPPS4JfmYGDctUa95bxP+/YLGk+bVTPt/SjhLCpFnJnrltTmkMLPgrrGxDWM1gJ1tM8y4oBBJWfccN45SfjINOG9wwSAdF7r7+XykkmrcF9AGL1c7hufaVJAl6/ErtkidUXkdW3Dd5QYHm97XOj5n1pWmtJ4+IrAlsKqGqKlUcvRRMHes06s6FD+4pUv7JXnuWnx6/BVqaloeDFCU3vD4jfUOn2UQNIJakvcxknwiCqvoNtcjUzQ58oQ4IG0YWNltI=",
"token_type":"Bearer",
"expires_in":86400
}
注意
- 発行された access_token が 24 時間以内利用されない場合には自動的に失効します。
- access_token の発行時間を token 情報と共に保存し、 Server API の利用時には token の有効期限を確認することを推奨します。
- access_token の有効期限内であっても、token の再発行を行うと以前の token は無効になります。
エラー発生
access_token の値が存在しない場合、エラーを返します。
また、誤ったパラメータや失効した JWT によるエラーが発生した場合、以下のような形式の response を返します。
{
"message":"jwt already expired",
"detail":"JWT expired at 2017-04-19T13:57:58Z. Current time: 2017-04-19T14:27:52Z,
a difference of 1794480 milliseconds. Allowed clock skew: 0 milliseconds.",
"code":"31"
}
Server Token の使用
発行された Token は、ソースコード内にて下記のように使用します。
注意
- Authorization タイプに 'Bearer'を明示してください。'Bearer'と'Token'の間には空白(space)を必ず入れてください。
PostMethod method = new PostMethod(url);
method.setRequestHeader("consumerKey", "dz0jtXyXc9Zo953HdjZA");
method.setRequestHeader("Authorization", "Bearer AAAA5IdUiCj5emZowcf49VRu7qbb548g6aGE");