ID Token の利用方法

OpenID Connect (OIDC) は、OAuth 2.0 を基盤として拡張された認証プロトコルで、認証を行ったメンバーの情報を安全に取得できます。

認証により、API を呼び出すことができる Access Token と、ユーザー情報を含む ID Token の両方を取得することができ、ID Token は SSO で利用できます。

ID Token の利用の流れ

1. ID Token の発行 {#id-token-issue}

ID Token は、User Account 認証で利用できます。

認証により、API を呼び出すことができる Access Token と、ユーザー情報を含む ID Token の両方を取得することができます。

詳しくは User Account 認証 を参照してください。

注意

• ID Tokenは、User Account 認証でのみ発行できます。Service Account 認証では発行できません。

2.ID Token の検証 {#id-token-validation}

以下の項目をすべて確認し、ID Token を検証します。

1. payload > iss claim : openid-configuration に記載された issuer と正確に一致している
2. payload > aud claim : アプリの client id と一致している
3. payload > nonce : 認証を要求した際に指定した nonce と一致している
4. payload > iat, exp : 現在の時刻が iat と exp の間である
5. header > kid, alg : kid に示された Key ID に対応した鍵情報を certs から参照して public key を生成し、alg ヘッダに示されたアルゴリズムで id_token の署名を検証する

3.Access Token の検証 {#access-token-validation}

Access Token は以下の手順で検証します。

1. ID Token Header の alg で指定されたハッシュアルゴリズムで、access_token のハッシュ値を取得する
2. 取得したハッシュ値の左側半分を Base64URL Encode したものが、ID Token の payload > at_hash と等しいことを確認する

4. ID Token の利用 {#id-token-use}

検証によって正当性を確認後 ID Token を利用してください。ID Token に認証を行ったメンバー情報が含まれています。

下記の ID Token の仕様 を参照してください。

ID Token の仕様 {#id-token}

ID Token は、ヘッダー、ペイロード、署名からなる、JSON Web Signature (JWS) で署名された JSON Web Token (JWT) です。

Header {#id-token-header}

Payload {#id-token-payload}

openid-configuration {#openid-configuration}

LINE WORKS の OIDC 構成情報を取得します。 OpenID Connect Discovery 1.0 に従います。

Request URL {#openid-configuration-request-url}

https://auth.worksmobile.com/{tenantId}/.well-known/openid-configuration

HTTP Request {#openid-configuration-request-method}

GET

Path Parameters {#openid-configuration-request-parameter}

Request Example {#openid-configuration-request-example}

curl -location -request GET 'https://auth.worksmobile.com/1111/.well-known/openid-configuration'

Response {#openid-configuration-response}

HTTP 200 OK

Response Example {#openid-configuration-response-example}

{  "issuer": "https://auth.worksmobile.com",  "authorization_endpoint": "https://auth.worksmobile.com/oauth2/v2.0/authorize",  "token_endpoint": "https://auth.worksmobile.com/oauth2/v2.0/token",  "revocation_endpoint": "https://auth.worksmobile.com/oauth2/v2.0/revoke",  "end_session_endpoint": "https://auth.worksmobile.com/oauth2/v2.0/logout",  "jwks_uri": "https://auth.worksmobile.com/oauth2/v2.0/certs/1111",  "userinfo_endpoint": "https://auth.worksmobile.com/oauth2/v2.0/userinfo",  "scopes_supported": [    "openid",    "email",    "profile"  ],  "response_types_supported": [    "code",    "id_token",    "token id_token"  ],  "grant_types_supported": [    "authorization_code",    "implicit",    "refresh_token"  ],  "subject_types_supported": [    "public"  ],  "id_token_signing_alg_values_supported": [    "RS256"  ],  "token_endpoint_auth_methods_supported": [    "client_secret_post"  ],  "claims_supported": [    "iss",    "aud",    "sub",    "iat",    "exp",    "email",    "email_verified",    "family_name",    "given_name",    "name",    "locale",    "app_ver"  ]}

公開鍵情報 {#oidc-certs}

ID Token の署名の検証に使用する公開鍵情報を返します。公開鍵情報は 30 日ごとに更新されます。

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

https://auth.worksmobile.com/oauth2/v2.0/certs/{tenantId}

HTTP Method {#oidc-certs-request-method}

GET

Response {#oidc-certs-response}

HTTP 200

OK

Response Example {#oidc-certs-response-example}

{  "keys": [    {      "kty": "RSA",      "use": "sig",      "alg": "RS256",      "kid": "gnwk3n8rna",      "e": "AQAB",      "n": "ge42jbjjksdgajh23bjtaeg"    },    {      "kty": "RSA",      "use": "sig",      "alg": "RS256",      "kid": "wlgoai49eg",      "e": "AQAB",      "n": "kfiwuheg8skhvbgi23ligoh"    }  ]}

UserInfo Endpoint {#userinfo-endpoint}

Access Token を使用して、認証されたユーザーの情報を取得します。 OpenID Connect Core 1.0 > UserInfo Endpoint に従います。

参考

• UserInfo Endpoint を呼び出すには、Access Token の発行時の scope に openid を含む必要があります。
• レスポンスに含まれるユーザー情報は、Access Token の発行時に指定した Scope により異なります。

Request URL {#userinfo-endpoint-request-url}

https://auth.worksmobile.com/oauth2/v2.0/userinfo

HTTP Method {#userinfo-endpoint-request-method}

GET / POST

Request Headers {#userinfo-endpoint-request-headers}

Request Example {#userinfo-endpoint-request-example}

curl -location -request GET 'https://auth.worksmobile.com/oauth2/v2.0/userinfo' \--header 'Authorization: Bearer jp1AAAAwQ...'

Response Body (JSON) {#userinfo-endpoint-response-body}

Response Example {#userinfo-endpoint-response-example}

openid, email, profile scope をすべて含む場合

{  "sub": "1234567890",  "email": "user@example.com",  "email_verified": true,  "name": "ワークス太郎",  "family_name": "ワークス",  "given_name": "太郎",  "locale": "ja_JP"}

openid scope のみを含む場合

{  "sub": "1234567890"}

Error Response {#userinfo-endpoint-error-response}

HTTP 401 Unauthorized

WWW-Authenticate: Bearer error="invalid_token", error_description="The access token is invalid or has expired"

HTTP 403 Forbidden

WWW-Authenticate: Bearer error="insufficient_scope", error_description="The access token does not contain the 'openid' scope"