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 コンシューマーキーが未発行の場合は、発行をクリックして発行してください。

    • コンシューマーキーで発行する Token の有効期間を指定できます。既定では 90 日に設定されていますが、7~365 日の間で変更することができます。
    • Token 自動延長を選択すると、Token を使用するたびに有効期間が延長されます。

    発行されたコンシューマーキーは、ソースコード内で下記のように使用します。

    PostMethod method = new PostMethod(url);
    method.setRequestHeader("consumerKey", "LQwDde6x8eV4ROOCOdSW");
    

    サービス API Authorization Code の発行

    サービス API を利用する際は、Access Token をヘッダーに含めます。Access Token の発行には、Authorization Code が必要となります。Authorization Code を発行する際は LINE WORKS サービスへのログインが必要なため、下記の URL を画面に呼び出す必要があります。

    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 ドメイン名(ライトプランの場合は、グループ名)

    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 は、ソースコード内で下記のように使用します。

    注意

    • 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 成功
    30 パラメータエラー
    40 認証エラー

    サーバー API

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

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

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

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

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

    • Step 1でコンシューマーキーごとのサーバー API の利用範囲を指定します。既定値はすべてのサーバー API です。特定用途のみでコンシューマーキーを使用する場合には、API 利用範囲を適切に制限してください。
    • Step 2でコンシューマーキーで発行する Token の有効期間を指定します。既定値は 90 日に設定されており、7~365日の間で変更することができます。
    • 有効期間を自動延長するように設定すると、このコンシューマーキーで発行された 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");