OAuth 인증 빠른 시작(Authentication with OAuth quickstart)

Gemini API에 인증하는 가장 쉬운 방법은 Gemini API 시작 가이드에 설명된 대로 API 키를 구성하는 거예요. 더 엄격한 접근 제어가 필요하다면 OAuth를 대신 사용할 수 있어요. 이 가이드는 OAuth로 인증을 설정하는 데 도움을 줘요.

이 가이드는 테스트 환경에 적합한 간소화된 인증 접근 방식을 사용해요. 프로덕션 환경에서는 앱에 적합한 액세스 자격 증명을 선택하기 전에 인증과 권한 부여에 대해 알아보세요.

출처: 원문

본문

목표(Objectives)

OAuth용 클라우드 프로젝트 설정
Application Default Credentials 설정
gcloud auth 대신 프로그램에서 자격 증명 관리

사전 요구 사항(Prerequisites)

이 빠른 시작을 실행하려면 다음이 필요해요:

클라우드 프로젝트 설정

이 빠른 시작을 완료하려면 먼저 Cloud 프로젝트를 설정해야 해요.

1. API 활성화

Google API를 사용하기 전에 Google Cloud 프로젝트에서 이를 켜야 해요.

Google Cloud 콘솔에서 Google Generative Language API를 활성화해요.

API 활성화

2. OAuth 동의 화면 구성

다음으로 프로젝트의 OAuth 동의 화면을 구성하고 자신을 테스트 사용자로 추가해요. 이미 Cloud 프로젝트에 대해 이 단계를 완료했다면 다음 섹션으로 건너뛰어요.

Google Cloud 콘솔에서 Menu > Google Auth platform > Overview로 가요. Google Auth 플랫폼으로 이동
프로젝트 구성 양식을 완료하고 Audience 섹션에서 사용자 유형을 External로 설정해요.
나머지 양식을 완료하고 User Data Policy 약관을 수락한 다음 Create를 클릭해요.
지금은 스코프 추가를 건너뛰고 Save and Continue를 클릭해도 돼요. 나중에 Google Workspace 조직 외부에서 사용할 앱을 만들 때는 앱에 필요한 권한 부여 스코프를 추가하고 검증해야 해요.
테스트 사용자를 추가해요:

Google Auth 플랫폼의 Audience 페이지로 이동해요. Test users 아래에서 Add users를 클릭해요. 자신의 이메일 주소와 기타 승인된 테스트 사용자를 입력한 다음 Save를 클릭해요.

3. 데스크톱 애플리케이션용 자격 증명 승인

최종 사용자로 인증하고 앱에서 사용자 데이터에 접근하려면 하나 이상의 OAuth 2.0 Client ID를 만들어야 해요. 클라이언트 ID는 Google의 OAuth 서버에 단일 앱을 식별하는 데 사용돼요. 앱이 여러 플랫폼에서 실행되면 각 플랫폼에 대해 별도의 클라이언트 ID를 만들어야 해요.

Google Cloud 콘솔에서 Menu > Google Auth platform > Clients로 가요. 자격 증명으로 이동
Create Client를 클릭해요.
Application type > Desktop app을 클릭해요.
Name 필드에 자격 증명 이름을 입력해요. 이 이름은 Google Cloud 콘솔에서만 표시돼요.
Create를 클릭해요. OAuth client created 화면에 새 Client ID와 Client secret이 표시돼요.
OK를 클릭해요. 새로 만든 자격 증명이 OAuth 2.0 Client IDs 아래에 나타나요.
다운로드 버튼을 클릭해 JSON 파일을 저장해요. client_secret_<identifier>.json으로 저장되며, 이를 client_secret.json으로 이름을 바꾸고 작업 디렉터리로 옮겨요.

Application Default Credentials 설정

client_secret.json 파일을 사용 가능한 자격 증명으로 변환하려면 그 위치를 gcloud auth application-default login 명령의 --client-id-file 인자로 전달해요.

gcloud auth application-default login \
    --client-id-file=client_secret.json \
    --scopes='https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/generative-language.retriever'

이 튜토리얼의 간소화된 프로젝트 설정은 "Google hasn't verified this app." 대화상자를 트리거해요. 정상적인 것이니 **"continue"**를 선택하세요.

그러면 결과 토큰이 잘 알려진 위치에 배치되어 gcloud 또는 클라이언트 라이브러리가 접근할 수 있어요.

참고: Colab에서 실행하는 경우 --no-browser를 포함하고 출력된 지침을 주의 깊게 따르세요(링크를 그냥 클릭하지 마세요). 또한 로컬 gcloud --version이 Colab과 일치하도록 최신 버전인지 확인하세요.

gcloud auth application-default login \
    --no-browser \
    --client-id-file=client_secret.json \
    --scopes='https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/generative-language.retriever'

Application Default Credentials(ADC)가 설정되면 대부분 언어의 클라이언트 라이브러리는 이를 찾는 데 최소한의 도움만 필요해요.

Curl

이것이 작동하는지 테스트하는 가장 빠른 방법은 curl을 사용해 REST API에 접근하는 거예요:

access_token=$(gcloud auth application-default print-access-token)
project_id=<MY PROJECT ID>
curl -X GET https://generativelanguage.googleapis.com/v1/models \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $access_token" \
    -H "x-goog-user-project: ${project_id}" | grep '"name"'

Python

Python에서는 클라이언트 라이브러리가 자동으로 찾아야 해요:

pip install google-genai

테스트할 수 있는 최소 스크립트는 다음과 같아요:

from google import genai

client = genai.Client()
print('Available base models:', [m.name for m in client.models.list()])

자격 증명 직접 관리하기 [Python]

많은 경우 Client ID(client_secret.json)로 액세스 토큰을 만들기 위해 gcloud 명령을 사용할 수 없을 거예요. Google은 앱 내에서 그 과정을 관리할 수 있게 많은 언어의 라이브러리를 제공해요. 이 섹션은 Python에서 그 과정을 보여줘요. 다른 언어의 동등한 예시는 Drive API 문서에서 확인할 수 있어요.

1. 필요한 라이브러리 설치

Python용 Google 클라이언트 라이브러리와 Gemini 클라이언트 라이브러리를 설치해요.

pip install --upgrade -q google-api-python-client google-auth-httplib2 google-auth-oauthlib
pip install google-genai

2. 자격 증명 관리자 작성

권한 부여 화면을 클릭해야 하는 횟수를 최소화하려면 작업 디렉터리에 load_creds.py 파일을 만들어 나중에 재사용하거나 만료되면 새로고침할 수 있는 token.json 파일을 캐싱해요.

client_secret.json 파일을 genai.configure와 함께 사용 가능한 토큰으로 변환하는 다음 코드로 시작하세요:

import os.path

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ['https://www.googleapis.com/auth/generative-language.retriever']

def load_creds():
    """Converts `client_secret.json` to a credential object.

    This function caches the generated tokens to minimize the use of the
    consent screen.
    """
    creds = None
    # The file token.json stores the user's access and refresh tokens, and is
    # created automatically when the authorization flow completes for the first
    # time.
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)
    # If there are no (valid) credentials available, let the user log in.
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(
                'client_secret.json', SCOPES)
            creds = flow.run_local_server(port=0)
        # Save the credentials for the next run
        with open('token.json', 'w') as token:
            token.write(creds.to_json())
    return creds

3. 프로그램 작성

이제 script.py를 만들어요:

import pprint
from google import genai
from load_creds import load_creds

creds = load_creds()

client = genai.Client(credentials=creds)

print()
print('Available base models:', [m.name for m in client.models.list()])

4. 프로그램 실행

작업 디렉터리에서 샘플을 실행해요:

python script.py

처음 스크립트를 실행하면 브라우저 창이 열리고 접근을 승인하라는 메시지가 표시돼요.

아직 Google 계정에 로그인하지 않았다면 로그인하라는 메시지가 표시돼요. 여러 계정에 로그인되어 있다면 프로젝트를 구성할 때 "Test Account"로 설정한 계정을 선택해야 해요. 참고: 이 튜토리얼의 간소화된 프로젝트 설정은 "Google hasn't verified this app." 대화상자를 트리거해요. 정상적인 것이니 **"continue"**를 선택하세요.
권한 부여 정보는 파일 시스템에 저장되므로 다음에 샘플 코드를 실행할 때 권한 부여를 요청받지 않아요.

인증 설정을 성공적으로 완료했어요.

OAuth 인증 빠른 시작(Authentication with OAuth quickstart)