# Integrasikan dengan Google Drive menggunakan OAuth2
<a name="identity-getting-started-google"></a>

Tutorial memulai ini memandu Anda melalui langkah-langkah penting untuk mulai menggunakan Amazon Bedrock AgentCore Identity untuk agen AI Anda. Anda akan mempelajari cara mengatur lingkungan pengembangan, menginstal SDK yang diperlukan, membuat identitas agen pertama Anda, dan mengizinkan agen Anda mengakses sumber daya eksternal dengan aman.

Pada akhir tutorial ini, Anda akan memiliki agen kerja yang dapat mengambil token akses dari Google dengan AgentCore Identity OAuth2 Credential Provider, dan membaca file dari Google Drive menggunakan token akses. Untuk informasi mendetail tentang alur OAuth2, lihat [Mengelola penyedia kredensi](identity-outbound-credential-provider.md) dengan Identitas. AgentCore 

**Topics**
+ [Prasyarat](#identity-getting-started-prerequisites)
+ [Langkah 1: Siapkan Penyedia Kredenal OAuth 2.0](#identity-getting-started-step1)
+ [Langkah 2: Impor modul Identitas dan Auth](#identity-getting-started-step2)
+ [Langkah 3: Dapatkan token akses OAuth 2.0](#identity-getting-started-step3)
+ [Langkah 4: Gunakan Token Akses OAuth2 untuk Memanggil Sumber Daya Eksternal](#identity-getting-started-step4)
+ [Apa selanjutnya?](#identity-getting-started-whats-next)

## Prasyarat
<a name="identity-getting-started-prerequisites"></a>

Sebelum Anda mulai, Anda perlu:
+  AWS Akun dengan izin yang sesuai (misalnya,`BedrockAgentCoreFullAccess`)
+ Python 3.10 atau lebih tinggi
+  AWS CLI terbaru dan diinstal `jq`
+  AWS kredensil dan wilayah dikonfigurasi () `aws configure`
+ Pemahaman dasar tentang pemrograman Python

**penting**  
Kebijakan `BedrockAgentCoreFullAccess` terkelola memberikan izin luas termasuk`GetWorkloadAccessTokenForUserId`, yang memungkinkan penelepon mengeluarkan token akses beban kerja menggunakan string pengenal pengguna apa pun tanpa verifikasi token IDP. Ini cocok untuk pengembangan dan pengujian. Untuk penerapan produksi, buat kebijakan IAM khusus yang mengikuti prinsip hak istimewa paling sedikit dan batasi izin hanya untuk tindakan spesifik yang diperlukan. Jika aplikasi Anda menggunakan JWT-based otentikasi (direkomendasikan untuk produksi), Anda dapat secara eksplisit menolak `GetWorkloadAccessTokenForUserId` untuk memastikan semua identifikasi pengguna melewati jalur JWT yang diverifikasi. Untuk informasi selengkapnya, lihat [Mendapatkan token akses beban kerja](get-workload-access-token.md).

### Instal SDK
<a name="identity-getting-started-install-sdk"></a>

Untuk memulai, instal `bedrock-agentcore` paket:

```
pip install bedrock-agentcore
```

### Dapatkan ID Klien Google dan Rahasia Klien
<a name="identity-getting-started-google-credentials"></a>

Untuk memungkinkan agen Anda mengakses Google Drive, Anda perlu mendapatkan ID klien Google dan rahasia klien untuk agen Anda. Buka [Google Developer Console](https://console.developers.google.com/project) dan ikuti langkah-langkah berikut:

1. Membuat Project di Google Developer Console

1. Aktifkan Google Drive API

1. Konfigurasikan layar persetujuan OAuth

1. Buat aplikasi web baru untuk agen, misalnya, “Agen Saya 1"

1. Tambahkan cakupan OAuth 2.0 berikut ke aplikasi agen Anda: `https://www.googleapis.com/auth/drive.metadata.readonly` 

1. Buat Kredensial OAuth 2.0 untuk aplikasi web baru, dan simpan ID klien Google dan rahasia klien yang dihasilkan

## Langkah 1: Siapkan Penyedia Kredenal OAuth 2.0
<a name="identity-getting-started-step1"></a>

Buat Penyedia Kredenal OAuth 2.0 baru dengan ID klien Google dan rahasia klien yang diperoleh sebelumnya menggunakan perintah CLI AWS berikut:

```
OAUTH2_CREDENTIAL_PROVIDER_RESPONSE=$(aws bedrock-agentcore-control create-oauth2-credential-provider \
  --region us-east-1 \
  --name "google-provider" \
  --credential-provider-vendor "GoogleOauth2" \
  --oauth2-provider-config-input '{
      "googleOauth2ProviderConfig": {
        "clientId": "<your-google-client-id>",
        "clientSecret": "<your-google-client-secret>"
      }
    }' \
--output json)

OAUTH2_CALLBACK_URL=$(echo $OAUTH2_CREDENTIAL_PROVIDER_RESPONSE | jq -r '.callbackUrl')

echo "OAuth2 Callback URL: $OAUTH2_CALLBACK_URL"
```

**catatan**  
Dapatkan `callbackUrl` dari [CreateOauth2CredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateOauth2CredentialProvider.html)respons di atas dan tambahkan URI ke daftar URI pengalihan aplikasi Google Anda. URL panggilan balik akan terlihat seperti: https://bedrock-agentcore.us-east-1.amazonaws.com/identities/oauth2/callback/ \*\*\*\*\*\*\*\*\*\*-\*\*\*\*-\*\*\*\*\*\*-\*\*\*\*\*\*\*\*\*\*\*\*\*\*

## Langkah 2: Impor modul Identitas dan Auth
<a name="identity-getting-started-step2"></a>

Tambahkan pernyataan impor ini ke file Python Anda:

```
from bedrock_agentcore.services.identity import IdentityClient
from bedrock_agentcore.identity.auth import requires_access_token, requires_api_key
```

## Langkah 3: Dapatkan token akses OAuth 2.0
<a name="identity-getting-started-step3"></a>

Setelah Anda membuat Google Credential Provider pada langkah sebelumnya, tambahkan `@requires_access_token` dekorator ke kode agen Anda yang memerlukan token akses Google. Salin URL otorisasi dari output konsol Anda, lalu tempel di browser Anda dan lengkapi alur persetujuan dengan Google Drive.

Contoh kode berikut dimaksudkan untuk diintegrasikan ke dalam kode agen Anda untuk menjalankan alur kerja otorisasi. Ini bukan kode mandiri yang dapat disalin dan dijalankan secara independen.

```
import asyncio

# Injects Google Access Token
@requires_access_token(
    # Uses the same credential provider name created above
    provider_name="google-provider",
    # Requires Google OAuth2 scope to access Google Drive
    scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"],
    # Sets to OAuth 2.0 Authorization Code flow
    auth_flow="USER_FEDERATION",
    # Prints authorization URL to console
    on_auth_url=lambda x: print("\nPlease copy and paste this URL in your browser:\n" + x),
    # If false, caches obtained access token
    force_authentication=False,
    # The callback URL to redirect to after the OAuth 2.0 token retrieval is complete
    callback_url='oauth2_callback_url_for_session_binding',
)
async def write_to_google_drive(*, access_token: str):
    # Prints the access token obtained from Google
    print(access_token)

asyncio.run(write_to_google_drive(access_token=""))
```

Di belakang layar, `@requires_access_token` dekorator berjalan melalui urutan berikut:

![Diagram alir yang menunjukkan urutan panggilan API yang dilakukan oleh dekorator @requires_access_token](http://docs.aws.amazon.com/id_id/bedrock-agentcore/latest/devguide/images/identity_access_token_flow.png)


1. SDK membuat panggilan API ke`CreateWorkloadIdentity`,`GetWorkloadAccessToken`, dan`GetResourceOauth2Token`.

1. Saat menjalankan kode agen secara lokal, SDK secara otomatis menghasilkan ID identitas agen dan ID pengguna acak untuk pengujian lokal, dan menyimpannya dalam file lokal yang disebut. `.bedrock_agentcore.yaml`

1. Saat menjalankan kode agen dengan AgentCore Runtime, SDK tidak menghasilkan ID identitas agen atau ID pengguna acak. Sebagai gantinya, ia menggunakan ID identitas agen yang ditetapkan, dan ID pengguna atau token JWT diteruskan oleh pemanggil agen.

1. Token akses agen adalah token terenkripsi (buram) yang berisi ID identitas agen dan ID pengguna.

1. AgentCore Layanan identitas menyimpan token akses Google di Token Vault di bawah ID identitas agen dan ID pengguna. Ini menciptakan ikatan antara identitas agen, identitas pengguna, dan token akses Google.

1. [Alur pengikatan sesi](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.html) harus diselesaikan sebelum token akses Google dikembalikan ke pemanggil oleh AgentCore Identity.

## Langkah 4: Gunakan Token Akses OAuth2 untuk Memanggil Sumber Daya Eksternal
<a name="identity-getting-started-step4"></a>

Setelah agen memperoleh token akses Google dengan langkah-langkah di atas, agen dapat menggunakan token akses untuk mengakses Google Drive. Berikut adalah contoh lengkap yang mencantumkan nama dan ID dari 10 file pertama yang dapat diakses pengguna.

Pertama, instal pustaka klien Google untuk Python:

```
pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib
```

Kemudian, salin kode berikut:

```
import asyncio
from bedrock_agentcore.identity.auth import requires_access_token, requires_api_key
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

SCOPES = ["https://www.googleapis.com/auth/drive.metadata.readonly"]

def main(access_token):
    """Shows basic usage of the Drive v3 API.

    Prints the names and ids of the first 10 files the user has access to.
    """
    creds = Credentials(token=access_token, scopes=SCOPES)

    try:
        service = build("drive", "v3", credentials=creds)

        # Call the Drive v3 API
        results = (
            service.files()
            .list(pageSize=10, fields="nextPageToken, files(id, name)")
            .execute()
        )
        items = results.get("files", [])

        if not items:
            print("No files found.")
            return

        print("Files:")
        for item in items:
            print(f"{item['name']} ({item['id']})")

    except HttpError as error:
        # TODO(developer) - Handle errors from drive API.
        print(f"An error occurred: {error}")

if __name__ == "__main__":
    # This annotation helps agent developer to obtain access tokens from external applications
    @requires_access_token(
        provider_name="google-provider",
        # Google OAuth2 scopes
        scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"],
        # 3LO flow
        auth_flow="USER_FEDERATION",
        # prints authorization URL to console
        on_auth_url=lambda x: print("Copy and paste this authorization url to your browser", x),
        force_authentication=True,
        callback_url='oauth2_callback_url_for_session_binding',
    )
    async def read_from_google_drive(*, access_token: str):
        print(access_token)  # You can see the access_token
        # Make API calls...
        main(access_token)

    asyncio.run(read_from_google_drive(access_token=""))
```

**catatan**  
Untuk contoh implementasi server callback lokal untuk menangani [pengikatan sesi](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.html), lihat [https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/03-AgentCore-identity/05-Outbound_Auth_3lo/oauth2_callback_server.py](https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/03-AgentCore-identity/05-Outbound_Auth_3lo/oauth2_callback_server.py) 

## Apa selanjutnya?
<a name="identity-getting-started-whats-next"></a>

Contoh di bagian ini berfokus pada pola implementasi praktis yang dapat Anda sesuaikan untuk kasus penggunaan spesifik Anda. Anda dapat menyematkan kode sebagai bagian dari agen, atau alat Model Context Protocol (MCP). Jika Anda ingin meng-host kode Agen atau Alat MCP Anda dengan AgentCore Runtime, ikuti [agen Host atau alat dengan Amazon Bedrock AgentCore Runtime untuk menyalin kode di atas ke Runtime](agents-tools-runtime.md). AgentCore