認可・認証

API を通した LINE WORKS との連携を行うためには、まず、トークンの発行が必要です。

目的に応じて、以下の 2 種類をトークンを取得します。

  • アクセストークン
    • API を利用するためのトークン。
  • ID トークン
    • 認証を行ったメンバーの情報を安全に取得するためのトークン。

アクセストークンの取得 {#access-token}

LINE WORKS API を利用するためには アクセストークン (Access Token) が必要です。定められた認可方式に従ってアクセストークンを発行し、それを用いてAPIを呼び出します。

API の利用方法は LINE WORKS API 共通仕様 を参照してください。

アクセストークンとは {#about-access-token}

アクセストークンは、リソース (組織やユーザー、カレンダー、Bot 等) を操作するために必要なクレデンシャルです。OAuth 2.0 に準拠しています。

アクセストークンは LINE WORKS の認可サーバーより発行されます。この時に認証を行ったユーザーがもつ権限のうちの一部が、アクセストークンに一時的に委任されます。 このアクセストークンを使うことにより、限定された権限の中で、API を通じて安全にリソースへアクセスできます。

アクセス範囲 {#scope}

アクセストークンに付与されるアクセス範囲は、2つの要素で決定されます。

  1. アクセストークンを発行した (認証を行った) メンバーの権限
  2. 指定した権限範囲 (Scope)

アクセストークンの発行時に認証を行ったメンバー自身が持っている権限を基本とし、権限範囲 (Scope) によってどの範囲までを委任させるかを指定します。 指定された Scope によって、そのアクセストークンを使ってどの API を呼び出すことができるのかが決定されます。

Scope の詳細や一覧は OAuth Scopes を参照してください。

また、API ごとに、呼び出しのためにどの Scope が必要なのかが定められています。各 API リファレンスを参照してください。

アクセストークンの取得方法 {#how-to-issue-access-token}

アクセストークンの取得方法には、以下の 2 種類が用意されています。用途に合わせて使い分けてください。

User Account 認証Service Account 認証
概要メンバー (User Account) が認証を行い、アクセストークンを発行する。仮想管理者アカウント (Service Account) で認証を行い、アクセストークンを発行する。
用途スマホアプリや Web アプリ上に API 連携を組み込む場合。Bot やバッチ処理など、システムが API を利用する場合。
認可方式OAuth 2.0 (Authorization Code Grant) に準拠。
OpenID Connect (OIDC) にも対応しています。		OAuth 2.0 を拡張した JWT ベースの方式。
アクセス範囲認証を行ったメンバーの権限の一部をアクセストークンに一時委任する。権限範囲は OAuth Scope で制御される。管理者権限の一部をアクセストークンに一時委任する。権限範囲は OAuth Scope で制御される。
取得方法ログイン画面が表示され、メンバーのログイン情報 (ID/パスワード) でログインすることで、認可リクエストする。Service Account の情報から JWT を生成し、認可リクエストする。

取得方法の詳細は、各ページを参照してください。

ID トークンの取得 {#id-token}

ID トークン (ID Token) を通して、ログイン認証を行ったメンバーの情報は取得することができます。ID トークンは OpenID Connect Core 1.0 (以下、OIDC) で定義されたもので、検証の仕組みと合わせて提供されます。

User API を用いたメンバー情報取得との違いについて {#about-get-user-profile}

メンバー情報の取得方法として User API を用いる方法もあります。

一方、ID トークンでは検証の仕組みによって比較的安全に取得することができます。

ID トークンの利用方法 {#how-to-use-id-token}

ID トークンは OIDC に準拠した仕組みで取得・検証を行えます。

注意

  • ID トークンは User Account 認証にて対応しています。 Service Account 認証では対応していません。

利用方法については ID Token の利用方法 を参照してください。

クライアント認証情報の管理・設定 {#manage-client-authentication-information}

トークンの取得に必要なクライアント認証情報の管理や Scope などの設定は アプリ で行います。

アプリ {#about-app}

アプリとは、API を使ってリソース (組織やユーザー、カレンダー、Bot 等) を操作する際の、トークン発行に必要な情報やアプリ専用の仮想管理者アカウント (Service Account) など、API の利用に必要な情報の管理単位です。

アプリには、アプリの利用目的に応じたアプリタイプがあります。

  • 認証アプリ : LINE WORKS API を利用するためのアプリです。
  • プロビジョニングアプリ : ID プロビジョニング連携に使用するアプリです。

アプリタイプは、アプリの作成時に選択します。アプリの作成後にアプリタイプを変更することはできません。 プロビジョニングアプリについては、長期トークン > プロビジョニングアプリ を参照してください。

認証アプリでは以下の情報を管理します。

■ アプリの基本情報 {#app-basic-information}

項目名説明
アプリ名アプリの名前です。
アプリを追加する際に指定します。後から変更できます。
アプリの説明どのようなアプリなのかを記載する備考欄です。
アプリのアクセス権限アプリを管理できるメンバーを指定します。

■ クライアント認証情報と権限範囲 {#client-setting}

User Account 認証・Service Account 認証の両方で必要となる情報です。

項目名説明
Client IDアプリを識別する ID です。
アプリを作成すると自動的に発行され、変更できません。
Client SecretClient ID と合わせて利用される秘匿情報です。
アプリを作成すると自動的に発行され、変更できません。
OAuth Scopesアプリが利用するリソースとその操作権限です。
詳細は OAuth Scope を参照してください。
トークン設定アプリのトークンの設定です。
Access Token の有効期限と、トークンを再発行する際の動作を選択できます。

■ User Account 認証の設定 {#user-account-auth-setting}

User Account認証で必要となる情報です。

項目名説明
Redirect URLUser Account 認証において、ユーザーの認証に成功した後に、Authorization Code を送付するリダイレクト先の URL です。
Authorization Code の発行を要求する Request Body に含まれる redirect_uri パラメータが、アプリの Redirect URL として登録されているか、検証が行われます。

• https の URL を登録する必要があります。
• サブドメインも個別に登録する必要があります。(例: https://sub.domain)
• 最大 100 個まで登録可能です。
OIDC Logout Redirection - Redirect URLOAuth Scopes で openid を選択した場合にのみ構成できます。
OpenID Connect (OIDC) の RP Initiated Logout で、ログアウトの後にリダイレクトする URL を登録します。

• https の URL を登録する必要があります。
• サブドメインも個別に登録する必要があります。(例: https://sub.domain)
• 最大 100 個まで登録可能です。

■ Service Account 認証の設定 {#service-account-auth-setting}

Service Account認証で必要となる情報です。

項目名説明
Service Accountアプリ専用の仮想管理者アカウントです。
1 つのアプリに対して 1 つの Service Account を発行できます。不要になった Service Account は削除できます。
Private KeyService Account と合わせて利用される秘密鍵です。
Service Account に対し Private Key を発行します。Private Key は再発行が可能で、再発行により以前の Private Key は利用できなくなります。