API 認証の準備

    API リクエスト URL

    LINE WORKS Bot Platform API のリクエスト URL 形式は、下記の通りです。

    • サービス: https://apis.worksmobile.com/{API ID}/...
    • テスト: https://sandbox-apis.worksmobile.com/{API ID}/...

    ドメインごとの API IDは、LINE WORKS Developer Console から確認できます。

    図 3 API ID 発行の例

    図 3 API ID 発行の例

    API ID が未発行の場合は、LINE WORKS Developer Console発行をクリックして新規発行してください。発行された API ID は、下記のように利用します。

    • サービス: https://apis.worksmobile.com/kr1wwTrYrbIot/...
    • テスト: https://sandbox-apis.worksmobile.com/kr1abeSbktS/...

    サービス API

    サービス API のコンシューマーキー

    サービス API コンシューマーキーは、API を呼び出す際にヘッダーに含む値です。LINE WORKS Developer Console にて確認できます。

    図 4 サービス API のコンシューマーキー発行の例

    図 4 サービス API のコンシューマーキー発行の例

    サービス API コンシューマーキーが未発行の場合は、発行をクリックして発行してください。

    • Step 1 でコンシューマーキーごとのサービス API の利用範囲を指定します。利用範囲についての詳細は サービス API の利用範囲を確認してください。特定用途のみでサービス API を利用する場合には、コンシューマーキーを分けて利用範囲を適切に制限してください。
    • Step 2 でコンシューマーキーで発行するトークンの有効期間を指定します。7~365 日の間で設定することができます。
    • Token 自動延長を設定すると、そのコンシューマーキーで発行された 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
    • テスト: https://sandbox-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 Y ドメイン名(ライトプランの場合は、WORKS グループ名)

    Response

    LINE WORKS ログインページを通じてログインに成功した場合 Authorization Code が発行されて Request 内の redirect_uri に redirect します。

    利用メンバーがすでにログイン済みの場合はログインページは表示されず、そのまま Authorization Code が発行されて Request 内の redirect_uri に redirect します。

    パラメータ タイプ 必須 説明
    code String Y Authorization Code。
    Authorization Code は一回限り有効。有効期間は 1 時間。
    state String Y Authorization Code発行リクエスト時に渡した state 値

    エラー発生

    不正なパラメータやログイン不可能なドメイン、あるいは内部エラーが発生した場合などはエラーページを通じてエラー内容を表示します。

    サービス API Access Token の発行

    サービス API を呼び出す際にヘッダーに含める Access Token を発行します。発行された Access Token は、ソースコード内で下記のように使用します。
    現在、Refresh Token を使った 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
    • テスト: https://sandbox-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 Y ドメイン名(ライトプランの場合は、グループ名)

    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

    サーバー API のコンシューマーキー

    サーバー API を利用する際は、サーバー API コンシューマーキーをヘッダーに含める必要があります。コンシューマーキーは LINE WORKS Developer Console にて確認できます。

    図 5 サーバー API コンシューマーキーの発行例

    図 5 サーバー API コンシューマーキーの発行例

    サーバー API コンシューマーキーが未発行の場合、発行をクリックして発行します。

    • Step 1 でコンシューマーキーごとのサーバー API の利用範囲を指定します。利用範囲についての詳細は サーバーAPI の利用範囲を確認してください。特定用途のみで API を利用する場合には、コンシューマーキーを分けて利用範囲を適切に制限してください。
    • Step 2 でコンシューマーキーで発行するトークンの有効期間を指定します。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 を呼び出す際にヘッダーに含める値です。LINE WORKS Developer Consoleにて確認できます。固定 IP と ID 登録の 2 タイプがあります。

    Server Token(固定 IP タイプ)

    Server List にて追加ボタンをクリックすると、下記のように IP を登録して Tokenを 発行する画面が表示されます。

    図 6 Token 発行画面

    図 6 Token 発行画面

    • サーバー名は、任意です。区別しやすい名前を入力してください。
    • Key 選択で連携するサーバー API コンシューマーキーを選択します。Token 発行後は、他のサーバー API コンシューマーキーに変更することはできませんのでご注意ください。
    • IP に API を利用するサーバーのグローバル IP を入力します。その後、発行をクリックすると Token が発行されます。IP に入力された値と利用時のサーバーのグローバル IP が異なる場合、API 認証に失敗します。
    • 複数のグローバル IP をまとめて登録したり、IP を範囲で指定することはできません。

    IP 登録と token 発行を完了すると、下記のように Server List に表示されます。

    図 7 Token 発行例

    図 7 固定 IP タイプの Token 発行例

    IP をクリックすると詳細情報が表示され、 token を取得することができます。

    Server Token (ID 登録タイプ)

    ID 登録式のServer Token は Developer Console で発行されたサーバー ID をパラメータとして渡します。
    JWT(JSON Web Token RFC-7519) を利用した「two-legged OAuth 2.0 API」を呼び出して Token を発行します.

    サーバー ID 発行及び認証キーのダウンロード

    • Server List(ID 登録タイプ)追加をクリックします。
    • サーバー名を入力して連携するサーバー API コンシューマーキーを選択すると、32 桁のサーバー ID が発行されます。
    • 各サーバー ID ごとに発行される認証キーをダウンロードして保存します。

    図 8 ID 登録タイプのサーバー追加例

    図 8 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 の発行手順は以下の通りです。

    1. JWT 生成 - RFC-7519
    2. JWT 電子署名(signature) - RFC-7515
    3. LINE WORK S認証サーバーへの Token リクエスト - RFC-7523

    図 9 Server Token リクエストの流れ

    図 9 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
    • テスト: https://sandbox-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 の「Token 自動延長」がチェックされており、
    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 時間以内利用されない場合には自動的に失効しますので、ID 登録タイプの場合は必ず一日に一回 Token を発行してください。
    • 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");