인가·인증

API를 사용하는 등 NAVER WORKS와 연동하려면 토큰이 필요하다.

  • Access Token
    • NAVER WORKS API를 사용하기 위한 토큰
  • ID Token
    • 인증된 구성원의 정보를 안전하게 취득하기 위한 토큰.

Access Token 발급 {#access-token}

NAVER WORKS API를 사용하려면 Access Token이 필요하다. 정해진 방식에 따라 발급한 Access Token으로 API를 호출한다.

API를 호출하는 방법은 API 호출을 참고한다.

Access Token이란 {#about-access-token}

Access Token은 조직, 구성원, 캘린더, Bot 등의 정보에 접근하는 데 필요한 자격 정보이다. OAuth 2.0을 준수한다.

Access Token은 NAVER WORKS의 인증 서버에서 발급한다. 인증 절차에 따라 구성원의 리소스 액세스 권한이 Access Token에 일시적으로 위임된다. 사용자는 Access Token을 사용하여 위임받은 권한으로 API를 사용해 리소스에 안전하게 접근할 수 있다.

액세스 범위 {#scope}

Access Token에 부여되는 액세스 범위는 다음 두 가지 요소로 결정된다.

  1. Access Token을 발급받은 구성원의 권한
  2. 지정된 권한 범위(scope)

Access Token을 발급받은 구성원이 소유한 권한에 따라 권한 범위(scope)를 지정한다. 여기에 지정된 scope는 Access Token을 사용하여 어떤 API를 호출할 수 있는지 결정한다.

자세한 내용은 OAuth Scopes를 참고한다.

각 API를 호출하기 위해 필요한 scope는 각 API 문서를 참고한다.

Access Token 발급 방법 {#how-to-issue-access-token}

Access Token은 다음 두 가지 방법으로 발급받을 수 있으며 용도에 맞게 선택하여 사용할 수 있다.

구성원 계정으로 인증서비스 계정으로 인증(JWT)
개요구성원(User Account)으로 인증 절차를 거쳐 Access Token을 발급받는다.가상 관리자 계정(Service Account)으로 인증 절차를 거쳐 Access Token을 발급받는다.
용도모바일 앱이나 웹에 API 연계를 통합하는 경우.Bot 및 배치 처리와 같은 시스템이 API를 사용하는 경우.
인증 방법• OAuth 2.0 (Authorization Code Grant)
• OIDC(OpenID Connect)		OAuth 2.0을 확장한 JWT 기반 메서드
액세스 범위인증된 구성원의 권한을 Access Token에 위임한다. 권한 범위는 OAuth scope로 지정한다.관리자 권한을 Access Token에 위임한다. 권한 범위는 OAuth scope로 지정한다.
발급 방법로그인 화면이 표시되고 구성원 계정(ID/비밀번호)으로 로그인하여 Authorization Code를 요청한다.Service Account 정보에서 JWT를 생성하고 권한을 요청한다.

자세한 내용은 각 인증 방법의 페이지를 참고한다.

ID Token 발급 {#id-token}

ID Token로 로그인한 구성원의 정보를 취득할 수 있다. ID Token은 OpenID Connect Core 1.0(이하, OIDC)에서 정의된 것으로 검증과 함께 제공된다.

User API를 이용한 구성원 정보 조회와의 차이 {#about-get-user-profile}

User API로도 구성원 정보를 조회할 수 있지만, ID Token을 이용하면 별도의 검증 절차를 거쳐 비교적 안전하게 구성원 정보를 취득할 수 있다는 차이가 있다.

ID Token의 이용 방법 {#how-to-use-id-token}

ID Token은 OIDC에 기반한 방법으로 발급·검증할 수 있다.

주의

  • ID Token은 User Account 인증으로만 발급받을 수 있다. Service Account 인증 시 발급이 불가하다. 자세한 내용은 ID토큰 이용 방법을 참고한다.

클라이언트 자격 정보 관리 및 설정 {#manage-client-authentication-information}

토큰 발급 시 필요한 클라이언트 자격 정보 관리 및 권한 범위 등의 설정은 클라이언트 앱에서 할 수 있다.

클라이언트 앱 {#about-app}

클라이언트 앱이란 API로 조직, 구성원, 캘린더, Bot 등의 리소스를 조작할 때 Token 게시에 필요한 정보나 앱 전용 가상 관리자 계정(Service Account) 등 API를 이용할 때 필요한 정보의 관리 단위이다.

앱 이용 목적에 따라 다음과 같은 앱 유형이 있다.

  • OAuth 연동 : LINE WORKS API를 이용하기 위한 앱이다.
  • Provisioning 관리 : 아이디 프로비저닝 연계에 사용하는 앱이다.

앱 유형은 앱을 만들 때 선택한다. 앱 생성 후 앱 유형을 변경할 수 없다. Provisioning 관리에 관한 자세한 정보는 "Long-lived Token 발급"의 Provisioning 앱을 참고한다.

인증 앱에서는 아래의 정보를 관리합니다.

■ 클라이언트 앱의 기본 정보 {#app-basic-information}

클라이언트 앱의 기본 정보이다.

항목설명
앱 이름앱을 추가할 때 지정하는 앱 이름. 변경할 수 있다.
앱 설명앱에 관한 설명을 추가할 수 있다.

■ 클라이언트 자격 증명 및 권한 범위 {#client-setting}

구성원 계정 인증과 서비스 계정 인증에 필요한 정보이다.

항목설명
Client ID앱을 식별하는 ID.
앱을 만들면 자동으로 생성되며 변경할 수 없다.
Client SecretClient ID와 함께 사용되는 비밀 정보.
앱을 만들면 자동으로 게시되며 변경할 수 없다.
OAuth Scopes앱의 액세스 권한 범위.
자세한 내용은 OAuth Scopes를 참고한다.
Token 설정앱의 토큰 동작.
Access Token의 유효 기간과 토큰 갱신 시 동작을 선택할 수 있다.
앱 접근 권한앱에 접근할 수 있는 권한.
앱을 수정 및 삭제할 수 있는 구성원을 지정할 수 있다.

■ 구성원 계정 인증 {#user-account-auth-setting}

구성원 계정 인증에 필요한 정보이다.

항목설명
Redirect URL구성원 계정 인증에서 사용자 인증에 성공하면 입력한 Redirect URL로 Authorization Code가 전송된다.
Authorization Code는 요청 정보에 포함되는 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-auth-setting}

서비스 계정 인증에 필요한 정보이다.

항목설명
Service Account가상 관리자 계정.
클라이언트 앱 하나당 하나의 서비스 계정을 발급받을 수 있으며 더 이상 필요하지 않으면 삭제할 수 있다.
Private KeyService Account와 함께 사용되는 개인 키.
Priavate Key는 재발행할 수 있으며, 재발행하면 이전에 발급받은 키는 사용할 수 없다.