ID Token 이용 방법

OIDC(OpenID Connect)는 OAuth 2.0 기반의 확장된 인증 프로토콜로, 인증된 구성원의 정보를 안전하게 취득할 수 있도록 한다.

인증 과정을 거쳐 API를 호출할 수 있는 Access Token과 사용자 인증을 할 수 있는 ID Token을 모두 획득할 수 있다. ID Token은 SSO 연동(IdP)에 활용할 수 있다.

ID Token 이용 흐름

1. ID Token 발급{#id-token-issue}

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 헤더를 이용하여 certs로 public key를 생성하고, alg 헤더의 알고리즘으로 id_token의 서명을 검증해야 한다.

3. Access Token 검증 {#access-token-validation}

Access Token은 다음의 순서로 검증한다.

1. ID Token의 alg 헤더에서 지정된 해시 알고리즘으로 access_token의 해시값을 취득해야 한다.
2. 취득한 해시값을 반으로 나눠 앞부분을 Base64 URL encode한 뒤, ID Token의 payload > at_hash와 동일한지 확인한다.

4. ID Token의 사용 {#id-token-use}

검증된 ID Token을 사용한다. ID Token에는 인증된 구성원의 정보가 포함되어 있다.

ID Token의 규격 {#id-token}

ID Token은 헤더, 페이로드, 서명으로 구성되며, JWS(JSON Web Signature)에서 서명된 JWT(JSON Web Token)이다.

Header {#id-token-header}

Payload {#id-token-payload}

openid-configuration {#openid-configuration}

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

certs {#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}

GET/POST 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": "ko_KR"}

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"