인증과 승인은 각각 ID를 확인하고 리소스에 대한 액세스 권한을 부여하는 데 사용되는 메커니즘입니다. 이 문서에서는 Chat 앱 및 Chat API 요청에 대한 인증 및 승인 작동 방식을 간략하게 설명합니다.
프로세스 개요
다음 다이어그램은 Google Chat의 인증 및 승인에 관한 대략적인 단계를 보여줍니다.
Google Cloud 프로젝트 구성, Chat API 사용 설정, Chat 앱 구성: 개발 중에 Google Cloud 프로젝트를 만듭니다. Google Cloud 프로젝트에서 Chat API를 사용 설정하고 Chat 앱을 구성하며 인증을 설정합니다. 자세한 내용은 Google Workspace에서 개발 및 Chat 앱 빌드를 참고하세요.
Chat API 호출: 앱에서 Chat API를 호출하면 인증 사용자 인증 정보가 Chat API로 전송됩니다. 앱이 서비스 계정으로 인증하는 경우 사용자 인증 정보는 앱 코드의 일부로 전송됩니다. 앱에서 아직 부여되지 않은 사용자 인증을 사용하여 Chat API를 호출해야 하는 경우 사용자에게 로그인하라는 메시지가 표시됩니다.
리소스 요청: 앱이 인증을 설정할 때 지정한 범위를 사용하여 액세스를 요청합니다.
동의 요청: 앱이 사용자로 인증하는 경우 Google에서는 사용자가 앱에 요청된 데이터에 대한 액세스 권한을 부여할지 결정할 수 있도록 OAuth 동의 화면을 표시합니다. 서비스 계정으로 인증할 때는 사용자 동의가 필요하지 않습니다.
승인된 리소스 요청 전송: 사용자가 승인 범위에 동의하면 앱은 사용자 인증 정보와 사용자가 승인한 범위를 요청에 번들로 묶습니다. 이 요청은 Google 승인 서버로 전송되어 액세스 토큰을 가져옵니다.
Google에서 액세스 토큰을 반환합니다. 액세스 토큰에는 부여된 범위 목록이 포함됩니다. 반환된 범위 목록이 요청된 범위보다 더 제한적이면 앱은 토큰으로 제한된 모든 기능을 사용 중지합니다.
요청된 리소스에 액세스: 앱은 Google의 액세스 토큰을 사용하여 Chat API를 호출하고 Chat API 리소스에 액세스합니다.
갱신 토큰 가져오기 (선택사항): 앱이 단일 액세스 토큰의 전체 기간을 초과하여 Google Chat API에 액세스해야 하는 경우 갱신 토큰을 가져올 수 있습니다. 자세한 내용은 OAuth 2.0을 사용하여 Google API에 액세스하기를 참고하세요.
리소스 추가 요청: 앱에 액세스 권한이 더 필요한 경우 사용자에게 새 범위를 부여하도록 요청하여 액세스 토큰을 가져오기 위한 새로운 요청이 발생합니다(3~6단계).
Chat 앱에 인증이 필요한 경우
채팅 앱은 사용자 상호작용에 대한 응답으로 메시지를 전송하거나 비동기식으로 전송할 수 있습니다. Chat 스페이스를 만들거나 Chat 스페이스의 사용자 목록을 가져오는 등 사용자를 대신해 할 일을 완료할 수도 있습니다.
Chat 앱이 응답을 처리하는 동안 Chat API 또는 다른 Google API를 호출하지 않는 한 Chat 앱은 사용자 상호작용에 응답하기 위해 인증이 필요하지 않습니다.
비동기 메시지를 보내거나 사용자를 대신하여 작업을 실행하기 위해 Chat 앱은 인증 및 승인이 필요한 Chat API에 RESTful 요청을 보냅니다.
사용자 상호작용에 대한 응답에는 인증이 필요하지 않음
Google Chat 앱은 사용자 또는 Chat 앱으로 인증할 필요 없이 상호작용 이벤트를 수신하고 이에 동기식으로 응답할 수 있습니다.
Google Chat 앱은 사용자가 Chat 앱과 상호작용하거나 Chat 앱을 호출할 때마다 다음과 같은 상호작용 이벤트를 수신합니다.
- 사용자가 Chat 앱으로 메시지를 보냅니다.
- 사용자가 Chat 앱을 @멘션합니다.
- 사용자가 Chat 앱의 명령어 중 하나를 호출합니다.
다음 다이어그램은 Chat 사용자와 Chat 앱 간의 요청-응답 시퀀스를 보여줍니다.
- 사용자가 Google Chat의 Chat 앱에 메시지를 보냅니다.
- Google Chat에서 메시지를 앱으로 전달합니다.
- 앱은 메시지를 수신하고 처리한 후 Google Chat에 응답을 반환합니다.
- Google Chat은 사용자를 위해 또는 스페이스에서 응답을 렌더링합니다.
이 시퀀스는 각 Chat 앱 상호작용 이벤트에 대해 반복됩니다.
비동기 메시지에는 인증이 필요합니다.
비동기 메시지는 Chat 앱이 인증 및 승인이 필요한 Chat API에 요청할 때 발생합니다.
Chat API를 호출하면 Chat 앱이 Google Chat에 메시지를 게시하거나 사용자를 대신하여 작업을 완료하고 데이터에 액세스할 수 있습니다. 예를 들어 서버 중단을 감지한 후 Chat 앱은 Chat API를 호출하여 다음을 실행할 수 있습니다.
- 서비스 중단을 조사하고 해결하는 데 전념하는 Chat 스페이스를 만듭니다.
- Chat 스페이스에 사용자를 추가합니다.
- Chat 스페이스에 메시지를 게시하여 서비스 중단에 관한 세부정보를 제공합니다.
다음 다이어그램은 Chat 앱과 Chat 스페이스 간의 비동기 메시지 시퀀스를 보여줍니다.
- Chat 앱은
spaces.messages.create메서드를 사용하여 Chat API를 호출하여 메시지를 만들고 HTTP 요청에 사용자 인증 정보를 포함합니다. - Google Chat은 서비스 계정 또는 사용자 인증 정보로 Chat 앱을 인증합니다.
- Google Chat이 지정된 Chat 스페이스에 앱의 메시지를 렌더링합니다.
Chat API 범위
OAuth 동의 화면 구성 및 범위 선택을 통해 사용자와 앱 검토자에게 표시할 정보를 정의하고 나중에 게시할 수 있도록 앱을 등록합니다.
앱에 부여된 액세스 수준을 정의하려면 승인 범위를 식별하고 선언해야 합니다. 승인 범위는 Google Workspace 앱 이름, 액세스하는 데이터 유형, 액세스 수준이 포함된 OAuth 2.0 URI 문자열입니다.
민감하지 않은 범위
| 범위 코드 | 설명 |
|---|---|
https://www.googleapis.com/auth/chat.bot
|
Chat 앱에서 채팅을 보고 메시지를 보낼 수 있습니다. 이 범위는 서비스 계정으로 앱 인증만 지원합니다. 이 범위를 사용하여 사용자 사용자 인증 정보 또는 도메인 전체 위임으로 인증할 수 없습니다. |
민감한 범위
| 범위 코드 | 설명 |
|---|---|
https://www.googleapis.com/auth/chat.spaces
|
Chat에서 대화 및 스페이스를 만들고 메타데이터 (기록 설정 및 액세스 설정 포함)를 보거나 수정합니다. |
https://www.googleapis.com/auth/chat.spaces.create
|
Chat에서 새 대화를 만듭니다. |
https://www.googleapis.com/auth/chat.spaces.readonly
|
Chat에서 채팅 및 스페이스를 봅니다. |
https://www.googleapis.com/auth/chat.memberships
|
Chat의 대화에서 참여자를 확인, 추가, 업데이트, 삭제합니다. |
https://www.googleapis.com/auth/chat.memberships.app
|
Google Chat의 대화에서 자체적으로 추가 및 삭제합니다. |
https://www.googleapis.com/auth/chat.memberships.readonly
|
Chat 대화 참여자 보기 |
https://www.googleapis.com/auth/chat.messages.create
|
Chat에서 메시지를 작성하고 보냅니다. |
https://www.googleapis.com/auth/chat.messages.reactions
|
Chat에서 메시지에 대한 반응을 확인, 추가, 삭제합니다. |
https://www.googleapis.com/auth/chat.messages.reactions.create
|
Chat에서 메시지에 반응을 추가합니다. |
https://www.googleapis.com/auth/chat.messages.reactions.readonly
|
Chat에서 메시지에 대한 반응을 확인합니다. |
https://www.googleapis.com/auth/chat.users.readstate
|
Chat 대화의 마지막으로 읽은 시간 확인 및 수정 |
https://www.googleapis.com/auth/chat.users.readstate.readonly
|
Chat 대화를 마지막으로 읽은 시간 보기 |
https://www.googleapis.com/auth/chat.admin.spaces.readonly
|
Chat에서 관리자 도메인이 소유한 채팅 및 스페이스를 볼 수 있습니다. |
https://www.googleapis.com/auth/chat.admin.spaces
|
Chat에서 관리자 도메인이 소유한 채팅 및 스페이스를 보거나 수정합니다. |
https://www.googleapis.com/auth/chat.admin.memberships.readonly
|
Chat에서 관리자의 도메인이 소유한 대화의 참여자 및 관리자를 확인합니다. |
https://www.googleapis.com/auth/chat.admin.memberships
|
Chat에서 관리자 도메인이 소유한 대화의 참여자 및 관리자를 확인, 추가, 업데이트, 삭제합니다. |
https://www.googleapis.com/auth/chat.app.spaces
|
Chat에서 대화 및 스페이스를 만들고 메타데이터 (기록 설정 및 액세스 설정 포함)를 보거나 업데이트합니다. 관리자 승인이 필요합니다. 이 범위는 서비스 계정으로 앱 인증만 지원합니다. 이 범위를 사용하여 사용자 사용자 인증 정보 또는 도메인 전체 위임으로 인증할 수 없습니다. |
https://www.googleapis.com/auth/chat.app.spaces.create
|
Chat에서 새 대화 및 스페이스를 만듭니다. 관리자 승인이 필요합니다. 이 범위는 서비스 계정으로 앱 인증만 지원합니다. 이 범위를 사용하여 사용자 사용자 인증 정보 또는 도메인 전체 위임으로 인증할 수 없습니다. |
https://www.googleapis.com/auth/chat.app.memberships
|
Chat의 대화 및 스페이스에서 참여자를 확인, 추가, 업데이트, 삭제합니다. 관리자 승인이 필요합니다. 이 범위는 서비스 계정으로 앱 인증만 지원합니다. 이 범위를 사용하여 사용자 사용자 인증 정보 또는 도메인 전체 위임으로 인증할 수 없습니다. |
https://www.googleapis.com/auth/chat.customemojis
|
Chat에서 맞춤 이모티콘을 보고 만들고 삭제합니다. |
https://www.googleapis.com/auth/chat.customemojis.readonly
|
Chat에서 맞춤 이모티콘을 봅니다. |
https://www.googleapis.com/auth/chat.users.spacesettings
|
Chat 사용자 스페이스 설정을 보고 업데이트합니다. |
제한된 범위
| 범위 코드 | 설명 |
|---|---|
https://www.googleapis.com/auth/chat.delete
|
Chat에서 대화 및 스페이스를 삭제하고 관련 파일에 대한 액세스 권한을 삭제합니다. |
https://www.googleapis.com/auth/chat.import
|
스페이스, 메시지, 멤버십을 Chat으로 가져옵니다. 자세한 내용은 Chat 앱이 데이터를 가져오도록 승인하기를 참고하세요. |
https://www.googleapis.com/auth/chat.messages
|
메시지 보기, 작성, 전송, 업데이트, 삭제 및 메시지에 대한 반응 추가, 보기, 삭제 |
https://www.googleapis.com/auth/chat.messages.readonly
|
Chat에서 메시지와 반응을 확인합니다. |
https://www.googleapis.com/auth/chat.admin.delete
|
관리자의 도메인이 소유한 대화 및 스페이스를 삭제하고 Chat에서 관련 파일에 대한 액세스 권한을 삭제합니다. |
https://www.googleapis.com/auth/chat.app.delete
|
Chat에서 대화 및 스페이스를 삭제하고 관련 파일에 대한 액세스 권한을 삭제합니다. 관리자 승인이 필요합니다. 이 범위는 서비스 계정으로 앱 인증만 지원합니다. 이 범위를 사용하여 사용자 사용자 인증 정보 또는 도메인 전체 위임으로 인증할 수 없습니다. |
위 표의 범위는 다음 정의에 따라 민감도를 나타냅니다.
비민감한 정보: 이러한 범위는 승인 액세스의 가장 작은 영역을 제공하며 기본 앱 인증만 필요합니다. 이 요구사항에 관한 자세한 내용은 인증을 준비하는 단계를 참고하세요.
민감한 정보: 이 범위는 사용자로부터 승인을 받은 후 앱이 특정 사용자의 Google 데이터에 액세스할 수 있도록 허용합니다. 추가 앱 인증을 거쳐야 합니다. 이 요구사항에 관한 자세한 내용은 민감한 범위를 요청하는 앱의 단계를 참고하세요.
제한됨: 이러한 범위는 Google 사용자 데이터에 대한 광범위한 액세스 권한을 제공하며 제한된 범위 인증 절차를 거쳐야 합니다. 이 요구사항에 관한 자세한 내용은 Google API 서비스: 사용자 데이터 정책 및 특정 API 범위에 대한 추가 요구사항을 참고하세요. 제한된 범위를 요청하는 앱의 단계도 참고하세요.
앱에 다른 Google API에 대한 액세스 권한이 필요한 경우 해당 범위도 추가할 수 있습니다. Google API 범위에 관한 자세한 내용은 OAuth 2.0을 사용하여 Google API에 액세스를 참고하세요.
Google Workspace API의 범위에 대해 자세히 알아보려면 OAuth 동의 화면 구성 및 범위 선택을 참고하세요.
필수 인증 유형
Chat 앱이 Chat API로 인증 및 승인하는 방법에는 두 가지가 있습니다.
- 사용자 인증
- 사용자 인증을 사용하면 Chat 앱이 사용자 데이터에 액세스하고 사용자를 대신하여 작업을 완료할 수 있습니다. OAuth 범위는 승인된 데이터와 작업을 지정합니다. Chat 앱이 관리자가 설치했거나 도메인 전체 위임을 받은 것이 아니라면 Chat 앱이 사용자를 대신하여 작업을 처음 실행할 때 사용자는 OAuth 동의 화면을 사용하여 Chat 앱을 승인해야 합니다.
- 앱 인증
앱 인증을 사용하면 Chat 앱이 서비스 계정 사용자 인증 정보를 사용하고 데이터에 액세스하며 자체적으로 작업을 완료할 수 있습니다. Chat 앱은 자체 사용자 인증 정보를 사용하여 리소스에 액세스하고 작업하므로 최종 사용자는 Chat 앱의 API 호출을 승인할 필요가 없으며 앱 승인을 지원하는 OAuth 승인 범위를 OAuth 동의 화면에 추가할 수 없습니다.
다음 두 가지 유형의 OAuth 승인 범위가 앱 인증을 지원합니다.
https://www.googleapis.com/auth/chat.bot: Chat 앱은 이 승인 범위를 지원하는 Google Chat API 메서드를 호출하여 액세스할 수 있는 리소스(예: 최종 사용자가 Chat 앱을 추가한 스페이스의 메시지)를 만들거나, 업데이트하거나, 가져오거나, 나열하거나, 삭제할 수 있습니다. Chat 앱은 관리자 또는 최종 사용자 승인 없이 이 승인 범위를 자체 부여할 수 있습니다.https://www.googleapis.com/auth/chat.app.*(개발자 프리뷰): 이 범위를 사용하려면 일회성 관리자 승인이 필요합니다. 관리자 승인을 받으려면 Google Workspace Marketplace 호환 OAuth 클라이언트를 만들고 Google Workspace Marketplace SDK에서 앱을 구성하여 Chat 앱의 서비스 계정이 관리자 승인을 받을 수 있도록 준비합니다. 이러한 범위를 사용하면 Chat 앱에서 특정 Google Chat API 메서드를 호출할 수 있습니다. 예를 들어chat.app.spaces.create는 앱이 Chat 스페이스를 만들도록 허용합니다.
메서드가 사용자 인증과 앱 인증을 모두 지원하는 경우 Chat API는 사용하는 인증 유형에 따라 다른 결과를 반환합니다.
- 앱 인증을 사용하면 메서드는 채팅 앱에서 액세스할 수 있는 리소스만 반환합니다.
- 사용자 인증을 사용하면 메서드는 사용자가 액세스할 수 있는 리소스만 반환합니다.
예를 들어 앱 승인으로 spaces.list() 메서드를 호출하면 Chat 앱이 참여 중인 스페이스 목록이 반환됩니다.
사용자 승인으로 spaces.list()를 호출하면 사용자가 회원으로 있는 스페이스 목록이 반환됩니다. 실제로는 Chat 앱의 설계 및 기능에 따라 Chat API를 호출할 때 두 가지 유형의 인증을 모두 사용할 수 있습니다.
비동기 Chat API 호출
다음 표에는 Chat API 메서드와 지원되는 승인 범위가 나와 있습니다.
| 메서드 | 사용자 인증 지원 | 앱 인증 지원 | 지원되는 승인 범위 | |
|---|---|---|---|---|
| 스페이스 | ||||
| 스페이스 만들기 |
사용자 인증을 사용하면 다음과 같습니다.
|
|||
| 스페이스 설정하기 | — |
사용자 인증을 사용하면 다음과 같습니다.
|
||
| 스페이스 가져오기 |
사용자 인증을 사용하면 다음과 같습니다.
|
|||
| 스페이스 나열 |
사용자 인증을 사용하면 다음과 같습니다.
|
|||
| 검색 공간 | — |
관리자 권한을 사용하는 사용자 인증:
|
||
| 스페이스 업데이트하기 |
사용자 인증을 사용하면 다음과 같습니다.
|
|||
| 스페이스 삭제하기 |
사용자 인증을 사용하면 다음과 같습니다.
|
|||
| 스페이스 가져오기 프로세스 완료하기 | — |
사용자 인증을 사용하면 다음과 같습니다.
|
||
| 채팅 메시지 찾기 |
사용자 인증을 사용하면 다음과 같습니다.
|
|||
| 구성원 | ||||
| 멤버 만들기 |
사용자 인증을 사용하면 다음과 같습니다.
|
|||
| 멤버 가입하기 |
사용자 인증을 사용하면 다음과 같습니다.
|
|||
| 구성원 목록 |
사용자 인증을 사용하면 다음과 같습니다.
|
|||
| 회원 삭제하기 |
사용자 인증을 사용하면 다음과 같습니다.
|
|||
| 멤버 업데이트하기 |
사용자 인증을 사용하면 다음과 같습니다.
|
|||
| 메시지 | ||||
| 메시지 작성하기 |
사용자 인증을 사용하면 다음과 같습니다.
|
|||
| 메시지 받기 |
사용자 인증을 사용하면 다음과 같습니다.
|
|||
| 메시지 목록 | — |
사용자 인증을 사용하면 다음과 같습니다.
|
||
| 메시지 업데이트하기 |
사용자 인증을 사용하면 다음과 같습니다.
|
|||
| 메시지 삭제하기 |
사용자 인증을 사용하면 다음과 같습니다.
|
|||
| 리액션 | ||||
| 리액션 만들기 | — |
사용자 인증을 사용하면 다음과 같습니다.
|
||
| 리액션 나열 | — |
사용자 인증을 사용하면 다음과 같습니다.
|
||
| 리액션 삭제하기 | — |
사용자 인증을 사용하면 다음과 같습니다.
|
||
| 맞춤 그림 이모티콘 | ||||
| 맞춤 이모티콘 만들기 | — |
사용자 인증을 사용하면 다음과 같습니다.
|
||
| 맞춤 이모티콘 삭제하기 | — |
사용자 인증을 사용하면 다음과 같습니다.
|
||
| 맞춤 그림 이모티콘 사용하기 | — |
사용자 인증을 사용하면 다음과 같습니다.
|
||
| 맞춤 그림 이모티콘 나열 | — |
사용자 인증을 사용하면 다음과 같습니다.
|
||
| 미디어 및 첨부파일 | ||||
| 미디어를 파일 첨부파일로 업로드하기 | — |
사용자 인증을 사용하면 다음과 같습니다.
|
||
| 미디어 다운로드 |
사용자 인증을 사용하면 다음과 같습니다.
|
|||
| 메시지 첨부파일 가져오기 | — |
앱 인증을 사용하는 경우:
|
||
| 사용자 읽기 상태 | ||||
| 사용자의 스페이스 읽기 상태 가져오기 | — |
사용자 인증을 사용하면 다음과 같습니다.
|
||
| 사용자의 스페이스 읽기 상태 업데이트 | — |
사용자 인증을 사용하면 다음과 같습니다.
|
||
| 사용자의 대화목록 읽기 상태 가져오기 | — |
사용자 인증을 사용하면 다음과 같습니다.
|
||
| 사용자 스페이스 설정 | ||||
| 사용자의 스페이스 알림 설정 가져오기 | — |
사용자 인증을 사용하면 다음과 같습니다.
|
||
| 사용자의 스페이스 알림 설정 업데이트하기 | — |
사용자 인증을 사용하면 다음과 같습니다.
|
||
| 스페이스 이벤트 | ||||
| 스페이스 이벤트 가져오기 | — |
사용자 인증을 사용하려면
이벤트 유형에 따라 범위를 사용해야 합니다.
|
||
| 스페이스 이벤트 목록 표시 | — |
사용자 인증을 사용하면 요청에 포함된 각
이벤트 유형에 범위를 사용해야 합니다.
|
||
Chat 앱 상호작용 이벤트
다음 표에는 사용자가 채팅 앱과 상호작용하는 일반적인 방법과 인증이 필요한지 또는 지원되는지 여부가 나와 있습니다.
| 시나리오 | 인증 필요 없음 | 사용자 인증 지원 | 앱 인증 지원 | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 다음에서 메시지를 수신할 수 있습니다. |
|
|||||||||||||||
| 메시지에 응답하기 |
|
|||||||||||||||
| 새 메시지 보내기 |
|
|||||||||||||||
관련 주제
- Google Workspace의 인증 및 승인에 관한 개요는 인증 및 승인에 대해 알아보기를 참고하세요.
- Google Cloud의 인증 및 권한 부여에 관한 개요는 인증 개요를 참고하세요.
- 서비스 계정에 대한 자세한 내용은 서비스 계정을 참고하세요.
- Google API에서 OAuth 2.0을 사용하는 방법에 관한 자세한 내용은 OAuth 2.0을 사용하여 Google API에 액세스를 참고하세요.
- 사용자 인증 정보 또는 서비스 계정으로 인증 및 승인을 설정합니다.