Google API, OAuth 2.0 앱 인증 프로세스 분석

Google API Console

• Google API Console은 구글이 제공하는 방대한 API를 클라이언트 입장에서 통합 관리할 수 있게 해주는 웹 서비스로 2010년 개시하였다.

OAuth 2.0 client_id 발급

• Google API를 이용하기 위해서는 가장 먼저 개인 또는 회사(유료 플랜 이용시 권장) 명의의 Google 계정이 필요하다.


• 하나의 구글 계정으로 최대 10개의 프로젝트를 생성할 수 있다. 프로젝트를 생성하면 project_number(ex: 257124386236)를 부여 받는데 각 API 이용시 App ID로 사용된다.


• 각 프로젝트마다 연관된 설정 가능한 정보를 묶어 resource라고 부른다. 가장 기본적인 정보로 project_name, project_id, project_number가 있다.


• 각 프로젝트는 임의로 Shut Down이 가능하다. 셧다운시 모든 과금과 트래픽이 중단된다. 셧다운 후 30일이 지난 프로젝트는 자동 삭제된다.


• 각 프로젝트마다 n개의 client_id를 생성할 수 있다. 생성 즉시 client_id, client_secret이 발급되며 언제든지 관련 정보를 조회할 수 있다.


• client_secret을 재발급 받을 수 있다. 재발급 즉시 기존의 client_secret는 무효화된다.


• 각 client_id는 n개의 redirect_uri를 설정할 수 있다. http, https로 시작하는 호스트네임을 가진 완전한 URL만 등록이 허용된다. 아이피 주소는 허용되지 않는다.


• 프로젝트에 client_id를 생성하면 Google이 제공하는 모든 API(2017년 10월 현재 총 177개)를 이용할 수 있다.

OAuth 2.0 Scope

• 구글이 제공하는 전체 177개 API 전 영역에 걸쳐 고유한 scope를 제공한다. Google Drive API를 예로 들면 아래와 같다. 아래 scope들은 사용자에게 권한부여 위임 요청시 파라메터에 그대로 사용된다. 각 scope는 스페이스(%20)로 구분된다.

https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.file
https://www.googleapis.com/auth/drive.metadata
https://www.googleapis.com/auth/drive.metadata.readonly
https://www.googleapis.com/auth/drive.photos.readonly
https://www.googleapis.com/auth/drive.readonly

• https://www.googleapis.com/auth/까지는 동일하며 뒤에는 API 이름, API의 리소스 이름, 해당 리소스의 허용 범위를 닷(.) 기호로 구분한다.

Google API 호출

• OAuth 2.0 인증이 완료되면 access_token을 발급 받는다. 클라이언트에서는 각 API 호출시 Authorization: Bearer 헤더 값에 access_token 값을 명시하면 된다. Google Drive의 파일 목록을 요청하는 API를 호출하는 것을 예로 들면 아래와 같다.

GET https://www.googleapis.com/drive/v3/files
Authorization: Bearer ya29.GlvmBPbtXsjV0Q284FxTXHwPtWDKPj1rbfmOxDYkC-045xDpD7u6UfmIb-vCBCLDBuvoqDWdipfHeC1mYTjpC1XE2Ktcoac6TSKWy01EGN5TblSAU7nJ2EOwcZnz

온라인 액세스, 오프라인 액세스

• 클라이언트가 사용자에게 권한 부여에 동의하는 페이지를 출력하기 위해 Google의 웹 페이지로 리다이렉트할 때 클라이언트는 서버 측에 access_type 파라메터를 전달할 수 있다. 파라메터를 생략할 경우 기본 값은 online으로 설정되며 offline을 전달할 수 있다.


• online으로 설정하면 클라이언트에게 refresh_token을 내려주지 않는다. 사용자의 권한 부여 동의 후 클라이언트가 획득한 access_token이 만료되면 사용자에게 다시 권한 부여 동의를 요청하는 과정을 반복해야 한다.


• offline으로 설정하면 클라이언트에게 refresh_token을 내려준다. 시간이 흘러 access_token이 만료되어도 사용자의 개입 없이 클라이언트 스스로 내려받은 refresh_token을 이용하여 새로운 access_token을 발급 받을 수 있다.


• 즉, Google의 온라인 액세스, 오프라인 액세스 개념은 OAuth 2.0 사양의 refresh_token를 다르게 해석하는 개념일 뿐이다.

refresh_token의 라이프 사이클

• Google은 최초 사용자의 권한 부여 동의 후 발급된 refresh_token의 만료 시간에 제한을 두지 않는다. 즉, 무제한이다. access_token의 만료 시간을 짧게 두고 반영구적인 refresh_token으로 access_token을 재발급한다.


• 한 번 발급된 refresh_token은 사용자가 클라이언트에 대한 권한 부여 동의를 취소(revoke)하기 전까지 유효하다.


• refresh_token이 무한정 발급되는 것은 아니다. 클라이언트, 사용자 그룹 단위로 발급 한도가 존재하며 발급이 초과되면 가장 오래된 refresh_token이 만료된다.

참고 글

• Introducing the Google API Console
• OAuth 2.0 Scopes for Google APIs
• Using OAuth 2.0 to Access Google APIs
• Using OAuth 2.0 for Web Server Applications
• Auth0 - Understanding Refresh Tokens