User Account 認証 (OAuth 2.0)

User Account 認証は、LINE WORKS ユーザーでログインを行い、Access Token を発行して API を利用する方法です。また、ID Token を取得し、認証したメンバー情報を取得することもできます。

認可・認証方式 {#oauth-flow}

User Account 認証は、OAuth 2.0 に準拠した認可フローを提供しています。
また、認証プロトコルとして OpenID Connect (OIDC) に対応しています。

認可・認証フローとして、Authorization Code Flow と Implicit Flow の 2 つの方式に対応しています。

注意

• Implicit Flow は ID Token の取得で利用されるフローです。Access Token の取得で利用することは避けてください。

Authorization Code Flow {#authorization-code-flow}

認証の要求 で response_type に code を指定した場合には、Authorization Code Flow として動作します。

参考

• 通常はこの Authorization Code Flow を利用することを推奨します。

1. アプリ開発者は、事前に Developer Console で認証アプリを構成する。アプリで必要となる Scope と、Redirect URL を指定する
2. ユーザーは、アプリの利用を開始する
3. アプリは、response_type に code を設定し、LINE WORKS にユーザー認可を要求する (Client ID、Redirect URL、必要な Scope を送信)
4. LINE WORKS は、ユーザーの資格情報 (Credentials) を確認し、認証していない場合はログイン画面を表示する
5. ユーザーは、ログイン画面で ID とパスワードを入力してログインする
6. 認証に成功すると、LINE WORKS は Authorization Code (認可コード) を発行し、指定された Redirect URL にリダイレクトする。Authorization Code (認可コード) は、URL のクエリパラメータとしてアプリに返される。
7. アプリは、Authorization Code を使用して LINE WORKS に Access Token の発行を要求する
8. アプリは、受信した Access Token と ID Token を利用する
9. アプリは、Access Token の有効期限が過ぎた場合、Refresh Token を使用して Access Token の再発行を LINE WORKS に要求する

Access Token のみ取得の場合のフロー

ID Token, Access Token の取得の場合のフロー

Implicit Flow {#implicit-flow}

認証の要求 で response_type に id_token または token id_token を指定した場合には、Implicit Flow として動作します。

参考

• 通常は Authorization Code Flow を利用することを推奨します。

1. アプリ開発者は、事前に Developer Console で認証アプリを構成する。アプリで必要となる Scope と、Redirect URL を指定する
2. ユーザーは、アプリの利用を開始する
3. アプリは、response_type に id_token または token id_token を設定し、LINE WORKS にユーザー認可を要求する (Client ID、Redirect URL、必要な Scope を送信)
4. LINE WORKS は、ユーザーの資格情報 (Credentials) を確認し、認証していない場合はログイン画面を表示する
5. ユーザーは、ログイン画面で ID とパスワードを入力してログインする
6. 認証に成功すると、LINE WORKS は、ID Token と Access Token を発行し、アプリで指定した Redirect URL にリダイレクトする。ID Token と Access Token は URL のフラグメント要素としてアプリに返される
7. アプリは、受信した Access Token と ID Token を検証し、利用する

ID Token, Access Token の取得の場合のフロー

トークンの種類と仕様 {#expiry-and-count}

発行される各トークンについて、以下に記載します。それぞれ有効期限が設けられています。また、Authorization Code には利用可能回数が設けられています。

事前準備 {#preparation}

Developer Console に認証アプリを登録し、以下のアプリ情報を準備します。

• Client ID
• Client Secret
• Redirect URL
• OAuth scope

認証の要求 {#authorization-request}

準備したアプリ情報をもとに、認証を要求します。

Request URL {#authorization-request-url}

GET https://auth.worksmobile.com/oauth2/v2.0/authorize?client_id={Client_ID}&redirect_uri={Redirect_URL}&scope={Scope}&response_type={code|id_token|token%20id_token}&state={state}&nonce={nonce}

HTTP Method {#authorization-request-method}

GET

Request Param {#authorization-request-parameter}

以下の項目を URL エンコードして送信します。

Request Example {#authorization-request-example}

Authorization Code Flow の場合 {#authorization-request-example-authcode}

curl -location -request GET 'https://auth.worksmobile.com/oauth2/v2.0/authorize?client_id=X6xn4Bc9k_t2RstnAwrX&redirect_uri=https://example.com/redirect-url&scope=openid&response_type=code&state=UmyR2sX9gO&nonce=Gwbna3Srbl355n2c'

Implicit Flow の場合 {#authorization-request-example-implicit}

curl -location -request GET 'https://auth.worksmobile.com/oauth2/v2.0/authorize?client_id=X6xn4Bc9k_t2RstnAwrX&redirect_uri=https://example.com/redirect-url&scope=openid&response_type=id_token&state=UmyR2sX9gO&nonce=Gwbna3Srbl355n2c'

Response {#authorization-redirect-parameter}

ログイン画面で認証に成功すると、リクエスト時に指定した Redirect URL (redirect_uri) にリダイレクトされます。ログイン画面で認証に失敗した場合には、エラー画面が表示されます。

Authorization Code Flow の場合 {#authorization-redirect-parameter-authcode}

レスポンスはリダイレクトされた URL の Query parameter に返されます。

Implicit Flow の場合 {#authorization-redirect-parameter-implicit}

レスポンスはリダイレクトされた URL のフラグメント部に返されます。

Response Example {#authorization-redirect-example}

Authorization Code Flow の場合 {#authorization-redirect-example-authcode}

GET https://example.com/redirect-url?code=GgWvoas...&state=aBcDeF

Implicit Flow の場合 {#authorization-redirect-example-implicit}

GET https://example.com/redirect-url#access_token=jp1AAAAwQ...&id_token=eyJ0eXAiOiJKV...&scope=openid&expires_in=86400&token_type=Bearer&state=UmyR2sX9gO

トークンの発行 {#issue-access-token}

※ Authorization Code Flow のみ

発行された Authorization Code を使用してトークンの発行を要求します。

Request URL {#issue-access-token-request-url}

POST https://auth.worksmobile.com/oauth2/v2.0/token

HTTP Method {#issue-access-token-request-method}

POST

Request Headers {#issue-access-token-request-header}

Content-Type: application/x-www-form-urlencoded

Request Form Parameters {#issue-access-token-request-parameter}

以下の項目を URL エンコードして渡します。

Request Example {#issue-access-token-request-example}

curl --location --request POST 'https://auth.worksmobile.com/oauth2/v2.0/token' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'code=GgWvoasicmC8MMaUzuxx' \--data-urlencode 'grant_type=authorization_code' \--data-urlencode 'client_id=ZbsOq6zjt0IhtZZnrc' \--data-urlencode 'client_secret=oRm3M_nBg6' \--data-urlencode 'redirect_uri=https://example.com/redirect-url'

Response Body (JSON) {#issue-access-token-response-body}

Response Example {#issue-access-token-response-example}

{  "access_token": "jp1AAAAwQ...",  "refresh_token": "AAAAUrG72...",  "id_token": "eyJ0eXAiOiJKV...",  "scope": "bot",  "expires_in": "86400",  "token_type": "Bearer"}

注意

• Access Token と共に、Access Token の有効期限と Refresh Token を保存することを推奨します。
• API を利用する際に Access Token の有効期限を確認し、有効期限が終了している場合には Refresh Token を用いて Access Token を再発行できます。
• ID Token 取得後は、ID Token や Access Token の検証を行ってください。 詳しくは ID Token の検証 を参照してください。

Access Token の再発行 {#refresh-access-token}

※ Authorization Code Flow のみ

Access Token の有効期限が終了した場合には、Refresh Token を使用して Access Token の再発行を要求できます。

注意
Access Token を Implicit Flow で発行した場合には、Refresh Token は発行されず、Access Token を再発行することはできません。

Developer Console > API > ClientApp の [トークン設定 > Refresh Token Rotation] の設定により、動作が異なります。

• Refresh Token Rotation : ON

  • Access Token を再発行すると、新しい Access Token とともに、新しい Refresh Token が発行されます。
  • Access Token と Refresh Token は、それぞれ 100 個まで有効で、超過した場合には古いものから順に満了します。
  • Token の数は、client_id 毎、ユーザーアカウントまたは Service Account 毎にカウントされます。

• Refresh Token Rotation : OFF

  • Access Token を再発行すると、新しい Access Token のみが発行され、既存の Access Token は満了します。

Request URL {#refresh-access-token-request-url}

POST https://auth.worksmobile.com/oauth2/v2.0/token

Request Headers {#refresh-access-token-request-header}

Content-Type: application/x-www-form-urlencoded

Request Form Parameters {#refresh-access-token-request-parameter}

以下の項目を URL エンコードして渡します。

Request Example {#refresh-access-token-request-example}

curl --location --request POST https://auth.worksmobile.com/oauth2/v2.0/token \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'refresh_token=AAAAUrG721oexirJYyMXOdFMhVpRIDLP9g8gIIGf5xklkE+5FTIITjwlUGCyfJ5F3u4fWi4bIBheJ/2xrQ40M9VTd//g4aEqH1vBwjS6kKpGnUUen2oJqyNcel2fOz8E3nFKAQ==' \--data-urlencode 'grant_type=refresh_token' \--data-urlencode 'client_id=ZbsOq6zjt0IhtZZnrc' \--data-urlencode 'client_secret=oRm3M_nBg6'

Response Body (JSON) {#refresh-access-token-response-body}

Response Example {#refresh-access-token-response-example}

{  "access_token": "jp1BBBBwQSFbOgcXEy7kRGlljKS5/8UwpRh454bljHQajmS7TK069czqA0JcuCcbfDNWRqouQVL/cw64btBW08PQALp10jr3cqgQrA9sdytxKo0+xVT90b3yHs+/6/PM//qEjubrjyYMO+Nt3lPZrFOzzJiRiAQqU0lor0zWk+ZNxMm6D40nB8jD74voYpLTKX+HjSh63Xihmq1ckyN72OjkmmRuZ5+9Qp5GPvWp8jnL8n2ewFI/3D8hg9KFicOUh5V6aKqaxDj+zYuA9xAPOTgJMRpNZA=",  "scope": "bot",  "expires_in": "86400",  "token_type": "Bearer"}

Token の無効化 {#revoke-token}

Access Token または Refresh Token の漏洩が疑われたり、アプリの利用を停止する際に Token が有効な状態のままとなることを避けたい場合などには、Token を無効化できます。

Request URL {#revoke-token-url}

POST https://auth.worksmobile.com/oauth2/v2.0/revoke

Request Headers {#revoke-token-request-header}

Content-Type: application/x-www-form-urlencoded

Request Parameters {#revoke-token-request-parameter}

Request Example {#revoke-token-request-example}

curl --location --request POST 'https://auth.worksmobile.com/oauth2/v2.0/revoke' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'token=kr1AAAA0pZvx/7yyppqVGFfFf2X6HcfTcuNQ6ad1HEXjs3CBikVHSqqwWW218HCElz5JpN+13gothwKxdF98w6GGSzgWBkmarR96Bz3/oiFexXoVYswTntRLF6CYGLmW4VtZnrgeWRL1XmchdrNopKDc8sdfKL1AHhs+xVUCTW1Cc1ozhSFzXAu2VHLWf4R2osM+j/UoiombXGI3ywYjvfoUqTDdpOf8YRqqkI4BbiWMgJWAJe+i4HXFCOHbOI0zOUSrAfGBPadF+HAEyvUOBudoBQ2g/zalcQRnmKEj3uJWr9vsyHq' \--data-urlencode 'client_id=ZbsOq6zjt0IhtZZnrc' \--data-urlencode 'client_secret= nWgG8mdOiM' \--data-urlencode 'token_type_hint=refresh_token'

Response {#revoke-token-response}

HTTP 200 OK

OIDC ログアウト (RP Initialized Logout) {#oidc-logout}

LINE WORKS からログアウトする。 OpenID Connect RP-Initiated Logout 1.0 に従います。

補足

• これを LINE WORKS にアクセスしているブラウザ上で開くことで、LINE WORKS からログアウトすることができます。

Request URL {#oidc-logout-request-url}

GET または POST https://auth.worksmobile.com/oauth2/v2.0/logout

Request Parameters {#oidc-logout-request-parameter}

Request Example ‐ GET {#oidc-logout-request-example-get}

https://auth.worksmobile.com/oauth2/v2.0/logout?id_token_hint=eyJ0e...&client_id=X6xn4...&post_logout_redirect_uri=https%3A%2F%2Fyourdomain.com%2Flogout%2Fcallback&state=UmyR2sX9gO

Request Example ‐ POST {#oidc-logout-request-example-post}

curl --location 'https://auth.worksmobile.com/oauth2/v2.0/logout' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'id_token_hint=eyJ0e...' \--data-urlencode 'client_id=X6xn4Bc9k_t2RstnAwrX' \--data-urlencode 'post_logout_redirect_uri=https://yourdomain.com/logout/callback' \--data-urlencode 'state=UmyR2sX9gO'

Response {#oidc-logout-response}

ユーザーがログアウトについて同意し、LINE WORKS からのログアウトに成功すると、post_logout_redirect_uri にリダイレクトされます。

Success

Access Token の使用 {#how-to-use-access-token}

発行された Access Token は、認証スキーム Bearer と組み合わせて Authorization HTTP Request Header に指定し、API を呼び出します。

注意

• Authorization タイプに Bearer を明示し、Bearer と Token を 1 つの半角スペースでつなぎます。

PostMethod method = new PostMethod(url);method.setRequestHeader("Authorization", "Bearer AAAA5IdUiCj5emZowcf49VRu7qbb548g6aGE");