트위터 API 플랫폼과 OAuth – Access Token 얻기

이 글은 트위터 API 플랫폼과 OAuth – Twitter for Websites에서 이어지는 글입니다.

OAuth?

OAuth 로고. 저는 볼때마다 치과가 떠오르네요..

OAuth에 관한 자세한 설명은 네이버 개발자센터의 소개글을 한 번 읽어보시면 좋습니다.

OAuth 간단 요약

먼저 API를 제공해 주는 곳을 서비스 프로바이더(트위터)라고 부릅니다. 그리고 서비스 프로바이더의 API를 사용하는 쪽을 컨슈머(여러분의 애플리케이션)라고 부르죠. 그리고 사용자란 컨슈머의 서비스를 사용하는 사람들 입니다. 컨슈머는 서비스 프로바이더에 자신의 애플리케이션과 관련된 정보를 입력한 후, 컨슈머 키와 시크릿을 발급 받습니다. 이것은 OAuth 이전의 API Key와 비슷한 거라고 생각하셔도 되겠습니다. 애플리케이션에 관한 정보를 입력할 때 주의하실 점은 나중에 OAuth 인증진행 중, 사용자에게 노출이 된다는 점입니다.

애플리케이션 등록 화면

등록한 정보는 이런식으로 사용자에게 노출됩니다

위 그림은 애플리케이션 등록 화면인데요. 여기서 약간 애매한 부분이 웹사이트 URL과 콜백 URL입니다. 트위터는 완전한 형태의 URL이 필요하기 때문에 테스트 용도로 사용하기 위한 http:://localhost:8080/ 형태는 사용이 불가능합니다. 그래서 구글링을 통해 약간의 꼼수를 부린건데요. 물론, hosts파일에 127.0.0.1 local.dev 식으로 사용할 것을 만들어 주셔야 합니다. 이 방법이 귀찮다면 그냥 127.0.0.1로 하셔도 됩니다 🙂

컨슈머 키와 시크릿이 있는 상태에서 OAuth 인증 플로우가 시작됩니다:

callback이 있는 OAuth 인증 과정

컨슈머는 먼저 컨슈머 키와 시크릿을 사용해서 Request Token(트위터에선 oauth token이라고도 쓰이며 토큰은 키와 값의 쌍이며 Request Token의 경우 매번 달라집니다)을 발급 받습니다. Request Token은 해당 컨슈머를 대변한다고 보시면 되겠습니다. 자~ 이제 컨슈머는 됐으니 사용자를 대변할 Access Token을 받아야겠죠? 결국 서비스 프로바이더의 API를 사용한다는 것은 특정 사용자를 대신해 컨슈머가 서비스 프로바이더에게 해당 사용자 대신 API 요청을 하는 것이고, 그렇다면 해당 사용자가 정말 이 컨슈머에게 권한을 위임했는지 서비스 프로바이더가 알아야 할 것입니다. 이 역할을 하는 것이 Access Token 되겠습니다.

트위터가 Request Token을 발급해 주면 컨슈머는 사용자를 서비스 프로바이더로 보내 인증을 받고, Access Token을 얻기 위해 verifier 값을 얻어야 합니다. 그래서 위의 두 번째 그림처럼 컨슈머의 계정 사용 여부를 물어보는 것이죠. 만약 로그인 정보 쿠키가 남아있다면 두 번째 그림이 아니라 컨슈머를 허용할지에 대한 화면이 나타납니다.

로그인 정보가 있다면 간단히 컨슈머 허용 여부만 물어봅니다

만약 예전에 허용을 했었고(트위터 마이페이지 applications 탭에서 확인 가능), 로그인 정보도 있다면 바로 verifier 값을 얻을 수 있으며, 이 verifier 값과 Request Token 정보를 트위터에 보내서 최종적으로 Access Token을 발급받게 됩니다.

트위터의 OAuth

트위터는 현재 OAuth 1.0a 스펙을 구현 중이며, 조만간 2.0을 제공할 것 같습니다. OAuth가 기존 인증 절차와 어떻게 다른지는 moving-from-basic-auth-to-oauth에 잘 설명돼 있습니다.

제 생각에 OAuth는 두 가지 큰 특징을 가지는 것 같습니다:

• 사용자 계정 정보를 애플리케이션에서 관리하지 않는다.
• 인증 절차를 서비스 프로바이더에게 위임한다.

즉, 컨슈머의 사용자는 적합한 절차를 거쳐 서비스 프로바이더에게 컨슈머가 자신을 대신해 해당 서비스를 이용할 수 있다는 권한을 위임하게 되며, 이를 확인하기 위해 기존의 사용자 계정 정보 대신 Access Token을 이용합니다. 컨슈머는 Access Token을 가지고 해당 사용자 대신 서비스 프로바이더의 API를 호출합니다.

Access Token은 한 번 발급 받으면 다른 정보(로그인 정보, Request Token 등)가 전혀 필요없이 바로 API 호출이 가능하게 되며, 사용자가 계정 정보를 변경(패스워드 변경 등)했다고 하더라도 이 Access Token은 유효합니다.

Access Token의 유효기간은 서비스 프로바이더의 정책에 따라 다른 부분이 있는데, 트위터 OAuth faq를 확인해 보면 현재 Access Token의 유효기간은 없다(!)고 명시하고 있습니다. 따라서 토큰 보관에 주의를 하실 필요가 있을겁니다. Access Token의 유효기간이 없긴 하지만 사용자가 자신의 계정 설정에서 애플리케이션을 명시적으로 거부하거나 관리자가 제한한 경우에 Access Token이 만료될 수 있습니다.

내 계정에 접근할 수 있는 애플리케이션 목록

애플리케이션 종류에 따른 OAuth 인증

트위터에서는 OAuth 인증에 관해서 여러가지 방법을 제공해 주고 있습니다. 그렇다고 OAuth 스펙을 무시하는 것은 아니며 기본 흐름은 같되 세부적인 방법이 다른 것인데요. 특정 플랫폼에서 사용이 권장되는 것과 제한되는 것이 있습니다. 관련 정보는 공식 문서인 Which authorization path should I choose?를 읽어보세요. 아래는 이 문서를 요약한 것입니다:

웹 애플리케이션

콜백 방식의 OAuth를 사용해야 합니다. xAuth 방식은 사용할 수 없습니다.

써드 파티애플리케이션 이용

OAuth Echo라고 부르며 Twitpic, yfrog 같은 트위터 에코 시스템에 속하는 써드 파티 애플리케이션을 통해서 인증 및 API 호출을 위임하는 것을 말합니다.

위 두가지 방식이 웹 애플리케이션에서 권장됩니다. 모바일과 데스크탑 애플리케이션의 경우, 콜백 URL 방식을 사용하기 어렵거나 사실상 불가능 할 수도 있기 때문에 트위터에선 아래 두 가지 방법을 제공해 줍니다.

Out-of-band/PIN 코드 인증(oob)

콜백 URL OAuth 방식과 거의 흡사한데요. 콜백을 하는 대신에 컨슈머에게 특정 URL을 리턴해 줍니다. 접속하면 PIN 코드라 불리는 몇 자리 숫자가 나타나는데요. 이 숫자를 복사해서 다시 서비스 프로바이더에게 보내면 Access Token을 발급해 줍니다. 아마 핸드폰으로 소액결제 해보셨으니 그리 낯설지 않은 방식이라고 생각되네요 🙂

xAuth

xAuth 인증 방식은 우리가 많이 사용하고 있는 방식으로 사용자 계정 정보를 이용해서 Access Token을 발급받게 됩니다. xAuth 또한 OAuth 플로우를 거치며, 단지 Request Token을 얻는 부분과 사용자 승인 과정이 없을 뿐입니다. xAuth는 XAuth와는 다르며, 데스크탑과 모바일에서만 사용 가능합니다. 콜백 방식과 PIN코드 사용이 어려울 때, api@twitter.com에 메일을 보내 사용 동의를 얻어야 합니다.

Callback URL OAuth 자세히 살펴보기

애플리케이션 종류에 따른 OAuth 인증에서도 살펴 봤듯이 트위터에서는 OAuth 인증 방식에 몇 가지 옵션을 주고 있지만, 제가 웹 개발자라서 Callback URL을 사용하는 OAuth를 조금 더 자세히 살펴보겠습니다. 사실 다른 OAuth 방법들도 여기서 크게 벗어나지 않습니다.

1단계. Request Token 얻기

먼저, 앞서 살펴봤듯이 자신의 애플리케이션을 등록해 컨슈머 키/시크릿을 발급받습니다. 다음으로 Request Token을 발급 받기위해 http://dev.twitter.com/oauth/request_token을 POST로 호출합니다. 이때 컨슈머 키, 시크릿, OAuth 콜백 URL 등을 같이 보내야 합니다.

Request Token 요청을 위한 헤더의 예

그러면 트위터에서 Request Token(또는 OAuth Token)을 발급해 줍니다.

Request Token을 생성한 후 보내주는 응답 헤더의 예

2단계. 사용자 리다이렉트 하기

Request Token 발급 후, 사용자의 인증을 받기 위해 https://api.twitter.com/oauth/authenticate로 리다이렉트 해야합니다. 트위터 REST API OAuth 부분을 보면 /oauth/authenticate 외에 /oauth/authorize도 제공되는데요. authorize의 경우 사용자가 기존에 컨슈머 애플리케이션을 인증 했다고 하더라도 다시 인증 화면이 나타납니다. 반면에 authenticate는 이전에 사용자가 인증을 했다면 이 부분을 바로 넘어가 버립니다.  OAuth 1.0 스펙에서는 사용자가 반드시 해당 애플리케이션에게 자신의 권한을 줄 것인지 아닌지에 대해서 선택을 할 수 있게하라고 명시돼 있습니다. authenticate는 편의를 위해 이 부분을 대체한 것이라고 보면 되겠습니다.

로그인 정보가 없다면 로그인 및 애플리케이션 사용 동의 창이 나타나며, 로그인을 했다면 간단히 동의 페이지가 나타납니다. 이렇게 사용자 인증까지 마치면 트위터는 oauth_verifier라는 값을 넘겨줍니다.

사용자 인증 및 verifier 얻어오기

3단계. Request Token을 Access Token으로 교환하기

Request Token과 oauth_verifier 값을 가지고 https://api.twitter.com/oauth/access_token을 POST 방식으로 호출하면 Access Token을 얻게 됩니다.

드디어 Access Token을.. ;ㅁ;

트위터 API 라이브러리

트위터에서 제공하는 공식 OAuth 라이브러리는 없으며, REST API만을 제공하고 있습니다. 비공식적으로는 다양한 언어를 기반으로 하는 여러가지 구현체가 있으며, 그 중 트위터 공식 홈페이지에 등록된 Java 구현체는 총 3개 입니다. Java 구현체 중, Scribe의 경우 트위터 REST/Stream API 구현체는 아니지만 OAuth인증에 관한 범용적인 라이브러리를 제공합니다. Scribe의 예제 코드를 보면 다양한 SNS를 볼 수 있는데, 이 예제 중 트위터쪽은 PIN 코드 방식이므로 궁금하시면 한 번 돌려보세요.

트위터 파일럿 프로젝트

처음으로 Github에 프로젝트를 공유해 보네요. Spring Framework 3.0 기반에 Scribe 라이브러리를 사용했습니다. 관심 있으신 분들은 한 번 돌려보시고 참여도 좀.. 🙂

https://github.com/ethdemor/social-api-pilot

개발 시 고려사항

파일럿 프로젝트를 만들다 알게된 사실인데, 사용자가 계정 설정에서 해당 컨슈머를 revoke 한 경우, Access Token이 파기됩니다. 그런데 컨슈머 쪽에서는 Access Token이 파기 됐다고 연락 같은거 못받으니 문제가 생길 수 있습니다. 바로 만료된 Access Token으로 트위터 API를 호출한 경우인데요. 문제는 트위터쪽에선 무조건 200 OK 응답 코드를 준다는 것입니다. 만약 타임라인을 가져오려고 할 경우 사용자 입장에서 에러는 안뜨는데 목록은 하나도 안보이는 경우가 발생할 수 있겠죠. 트위터는 응답 코드는 200 OK지만 status 코드에 에러 정보를 넣어주니 이를 확인해서 대처해야 합니다.

Access Token이 사용 가능한지는 다음 API를 호출해 보면 됩니다:

GET account/verify_credentials

만약 현재 Access token이 사용할 수 없는 것이라면 HTTP 응답 헤더 status 코드가 401 Unauthorized로 세팅됩니다. 따라서 status 값이 401일 때, 다시 OAuth 인증을 받게 하면 이 문제를 해결 할 수 있을 것 같습니다.