Menyesuaikan Token dan Kode Otorisasi

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Tentang metadata token dan kode otorisasi

Apigee menghasilkan token akses OAuth, token refresh, dan kode otorisasi, serta mendistribusikannya ke aplikasi yang diautentikasi. Pada waktu pembuatan, Apigee menyimpan token dan kode tersebut. Kemudian, saat Apigee menerima permintaan API masuk yang berisi token atau kode ini, Apigee akan menggunakan informasi yang disimpan untuk memberikan otorisasi pada permintaan.

Saat membuat artefak OAuth ini, Apigee juga akan melampirkan metadata ke token atau kode. Misalnya, token akses dikaitkan dengan pasangan nama/nilai yang menentukan waktu habis masa berlaku, aplikasi dan developer terkait, serta informasi lainnya.

Representasi JSON token akses Apigee terlihat seperti berikut:

{
  "issued_at" : "1372170159093",
  "application_name" : "ccd1803b-b557-4520-bd62-ddd3abf8e501",
  "scope" : "READ",
  "status" : "approved",
  "api_product_list" : "[Product1,Product2]",
  "api_product_list_json" : ["Product1", "Product2"],
  "expires_in" : "3599", //--in seconds
  "developer.email" : "joe@weathersample.com",
  "organization_id" : "0",
  "refresh_token" : "82XMXgDyHTpFyXOaApj8C2AGIPnN2IZe",
  "client_id" : "deAVedE0W9Z9U35PAMaAJYphBJCGdrND",
  "access_token" : "shTUmeI1geSKin0TODcGLXBNe9vp",
  "organization_name" : "apifactory",
  "refresh_count" : "0"
}

Menambahkan atribut kustom ke token OAuth dan kode otorisasi

Terkadang, ada baiknya Anda melampirkan metadata kustom ke token akses. Misalnya, Anda mungkin ingin menambahkan nama pengguna, keanggotaan grup, atau peran untuk pengguna, ID pelanggan, ID sesi, atau informasi arbitrer lainnya ke token. Di Apigee, data ini disebut "atribut kustom". Selanjutnya, saat token diverifikasi dalam cakupan permintaan API, data tersebut akan tersedia untuk proxy API melalui variabel konteks. Proxy API dapat membuat keputusan otorisasi atau pemilihan rute yang terperinci berdasarkan data kustom yang dilampirkan ke token.

Untuk melampirkan data arbitrer ke token, gunakan elemen <Attributes> di kebijakan OAuthV2. Anda dapat menentukan nama dan nilai atribut kustom. Misalnya, berikut adalah konfigurasi kebijakan yang menghasilkan token dan melampirkan atribut kustom bernama "tenant_list" ke token:

<OAuthV2 name="GenerateAccessToken">
  <Operation>GenerateAccessToken</Operation>
  <ExpiresIn>600000</ExpiresIn>
  <GenerateResponse />
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <Attributes> 
    <Attribute name="tenant_list" ref="tenant_list_retrieved_from_external_service" display="false"/>
  </Attributes>
</OAuthV2>

Anda dapat menentukan beberapa atribut kustom, dan Anda dapat melampirkan atribut tersebut secara implisit ke kode otorisasi (<Operation>GenerateAuthorizationCode</Operation>) atau token (<Operation>GenerateAccessToken</Operation>) pada saat pembuatan.

Jika display ditetapkan ke true (default), atribut kustom akan ditampilkan dalam respons, tempat atribut tersebut dapat dilihat oleh aplikasi, atau diteruskan ke pengguna akhir. Jika display ditetapkan ke false, atribut kustom akan disimpan di penyimpanan data, tetapi tidak ditampilkan dalam pesan respons. Dalam kedua kasus tersebut, data kustom tersedia untuk kebijakan dalam Proxy API, setelah token diverifikasi.

Untuk informasi selengkapnya tentang opsi display, lihat Menampilkan atau menyembunyikan atribut kustom dalam respons.

Mendapatkan atribut token akses kustom saat runtime

Saat ada panggilan ke OAuthV2/VerifyAccessToken, Apigee akan memverifikasi token dengan mencarinya di token store. Apigee kemudian mengisi kumpulan variabel konteks yang berisi informasi tentang token. Fitur tersebut meliputi:

  • organization_name
  • developer.id
  • developer.app.name
  • client_id
  • grant_type
  • token_type
  • access_token
  • issued_at
  • expires_in //--dalam detik
  • status
  • scope
  • apiproduct.name*

Jika ada atribut kustom pada token, atribut kustom tersebut akan tersedia di variabel konteks dengan nama accesstoken.{custom_attribute}. Misalnya, token dikeluarkan dari kebijakan yang ditampilkan di atas. Setelah memverifikasi token tersebut, akan ada variabel konteks tambahan bernama accesstoken.tenant_list, yang berisi nilai yang disimpan pada saat token dibuat.

Kebijakan atau kondisi kemudian dapat merujuk ke variabel ini dan mengubah perilaku berdasarkan nilai yang disimpan di dalamnya.

Menetapkan dan memperbarui atribut kustom saat runtime

Dalam beberapa situasi, Anda ingin Proxy API memperbarui metadata yang terkait dengan token akses saat runtime saat panggilan API sedang diproses di Apigee. Untuk membantu hal ini, Apigee menyediakan kebijakan untuk mendapatkan dan menetapkan atribut token. Untuk informasi selengkapnya, lihat Mendapatkan kebijakan Info OAuth V2 dan Menetapkan kebijakan Info OAuth V2.

Dalam setiap kebijakan ini, elemen AccessToken harus merujuk ke variabel yang berisi token akses.