How to Use an ID Token

OpenID Connect (OIDC) is an extended authentication protocol based on OAuth 2.0, which allows you to securely acquire an authenticated user's information.

After going through the authorization process, you can get both an access token that is used to make an API call and an ID token to authenticate a user. An ID token can be used for SSO integration (IdP).

ID token use flow

1. Get an ID token {#id-token-issue}

Getting an ID token requires authentication with a user account.

Caution
Getting an ID token requires authentication with a user account. You cannot get an ID token by authentication with a service account.

2. Verify an ID token {#id-token-validation}

To verify an ID token, you need to check all of the following:

payload > iss claim: It must exactly match the issuer specified in openid-configuration.
payload > aud claim: It must match the client ID of the app.
payload > nonce: It must be the same as the nonce requested in the authorization request.
payload > iat, exp: The current time must be between iat and exp.
header > kid, alg: Create a public key with certs using the kid header and verify the signature of id_token with the algorithm in the alg header.

3. Verify an access token {#access-token-validation}

Follow the instructions below.

Get the hash value of access_token with the hash algorithm specified in the alg header of the ID token.
Divide the hash value in half, Base64 URL-encode the first part, and then check if it is the same as the payload > at_hash of the ID token.

4. Use an ID token {#id-token-use}

Verify an ID token before using it. An ID token contains the information of the authenticated user.

ID token specification {#id-token}

As a JSON Web Token (JWT) signed with JSON Web Signature (JWS), an ID token consists of a header, payload, and signature.

Header {#id-token-header}

Property	Required	Description
typ	Required	JWT
alg	Required	RS256
kid	Required	Key ID for the signature

Payload {#id-token-payload}

claim	Required	Description
iss	Required	Issuer It must match the issuer of openid-configuration.
sub	Required	Member ID
aud	Required	The app's client ID issued by the Developer Console
nonce	Optional	The nonce value passed by the authorization request. It is required if a nonce is specified in the authorization request.
email	Optional	LINE WORKS account. It is usually in the form of an email, but it may not be if a group name is used as the domain. ・ Available if the email scope is selected.
name	Optional	Representative name ・ Available if the profile scope is selected.
locale	Optional	Language codes (ko_KR, ja_JP, en_US, zh_CN, zh_TW) ・ Available if the profile scope is selected.
exp	Required	JWT expiration time. It is in Unix time format (in sec). It expires after 1 hour.
iat	Required	JWT creation time. It is in Unix time format (in sec).
at_hash	Optional	The hash value of the access token. It is used to verify the access token. It is required in the implicit flow.
email_verified	Optional	Account validity. It is always true because email is a LINE WORKS account. ・ Available if the email scope is selected.
family_name	Optional	Last name ・ Available if the profile scope is selected.
given_name	Optional	First name ・ Available if the profile scope is selected.

openid-configuration {#openid-configuration}

It specifies the OIDC specifications of LINE WORKS.
Comply with 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}

Property	Type	Description
tenantId	String	Tenant ID

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

Property	Type	Description
issuer	String	Issuer
authorization_endpoint	String	OAuth 2.0 Authorization Endpoint URL
token_endpoint	String	OAuth2.0 Token Endpoint URL
revocation_endpoint	String	OAuth2.0 Revocation Endpoint URL
jwks_uri	String	JWK document URL
scopes_supported	Array (string)	Scopes supported by OIDC
grant_types_supported	Array (string)	grant_types supported by OIDC
subject_types_supported	Array (string)	Subject identifier types supported
id_token_signing_alg_values_supported	Array (string)	id_token signature algorithm
token_endpoint_auth_methods_supported	Array (string)	Authentication method supported by the token endpoint
claims_supported	Array (string)	Items supported by id_token claim

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",  "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"  ]}

certs {#oidc-certs}

It returns the public key information to be used to verify the signature of the ID token. The rotation cycle is 30 days.

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

Property	Type	Description
kty	String	Key Type Set this to "RSA".
use	String	Public Key User Set this to "sig" (signature).
alg	String	Algorithm Set this to "RS256".
kid	String	Key ID ID of non-duplicate key
e	String	Exponent RSA public key exponent ※ Signs are not included.
n	String	Modulus RSA public key modulus ※ Signs are not included.

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"    }  ]}