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 から確認できます。

    図 3 API ID 発行の例

    図 1 API ID 発行の例

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

    • https://apis.worksmobile.com/xxxwwTrYrbIot/...

    サービス API

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

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

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

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

    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

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

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

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

    図 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 を発行する画面が表示されます。

    図 6 Token 発行画面

    図 4 Token 発行画面

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

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

    図 7 Token 発行例

    図 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 ごとに発行される認証キーをダウンロードして保存します。

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

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

    図 9 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 の「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 時間以内利用されない場合には自動的に失効します。
    • 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");