구성원 계정으로 인증 (OAuth 2.0 + OpenID Connect 1.0)

User Account 인증은 NAVER WORKS 계정으로 로그인하여 Access Token을 발급받아 API를 이용하는 방법이다.

인증·인가 방식 {#oauth-flow}

User Account 인증은 OAuth 2.0에 기반한 인가 과정이며,
인증 프로토콜인 OIDC(OpenID Connect)도 지원한다.

인증·인가 흐름에 따라, Authorization Code Flow와 Implicit Flow 2가지 방식으로 이용할 수 있다.

주의
Implicit Flow에서는 ID Token만 발급된다. Access Token을 발급받으려면 Authorization Code Flow를 이용한다.

Authorization Code Flow {#authorization-code-flow}

인증 요청에서 response_type으로 code를 지정한 경우 Authorization Code Flow로 동작한다.

참고
Authorization Code Flow를 주로 이용할 것을 권장한다.

Developer Console에서 OAuth 앱을 생성한다. 필요한Scope와 Redirect URL을 지정한다.
response_type으로 code를 지정하고, 사용자 인증을 요청한다. 이때, Client ID, Redirect URL, Scope 정보를 함께 전달한다.
사용자의 자격 정보(Credentials)를 확인하여 로그인되지 않은 상태이면 로그인 화면을 표시한다.
사용자는 로그인 화면에서 아이디와 비밀번호를 입력하여 로그인한다.
로그인에 성공하면 Authorization Code(인가 코드)가 발급되어 Redirect URL의 쿼리 파라미터로 리다이렉트된다. Authorization Code(인가 코드)는 URL의 쿼리 매개 변수로 리다이렉트 된다.
발급받은 Authorization Code를 사용하여 Access Token을 요청한다.
Access Token과 ID Token이 발급된다.
Access Token이 만료되면 Refresh Token으로 Access Token을 재발급한다.

Access Token만 취득한 경우

auth_user_account_authcode

ID Token, Access Token을 취득한 경우

auth_user_account_authcode_oidc

Implicit Flow {#implicit-flow}

인증 요청에서 response_type을 id_token 또는 token id_token을 지정한 경우 Implicit Flow로 동작한다.

참고
Authorization Code Flow를 주로 이용할 것을 권장한다.

Developer Console에서 OAuth 앱을 생성한다. 필요한Scope와 Redirect URL을 지정한다.
response_type으로 id_token 또는 token id_token을 지정하고, 사용자 인증을 요청한다. 이때, Client ID, Redirect URL, Scope 정보를 함께 전달한다.
사용자의 자격 정보(Credentials)를 확인하여 로그인되지 않은 상태이면 로그인 화면을 표시한다.
사용자는 로그인 화면에서 아이디와 비밀번호를 입력하여 로그인한다.
로그인에 성공하면 ID Token과 Access Token이 발급되어 Redirect URL로 리다이렉트된다.
발급받은 Access Token과 ID Token을 검증 후 사용한다.

ID Token, Access Token을 취득한 경우

auth_user_account_implicit_oidc

토큰의 종류와 규격 {#expiry-and-count}

발급받을 수 있는 토큰은 다음과 같다. 토큰별로 유효 기간이 다르며, Authorization Code는 이용 가능 횟수가 제한된다.

종류	설명	유효 기간	이용 가능 횟수
Authorization Code	Authorization Code Flow에서 이용되는 인증 코드	10분	1회
Access Token	사용자 인증 정보와 API 이용 범위(scope) 포함	1시간 or 24시간	-
Refresh Token	Access Token이 만료되었을 때 인증 절차를 거치지 않고 Access Token을 재발급하는 데 사용	90일	-
ID Token	사용자 인증 정보와 부가 정보(email, name, locale 등) 포함	1시간	-

사전 준비 {#preparation}

Developer Console에 OAuth 앱을 추가하고 다음의 정보를 확인한다.

Client ID
Client Secret
Redirect URL
OAuth scope

인증 요청 {#authorization-request}

앱 정보로 인증을 요청한다.

Request URL {#authorization-request-url}

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 인코딩하여 기입한다.

파라미터	타입	필수 여부	설명
client_id	String	Y	Developer Console에서 발급받은 앱의 client ID
redirect_uri	String	Y	Authorization Code 또는 ID Token 발급 후 전달할 고객사의 URL. 인코딩된 URL로 입력하며 클라이언트 앱에 등록한 Redirect URL과 일치해야 한다.
scope	String	Y	사용할 API의 요청 범위 정보. 여러 개의 요청 범위를 사용할 때는 쉼표(,)나 공백( )으로 연결한다. 자세한 내용은 OAuth Scopes 를 참고한다. ID Token을 발급받는 경우 · "openid"를 지정해야한다. · ID Token에 email 정보가 포함되어야 하는 경우 "email", name과 locale 정보가 포함되어야 하는 경우 "profile"을 추가한다.
response_type	String	Y	OAuth 2.0 Response Type 값에 따라 인증 흐름 방식이 달리진다. · "code": Authorization Code(Authorization Code Flow) · "id_token": ID Token(Implicit Flow) · "token id_token": Access Token및 ID Token(Implicit flow)
state	String	Y	CSRF(Cross-Site Request Forgeries)를 방지하기 위한 임의값
nonce	String	-	Replay Attack 방지를 위한 임의의 값. · Implicit Flow에서는 필수이다. 추측하기 어려운 값으로 지정한다.
domain	String	N	도메인명(Lite 상품인 경우 그룹명) SSO 사용 시 필수로 입력해야 한다. 입력하지 않으면 고객사 로그인 페이지로 redirect되지 않는다.

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}

속성	타입	필수 여부	설명
code	String	Y	Authorization Code. Authorization Code는 일회성이고, 유효 기간은 10분이다.
state	String	Y	Authorization Code 발급 요청 시 전달한 값

Implicit Flow {#authorization-redirect-parameter-implicit}

파라미터	타입	설명
access_token	String	Access Token. response_type에 "token"을 포함해 요청하면 반환된다. 검증 후 이용해야 한다.
id_token	String	ID Token. 검증 후 이용해야 한다.
scope	String	Access Token으로 이용할 수 있는 Scope
expires_in	String	Access Token의 유효 기간. 유효 기간은 Developer Console의 Token 설정 > Access Token 유효 기간의 설정에 따라 다르다. • 1 hour(3600초) • 24 hours(86400초) 설정된 유효 기간이 지나면 자동으로 만료된다.
token_type	String	토큰의 종류. "Bearer"
state	String	인증 요청 시 지정한 값

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-token}

토큰을 이용해 유효 기간 동안 매번 인증을 거치지 않고 API를 호출할 수 있다.

API를 호출할 때 필요에 따라 토큰 정보를 확인하거나 유효 기간 갱신을 위해 별도의 요청이 필요할 수 있다. 유효 기간을 경과한 Access Token으로 API를 호출하면 오류가 출력된다.
※Authorization Code Flow인 경우, 발급받은 Authorization Code를 이용하여 token을 발급받는다.

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

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 인코딩하여 요청한다.

파라미터	타입	필수 여부	설명
code	String	Y	발급받은 Authorization Code 입력
grant_type	String	Y	"authorization_code"로 고정
client_id	String	Y	Developer Console에서 발급받은 앱의 client ID
client_secret	String	Y	Developer Console에서 발급받은 앱의 client secret
redirect_uri	String	N	Authorization Code 또는 ID Token 발급 후 전달할 고객사의 URL. 인코딩된 URL로 입력하며 클라이언트 앱에 등록한 Redirect URL과 일치해야 한다. scope에 "openid"가 지정되면 필수
domain	String	N	도메인명(Lite 상품인 경우 그룹명) SSO 사용 시 필수

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}

속성	타입	설명
access_token	String	Access Token. API 호출 시 헤더에 포함하는 값으로 유효 기간은 1일이다.
refresh_token	String	Refresh Token
id_token	String	ID Token scope에 openid가 지정될 때만 발급된다. ID Token에 대한 자세한 내용은 ID Token을 참고한다.
scope	String	토큰이 사용할 수 있는 API의 요청 범위
expires_in	String	Access Token의 유효 기간. 유효 기간은 Developer Console의 Token 설정 > Access Token 유효 기간의 설정에 따라 다르다. • 1 hour(3600초) • 24 hours(86400초) 설정된 유효 기간이 지나면 자동으로 만료된다.
token_type	String	토큰의 종류. Bearer

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의 유효 기간과 Refresh Token을 저장할 것을 권장한다.
API를 이용할 때 Access Token의 유효 기간을 확인하고, 유효 기간이 만료되면 Refresh Token으로 Access Token을 재발급할 수 있다.
ID Token과 Access Token은 검증 이후 사용해야 한다. 자세한 내용은 ID Token 검증을 참고한다.

Access Token 갱신 {#refresh-access-token}

Authorization Code Flow에서 Access Token이 만료되면 Refresh Token으로 재발급할 수 있다.

Developer Console의 Token 설정 > Refresh Token Rotation 설정에 따라 다르게 동작한다.

Refresh Token Rotation이 On인 경우
- Access Token 갱신 시 새로운 Access Token과 새로운 Refresh Token이 발급된다.
- Access Token과 Refresh Token은 각각 100개까지 유효하며, 초과 시 오래된 순서대로 만료된다.
- 토큰의 개수는 client_id + 구성원 계정(혹은 서비스 계정) 단위로 집계된다.
Refresh Token Rotation이 Off인 경우
- Access Token 갱신 시 새로운 Access Token만 발급되고, 기존 Access Token은 만료된다.

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

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

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

POST

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

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

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

각 항목의 값을 URL 인코딩하여 요청한다.

파라미터	타입	필수 여부	설명
refresh_token	String	Y	Access Token 발급 시 받은 refresh_token값
grant_type	String	Y	"refresh_token"으로 고정
client_id	String	Y	Developer Console에서 발급받은 앱의 client ID
client_secret	String	Y	Developer Console에서 발급받은 앱의 client secret

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}

속성	타입	설명
access_token	String	새로운 Access Token. API 호출 시 헤더에 포함하는 값
refresh_token	String	새로운 Refresh Token. Refresh Token Rotation이 On인 경우에만 응답
scope	String	토큰이 사용할 수 있는 API의 요청 범위
expires_in	String	Access Token의 유효 기간. 유효 기간은 Developer Console의 Token 설정 > Access Token 유효 기간의 설정에 따라 다르다. • 1 hour(3600초) • 24 hours(86400초) 설정된 유효 기간이 지나면 자동으로 만료된다.
token_type	String	토큰의 종류. Bearer

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

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

토큰 만료 {#revoke-token}

Access Token 또는 Refresh Token을 만료시킨다.

Request URL {#revoke-token-request-url}

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

HTTP Method {#revoke-token-request-method}

POST

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

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

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

name	type	requirement	description
client_id	String	Y	Developer Console에서 발급받은 앱의 client ID
client_secret	String	Y	Developer Console에서 발급받은 앱의 client secret
token	String	Y	만료시킬 Access Token 또는 Refresh Token. 요청이 성공하면 관련된 토큰이 만료된다. Refresh Token을 만료시킬 경우 Access Token이 함께 만료된다.
token_type_hint	String	N	만료시킬 토큰 타입에 대한 힌트. access_token이나 refresh_token을 사용한다. refresh_token을 사용하면 관련된 모든 access_token이 만료된다.

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 Initiated Logout) {#oidc-logout}

NAVER WORKS로 로그아웃을 요청한다.
OpenID Connect RP-Initiated Logout 1.0을 준수한다.

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

GET or POST https://auth.worksmobile.com/oauth2/v2.0/logout

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

속성	타입	필수 여부	설명
id_token_hint	String	Y	OIDC 로그인에서 발급받은 id token. 로그아웃 대상 사용자의 id token을 전달한다.
client_id	String	Y	로그아웃할 앱의 client_id
post_logout_redirect_uri	String	Y	IDP(NAVER WORKS)에서 로그아웃 후 리다이렉트되는 URL Developer Console > OIDC Logout Redirection에 등록된 Redirect URL과 일치해야 한다.
state	String	N	CSRF(Cross-Site Request Forgeries)를 방지하기 위한 임의값 추측하기 어려운 값으로 지정한다. post_logout_redirect_uri로 리다이렉트될 때 포함된다.

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

curl -location -request 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}

요청이 유효한 경우, 사용자에게 로그아웃 여부를 확인한다. 사용자가 확인하여 NAVER WORKS에서 로그아웃되면 post_logout_redirect_uri로 리다이렉트된다.

Success

속성	타입	설명
state	String	로그아웃 요청 시 전달한 값

Access Token의 사용 {#how-to-use-access-token}

발급받은 Access Token은 Bearer와 함께 Authorization HTTP Request Header에 지정하여 API를 호출한다.

주의
Authorization 타입에 Bearer를 명시해야 하며, Bearer와 Token 사이에 공백을 한 칸 둔다.

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