IAM 계정을 사용하여 연결

이 페이지에서는 Identity and Access Management(IAM)로 준비된 계정을 사용하여 PostgreSQL용 AlloyDB 인스턴스에 로그인하는 과정을 설명합니다. psql 명령줄 클라이언트를 사용해 IAM 기반 로그인을 수행하는 방법을 예시로 보여줍니다.

AlloyDB 인스턴스 연결 개요는 연결 개요를 참조하세요.

시작하기 전에

IAM 사용자 인증 정보를 사용하여 AlloyDB 인스턴스에 로그인하려면 프로젝트, 클러스터, 인스턴스, IAM 사용자 계정을 모두 미리 준비해야 합니다.

자세한 내용은 IAM 인증 관리를 참조하세요.

OAuth 2.0 토큰으로 인증

사용자 또는 애플리케이션은 다음 단계에 따라 AlloyDB 데이터베이스에 인증할 수 있습니다.

아직 설정하지 않았다면 AlloyDB 인스턴스에 로그인하려는 동일한 사용자 또는 서비스 계정으로 Google Cloud CLI를 승인하세요.
gcloud auth print-access-token 명령어를 사용하여 Google Cloud 에서 OAuth 2.0 토큰을 요청하세요.
```
gcloud auth print-access-token
```
Google Cloud 는 OAuth 2.0 토큰을 이 명령어의 출력으로 표시합니다.

추가 보안을 위해 다음 대체 단계에 따라 토큰을 AlloyDB 인증에만 사용하도록 제한할 수 있습니다.
1. 아직 수행하지 않았다면, gcloud auth application-default login 명령어를 사용해 현재 환경의 액세스 사용자 인증 정보에 alloydb.login 범위를 추가합니다.
```
gcloud auth application-default login --scopes=https://www.googleapis.com/auth/alloydb.login,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,openid
```
2. gcloud auth application-default print-access-token 명령어를 사용해 AlloyDB 인증에만 사용되도록 범위가 제한된 OAuth 2.0 토큰을 출력합니다.
```
gcloud auth application-default print-access-token –-scopes=https://www.googleapis.com/auth/alloydb.login
```
주의: OAuth 2.0 토큰은 민감한 정보로 취급해야 합니다. 사용 후 안전하게 저장하거나, 아예 저장하지 마세요.

OAuth 2.0 토큰은 본인 또는 다른 사용자가 사용자의 권한으로 Google Cloud 에 인증된 요청을 수행할 수 있게 합니다. 토큰은 비밀번호와 동일한 수준의 보안으로 취급해야 합니다. 토큰을 안전하게 저장하거나, 가능하면 저장하지 않도록 하세요. 이 페이지 후반의 psql 사용 예시에서는 OAuth 2.0 토큰을 요청하고 사용한 뒤 바로 폐기하는 단일 작업 방식을 보여줍니다.
다음 사용자 인증 정보를 사용하여 표준 PostgreSQL 방식으로 AlloyDB 인스턴스에 로그인합니다.
- 이전 단계에서 얻은 액세스 토큰을 비밀번호로 사용하세요.
- IAM 사용자 계정의 경우 데이터베이스 사용자 이름은 계정의 전체 이메일 주소입니다.
- IAM 서비스 계정의 경우 데이터베이스 사용자 이름은 계정 이메일 주소에서 .gserviceaccount.com 서픽스를 제외한 값입니다.

다음 psql 명령어는 IAM 사용자로 명령줄에서 로그인하는 방법 중 하나를 보여줍니다. 이 명령어는 gcloud auth print-access-token의 출력을 PGPASSWORD 환경 변수에 설정하며, psql은 이를 데이터베이스 로그인 비밀번호로 사용합니다.

PGPASSWORD=$(gcloud auth print-access-token) psql \
  -h INSTANCE_ADDRESS \
  -U USERNAME \
  -d DATABASE

다음을 바꿉니다.

INSTANCE_ADDRESS: 연결할 AlloyDB 인스턴스의 IP 주소입니다.
USERNAME: 인스턴스 인증에 사용할 IAM 사용자의 식별자입니다.

IAM 사용자 계정의 경우 사용자 계정의 전체 이메일 주소를 제공합니다. 예를 들면 kai@altostrat.com입니다.

IAM 서비스 계정의 경우 .gserviceaccount.com 서픽스를 제외한 서비스 계정의 주소를 제공합니다. 예를 들어 서비스 계정을 my-service@my-project.iam.gserviceaccount.com로 지정하려면 여기에 my-service@my-project.iam 값을 사용합니다.
DATABASE: 연결할 데이터베이스의 이름입니다.

psql은 명령줄에서 입력된 비밀번호가 100자를 초과하면 잘라냅니다. psql에서 OAuth 2.0 토큰을 로그인 비밀번호로 사용하려면, 프롬프트에서 수동으로 붙여넣지 말고 이 예시에서처럼 PGPASSWORD 환경 변수를 설정해야 합니다.

자동으로 인증

OAuth 2.0 토큰 없이 IAM 기반 AlloyDB 사용자를 자동으로 인증하려면 AlloyDB 인증 프록시와 AlloyDB 언어 커넥터라는 두 가지 방법을 사용할 수 있습니다.

프록시 클라이언트 또는 언어 커넥터를 실행하는 데 사용하는 IAM 계정은 데이터베이스 사용자로 추가한 계정과 동일해야 합니다. 예를 들어 IAM 사용자 계정 kai@altostrat.com으로 워크로드를 실행하는 경우, OAuth 2.0 토큰을 지정하지 않고도 프록시 클라이언트 또는 언어 커넥터를 사용해 kai@altostrat.com 데이터베이스 사용자를 자동으로 인증할 수 있습니다. 이 예시에서는 kai@altostrat.com 이외의 다른 데이터베이스 사용자와는 자동 인증이 작동하지 않습니다.

인증 프록시

인증 프록시를 사용하려면 --auto-iam-authn 플래그가 사용 설정된 상태로 AlloyDB 인증 프록시 클라이언트를 실행해야 합니다.

인증 프록시 실행에 대한 자세한 내용은 AlloyDB 인증 프록시를 사용하여 연결을 참조하세요.

언어 커넥터

언어 커넥터를 사용하려면 IAM 인증을 프로그래매틱 방식으로 사용 설정해야 합니다. 언어별 옵션은 AlloyDB 언어 커넥터 구성에서 확인할 수 있습니다.

IAM 인증 문제 해결

IAM 기반 인증 실패의 원인을 파악하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.

로그 탐색기로 이동
리소스 유형에서 AlloyDB 인스턴스를 클릭합니다.
심각도에서 알림을 클릭합니다.

알림 옵션이 표시되지 않는 경우, 선택한 기간 내에 기록된 인증 실패가 없다는 의미입니다. 로그 탐색기의 컨트롤을 사용해 시간 범위를 조정해야 할 수도 있습니다.
쿼리 결과에서 다음 메시지 중 하나를 포함한 로그 항목을 확인합니다.
Request had invalid authentication credentials.

액세스 토큰이 잘못되었습니다.

Caller does not have required permission to use project.

IAM 주 구성원에 필요한 IAM 역할 또는 권한이 없습니다. 전체 오류 메시지에는 누락된 역할 또는 권한이 표시됩니다.

IAM principal does not match database user.
액세스 토큰으로 지정된 인증된 IAM 주 구성원이 연결하려는 데이터베이스 사용자와 일치하지 않습니다.

토큰에 지정된 주 구성원을 확인하려면 다음 명령어를 실행하세요.
```
curl -H "Content-Type: application/x-www-form-urlencoded" -d "access_token=ACCESS_TOKEN" https://www.googleapis.com/oauth2/v1/tokeninfo
```
ACCESS_TOKEN을 OAuth 2.0 액세스 토큰으로 바꿉니다.
Request had insufficient scopes.

액세스 토큰에 alloydb.login 범위 또는 cloud-platform 범위가 포함되어 있지 않습니다. 두 범위 중 하나가 필요합니다.

다음 단계

IAM 인증 관리