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