[confluence to tistory-4]Confluence Api도 OAuth2.0으로

Tistory Api 덕분에 OAuth2.0의 원리 및 활용법을 알게 되었는데, 생각해보니 사용자를 위해서라면 Confluence Api를 사용할 때도 OAuth2.0 방식으로 해야겠다는 생각이 되어 찾아보니, Confluence에서도 OAuth2.0을 지원하고 있었다.

 

OAuth2.0 앱 등록

당연한 이야기 이지만 Confluence도 OAuth2.0 인증을 사용하기 위해서는 개발자 콘솔에서 어플리케이션을 등록하고, AppID 및 Secret등을 발급 받아야 한다. 순서는 다음과 같다.

1. 개발자 콘솔의 Myapps에서 Create app버튼에서 OAuth 2.0 (3LO) integration 을 선택한다.
2. 만들 어플리케이션의 이름을 입력하고 생성한다.
3. 방금 생성한 항목에 접속해서 Permissions 탭에서 사용할 어플리케이션의 사용가능 권한을 세팅한다.

   

   우리는 Confluence API를 사용할 것이기 때문에 해당 항목의 권한을 설정한다. 이후에 OAuth 인증을 호출할때에 관련하여 권한을 다시 입력하지만, 본 페이지에서 허용한 권한보다 많은 권한을 요구할 수 없다.
4. Authorization 탭 → Configure 버튼을 눌러서 Callback URL을 설정해 준다.

   

   이후에 OAuth2.0 인증을 사용자가 완료하고 나면, 여기에 작성한 Callback URL로 인증코드가 쿼리파라미터로 전달된다. 아직 Listening이 가능한 주소가 없다면 접근 가능한 임시 URL을 작성하여 개발하고 이후에 수정하면 된다.
5. Settings 화면의 하단에 있는 Client ID 와 Secret 값을 저장해 둔다.
   

   

   이후 OAuth 인증유도 화면이나 인증코드를 활요한 토큰 생성시 필요한 값이다.

사용자 인증 화면 URL

구분	정보	비고
API 경로	https://auth.atlassian.com/authorize
매서드	GET
Query 파라미터1	scope	값 : 필요한 권한 목록 표 하단 참조
Query 파라미터2	redirect_uri	값: app 등록시 등록한 redirect주소
Query 파라미터3	state	값: 아무값이나 가능
Query 파라미터4	response_type	값: code (고정)
Query 파라미터5	prompt	값: consent (고정)
호출 목적	OAuth2.0 사용자 로그인 유도 화면 URL

scope 파라미터에 입력해야 하는 값은 사용할 API가 요구하는 권한에 따라 달라진다 여러개의 scope를 작성해야 하는 경우에는 공백(%20)으로 구분해서 전달하면된다. 필요한 scope는 Confluence API문서를 참조하면 각각의 API가 필요로 하는 scope가 명시되어 있으니 참고하여 작성하면 된다. 내가 만들 프로그램에서는 space와 content관련 읽기 권한만 있으면 되어서 scope값으로 아래와 같은 값을 전달하였다.

• 전달한 값 : read:confluence-space.summary read:confluence-content.summary

인증코드를 이용하여 토큰 생성

사용자 인증 페이지를 통해 사용자가 인증을 정상적으로 수행하고 나면, redirect_url 쪽으로 code 쿼리 파라미터에 인증코드가 담긴 요청이 리다이렉트 된다. 서버에서는 해당 값을 이용해서 Confluence서버로 부터 API 요청시 사용할 수 있는 토큰을 요청할 수 있게 된다.

구분	정보	비고
API 경로	https://auth.atlassian.com/oauth/token
매서드	POST
json 파라미터1	grant_type	값 : authorization_code (고정)
json 파라미터2	client_id	값: app 등록 후 생성된 id
json 파라미터3	client_secret	값: app 등록 후 생성된 secret
json 파라미터4	code	값: 전달받은 인증코드
json 파라미터5	redirect_uri	값: app 등록시 등록한 redirect주소
호출 목적	토큰 생성

토큰 활용하기

이러한 과정을 통해서 발급받은 토큰은 요청 헤더에 Authorization 를 추가하고, 값으로 Bearer 토큰 을 선언하여 API를 요청하는데 사용할 수 있다.

curl --request GET \
  --url https://api.atlassian.com/oauth/token/accessible-resources \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Accept: application/json'

API 호출 URL을 더욱 스마트하게

이전에 Confluence API를 호출할 때 현재 접속한 컨플루언스 스페이스 URL을 기준으로 뒤에 API주소를 붙여서 호출했었는데, 이렇게 하면 API호출시 사용하는 BaseURL이 사용자마다 달라지게 되어서 관리가 매우 어려웠다. 하지만, 이번에 OAuth2.0을 적용하면서 관련 문서의 내용을 살펴보니, 토큰에 부여된 권한으로 API질의가 가능한 항목에 대한 ID값을 조회하여 좀더 스마트하게 API를 호출하는 방법에 대한 가이드가 존재해서 기존의 URL호출방식에서 변경하기로 하였다.

• 기존 URL 형식 : https://<사용자Space명>.atlassian.net/wiki
• 신규 URL 형식 : https://api.atlassian.com/ex/confluence/<ID값>

구분	정보	비고
API 경로	https://api.atlassian.com/oauth/token/accessible-resources
매서드	POST
헤더	Authorization	값: Bearer <토큰>
호출 목적	조회할 항목 ID값 확인

예를 들어 호출할 ID값이 123asd456 이고, space목록을 조회하는 api /rest/api/space 를 호출하려고 하면 다음과 같은 주소로 호출하면 된다.

https://api.atlassian.com/ex/confluence/123asd456/rest/api/space