Mendapatkan token OAuth 2.0

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Dokumen ini menunjukkan cara mendapatkan token akses OAuth 2.0 dan kode otorisasi dengan Apigee API. Kami juga menunjukkan cara membuat kebijakan untuk setiap jenis pemberian OAuth 2.0 dan mengonfigurasi endpoint proxy untuk menerima permintaan klien.

Catatan: Contoh ini menunjukkan konfigurasi paling dasar yang mungkin dilakukan. Kebijakan OAuthV2 mencakup banyak elemen opsional yang dapat dikonfigurasi dan tidak ditampilkan dalam topik ini. Untuk mengetahui informasi selengkapnya tentang elemen tersebut, lihat kebijakan OAuthV2.

Menggunakan jenis pemberian kode otorisasi

Bagian ini menjelaskan cara mendapatkan token akses menggunakan alur jenis pemberian kode otorisasi. Permintaan token untuk alur ini memerlukan kode otorisasi. Lihat Mendapatkan kode otorisasi. Lihat juga Apa yang dimaksud dengan jenis pemberian OAuth 2.0.

Catatan: Konfigurasi kebijakan OAuthV2 di bagian ini menggunakan GenerateAccessToken operasi. Operasi ini menghasilkan format token string buram. Anda juga dapat membuat token berformat JWT dengan mengganti operasi GenerateJWTAccessToken. Lihat juga Menggunakan operasi token OAuth JWT.

Contoh permintaan

curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
   -X POST 'https://apitest.acme.com/oauth/token' \
   -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com' 

Parameter wajib

Secara default, parameter ini harus berupa x-www-form-urlencoded dan ditentukan dalam isi permintaan (seperti yang ditunjukkan dalam contoh di atas); namun, default ini dapat diubah dengan mengonfigurasi elemen <GrantType>, <Code>, dan <RedirectUri> dalam kebijakan OAuthV2. Lihat kebijakan OAuthV2.

• grant_type - Harus ditetapkan ke nilai authorization_code.
• code - Kode otorisasi. Lihat Meminta kode otorisasi.
• redirect_uri - Anda harus memberikan parameter ini jika parameter redirect_uri disertakan dalam permintaan kode otorisasi. Jika parameter redirect_uri tidak disertakan dalam permintaan kode otorisasi, dan jika Anda tidak memberikan parameter ini, kebijakan ini akan menggunakan nilai URL Panggilan Balik yang diberikan di aplikasi developer terdaftar.

Parameter opsional

• status - String yang akan dikirim kembali dengan respons. Biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs.
• scope - Memungkinkan Anda memfilter daftar produk API yang dapat menggunakan token yang dicetak. Untuk mengetahui informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.

Otorisasi

Anda harus meneruskan ID Klien dan Rahasia Klien sebagai header Otorisasi Dasar (berenkode Base64) atau sebagai parameter formulir client_id dan client_secret. Anda mendapatkan nilai ini dari aplikasi developer terdaftar. Lihat juga Mengenkode kredensial autentikasi dasar.

Endpoint contoh

Berikut adalah contoh konfigurasi endpoint untuk membuat token akses. Kebijakan ini akan menjalankan kebijakan GenerateAccessToken, yang harus dikonfigurasi untuk mendukung jenis pemberian authorization_code.

...
       <Flow name="generate-access-token">
            <Description>Generate a token</Description>
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Contoh kebijakan

Ini adalah kebijakan GenerateAccessToken dasar yang dikonfigurasi untuk menerima jenis pemberian authorization_code. Untuk mengetahui informasi tentang elemen konfigurasi opsional yang dapat Anda konfigurasi dengan kebijakan ini, lihat kebijakan OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn>
    <RefreshTokenExpiresIn>86400000</RefreshTokenExpiresIn>
    <SupportedGrantTypes>
      <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Menampilkan

Dengan <GenerateResponse> diaktifkan, kebijakan akan menampilkan respons JSON yang mencakup token akses, seperti yang ditunjukkan di bawah. Jenis pemberian authorization_code membuat token akses dan token refresh, sehingga responsnya mungkin terlihat seperti ini:

{
    "issued_at": "1420262924658",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420262924658",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "[e-mail]",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "fYACGW7OCPtCNDEnRSnqFlEgogboFPMm",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "2l4IQtZXbn5WBJdL6EF7uenOWRsi",
    "organization_name": "docs",
    "refresh_token_expires_in": "86399", //--in seconds
    "refresh_count": "0"
}

Catatan: Ya, memang agak tidak biasa untuk menentukan nilai masa berlaku dalam milidetik dalam kebijakan, tetapi menerimanya dalam detik di payload respons. Kami menyadarinya.

Jika <GenerateResponse> disetel ke false, kebijakan tidak akan menampilkan respons. Sebagai gantinya, variabel ini akan diisi dengan kumpulan variabel alur berikut yang berisi data terkait pemberian token akses.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Contoh:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Menggunakan jenis pemberian kredensial klien

Bagian ini menjelaskan cara mendapatkan token akses menggunakan alur jenis pemberian kredensial klien. Lihat juga Apa yang dimaksud dengan jenis pemberian OAuth 2.0.

Catatan: Konfigurasi kebijakan OAuthV2 di bagian ini menggunakan GenerateAccessToken operasi. Operasi ini menghasilkan format token string buram. Anda juga dapat membuat token berformat JWT dengan mengganti operasi GenerateJWTAccessToken. Lihat juga Menggunakan operasi token OAuth JWT.

Contoh permintaan

curl -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \
  -X POST "https://apitest.acme.com/oauth/token" \
  -d "grant_type=client_credentials"

Parameter wajib

• grant_type - Harus ditetapkan ke nilai client_credentials.

  Secara default, parameter grant_type yang diperlukan harus berupa x-www-form-urlencoded dan ditentukan dalam isi permintaan (seperti yang ditunjukkan dalam contoh di atas); namun, Anda dapat mengubah nilai default ini dengan mengonfigurasi elemen <GrantType> dalam kebijakan OAuthV2. Misalnya, Anda dapat memilih untuk meneruskan parameter dalam parameter kueri. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.

Parameter opsional

• status - String yang akan dikirim kembali dengan respons. Biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs.
• scope - Memungkinkan Anda memfilter daftar produk API yang dapat menggunakan token yang dicetak. Untuk mengetahui informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.

Otorisasi

Anda harus meneruskan ID Klien dan Rahasia Klien sebagai header Otorisasi Dasar (berenkode Base64) atau sebagai parameter formulir client_id dan client_secret. Anda mendapatkan nilai ini dari aplikasi developer terdaftar yang terkait dengan permintaan. Lihat juga Mengenkode kredensial autentikasi dasar.

Endpoint contoh

Berikut adalah contoh konfigurasi endpoint untuk membuat token akses. Kebijakan ini akan menjalankan kebijakan GenerateAccessToken, yang harus dikonfigurasi untuk mendukung jenis pemberian client_credentials.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Contoh kebijakan

Ini adalah kebijakan GenerateAccessToken dasar yang dikonfigurasi untuk menerima jenis pemberian client_credentials. Untuk mengetahui informasi tentang elemen konfigurasi opsional yang dapat Anda konfigurasi dengan kebijakan ini, lihat kebijakan OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Menampilkan

Dengan <GenerateResponse> diaktifkan, kebijakan akan menampilkan respons JSON. Perhatikan bahwa dengan jenis pemberian client_credentials, token refresh tidak didukung. Hanya token akses yang dibuat. Contoh:

{
    "issued_at": "1420260525643",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "[e-mail]",
    "organization_id": "0",
    "token_type": "BearerToken",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "XkhU2DFnMGIVL2hvsRHLM00hRWav",
    "organization_name": "docs"
}

Jika <GenerateResponse> disetel ke false, kebijakan tidak akan menampilkan respons. Sebagai gantinya, variabel ini akan diisi dengan kumpulan variabel alur berikut yang berisi data terkait pemberian token akses.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds

Contoh:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in     //--in seconds

Menggunakan jenis pemberian akses sandi

Bagian ini menjelaskan cara mendapatkan token akses menggunakan alur jenis pemberian kredensial (sandi) sandi pemilik resource. Lihat juga Menerapkan jenis pemberian sandi. Lihat juga Apa yang dimaksud dengan jenis pemberian OAuth 2.0.

Catatan: Konfigurasi kebijakan OAuthV2 di bagian ini menggunakan GenerateAccessToken operasi. Operasi ini menghasilkan format token string buram. Anda juga dapat membuat token berformat JWT dengan mengganti operasi GenerateJWTAccessToken. Lihat juga Menggunakan operasi token OAuth JWT.

Contoh permintaan

curl -v -k -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \
  -X POST "https://apitest.acme.com/oauth/token" \
  -d "grant_type=password&username=a_username&password=a_password"

Parameter wajib

Secara default, parameter ini harus berupa x-www-form-urlencoded dan ditentukan dalam isi permintaan (seperti yang ditunjukkan dalam contoh di atas); namun, default ini dapat diubah dengan mengonfigurasi elemen <GrantType>, <Username>, dan <Password> dalam kebijakan OAuthV2. Lihat kebijakan OAuthV2.

Kredensial pengguna biasanya divalidasi terhadap penyimpanan kredensial menggunakan kebijakan LDAP atau JavaScript.

• grant_type - Harus ditetapkan ke nilai password.
• username - Nama pengguna pemilik resource.
• password - Sandi pemilik resource.

Parameter opsional

• status - String yang akan dikirim kembali dengan respons. Biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs.
• scope - Memungkinkan Anda memfilter daftar produk API yang dapat menggunakan token yang dicetak. Untuk mengetahui informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.

Otorisasi

Anda harus meneruskan ID Klien dan Rahasia Klien sebagai header Otorisasi Dasar (berenkode Base64) atau sebagai parameter formulir client_id dan client_secret. Anda mendapatkan nilai ini dari aplikasi developer terdaftar yang terkait dengan permintaan. Lihat juga Mengenkode kredensial autentikasi dasar.

Endpoint contoh

Berikut adalah contoh konfigurasi endpoint untuk membuat token akses. Kebijakan GenerateAccessToken akan dijalankan, yang harus dikonfigurasi untuk mendukung jenis pemberian sandi.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Contoh kebijakan

Ini adalah kebijakan GenerateAccessToken dasar yang dikonfigurasi untuk menerima jenis pemberian sandi. Untuk mengetahui informasi tentang elemen konfigurasi opsional yang dapat Anda konfigurasi dengan kebijakan ini, lihat kebijakan OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
    <SupportedGrantTypes>
      <GrantType>password</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Menampilkan

Dengan <GenerateResponse> diaktifkan, kebijakan akan menampilkan respons JSON. Perhatikan bahwa dengan jenis pemberian sandi, token akses dan token refresh akan dibuat. Misalnya:

{
    "issued_at": "1420258685042",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420258685042",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "[e-mail]",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "IFl7jlijYuexu6XVSSjLMJq8SVXGOAAq",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "I6daIgMSiUgYX1K2qgQWPi37ztS6",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "0"
}

Jika <GenerateResponse> disetel ke false, kebijakan tidak akan menampilkan respons. Sebagai gantinya, variabel ini akan diisi dengan kumpulan variabel alur berikut yang berisi data terkait pemberian token akses.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Contoh:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Menggunakan jenis pemberian implisit

Bagian ini menjelaskan cara mendapatkan token akses menggunakan alur jenis pemberian implisit. Lihat juga Apa yang dimaksud dengan jenis pemberian OAuth 2.0.

Catatan: Konfigurasi kebijakan OAuthV2 di bagian ini menggunakan GenerateAccessTokenImplicitGrant operasi. Operasi ini menghasilkan format token string buram. Anda juga dapat membuat token berformat JWT dengan mengganti operasi GenerateJWTAccessTokenImplicitGrant. Lihat juga Menggunakan operasi token OAuth JWT.

Contoh permintaan

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'https://apitest.acme.com/oauth/implicit?response_type=token&client_id=c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ&redirect_uri=http://callback-example.com'

Parameter wajib

Secara default, parameter ini harus berupa parameter kueri (seperti yang ditunjukkan dalam contoh di atas); namun, default ini dapat diubah dengan mengonfigurasi elemen <ResponseType>, <ClientId>, dan <RedirectUri> dalam kebijakan OAuthV2 yang dilampirkan ke endpoint /token ini. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.

Kredensial pengguna biasanya divalidasi terhadap penyimpanan kredensial menggunakan panggilan layanan LDAP atau kebijakan JavaScript.

• response_type - Harus disetel ke nilai token.
• client_id - ID klien aplikasi developer terdaftar.
• redirect_uri - Parameter ini wajib diisi jika URI Callback tidak diberikan saat aplikasi developer klien didaftarkan. Jika URL Panggilan Balik diberikan saat pendaftaran klien, URL tersebut akan dibandingkan dengan nilai ini dan harus sama persis.

Parameter opsional

• status - String yang akan dikirim kembali dengan respons. Biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs.
• scope - Memungkinkan Anda memfilter daftar produk API yang dapat menggunakan token yang dicetak. Untuk mengetahui informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.

Otorisasi

Tidak memerlukan header Otorisasi; namun, Anda harus meneruskan client ID sebagai parameter permintaan.

Endpoint contoh

Berikut adalah contoh konfigurasi endpoint untuk membuat token akses. Kebijakan GenerateAccessTokenImplicitGrant akan dijalankan.

...
       <Flow name="generate-access-token-implicit">
            <Request>
                <Step>
                    <Name>GenerateAccessTokenImplicitGrant</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/implicit") and (request.verb = "POST")</Condition>
        </Flow>
...

Contoh kebijakan

Ini adalah kebijakan GenerateAccessTokenImplicitGrant dasar yang memproses permintaan token untuk alur jenis pemberian implisit. Untuk mengetahui informasi tentang elemen konfigurasi opsional yang dapat Anda konfigurasi dengan kebijakan ini, lihat kebijakan OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="GenerateAccessTokenImplicit">
    <DisplayName>GenerateAccessTokenImplicit</DisplayName>
    <Operation>GenerateAccessTokenImplicitGrant</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Menampilkan

Jika <GenerateResponse> diaktifkan, kebijakan akan menampilkan pengalihan Lokasi 302 di header respons. Pengalihan mengarah ke URL yang ditentukan dalam parameter redirect_uri dan ditambahkan dengan token akses dan waktu habis masa berlaku token. Perhatikan bahwa jenis pemberian izin implisit tidak mendukung token refresh. Contoh:

https://callback-example.com#expires_in=1799&access_token=In4dKm4ueoGZRbIYJhC9yZCmTFw5

Jika <GenerateResponse> disetel ke false, kebijakan tidak akan menampilkan respons. Sebagai gantinya, variabel ini akan diisi dengan kumpulan variabel alur berikut yang berisi data terkait pemberian token akses.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in  //--in seconds

Contoh:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in   //--in seconds

Mendapatkan kode otorisasi

Dalam alur jenis pemberian kode otorisasi, kode otorisasi diperlukan untuk mendapatkan token akses. Lihat Menggunakan jenis pemberian kode otorisasi. Lihat juga Apa yang dimaksud dengan jenis pemberian OAuth 2.0.

Catatan: Alur kode otorisasi terjadi antara layanan autentikasi pengguna pihak ketiga dan Apigee. Tujuan alur jenis pemberian kode otorisasi adalah agar aplikasi klien tidak pernah melihat kredensial pengguna untuk server resource. Untuk melihat alur ini secara mendetail, lihat Menerapkan jenis pemberian kode otorisasi.

Contoh permintaan

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  "https://apitest.acme.com/oauth/authorize?response_type=code&client_id=c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ&redirect_uri=http://my-callback.com"

Parameter wajib

Secara default, parameter ini harus berupa parameter kueri (seperti yang ditunjukkan dalam contoh di atas); namun, Anda dapat mengubah default ini dengan mengonfigurasi elemen <ResponseType>, <ClientId>, dan <RedirectUri> dalam kebijakan OAuthV2. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.

• redirect_uri - Jika URI Panggilan Balik lengkap (bukan sebagian) ditentukan di aplikasi klien terdaftar, parameter ini bersifat opsional; jika tidak, parameter ini wajib diisi. Callback adalah URL tempat Apigee mengirim kode otorisasi yang baru dibuat. Lihat juga Mendaftarkan aplikasi dan mengelola kunci API.
• response_type - Harus disetel ke nilai code.
• client_id - ID klien aplikasi developer terdaftar.

Parameter opsional

• redirect_uri - Jika URI Panggilan Balik lengkap (bukan sebagian) ditentukan di aplikasi klien terdaftar, parameter ini bersifat opsional; jika tidak, parameter ini wajib diisi. Callback adalah URL tempat Apigee mengirim kode otorisasi yang baru dibuat. Lihat juga Mendaftarkan aplikasi dan mengelola kunci API.
• status - String yang akan dikirim kembali dengan respons. Biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs.
• scope - Memungkinkan Anda memfilter daftar produk API yang dapat menggunakan token yang dicetak. Untuk mengetahui informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.

Otorisasi

Tidak memerlukan header Otorisasi, tetapi ID klien dari aplikasi klien terdaftar harus diberikan dalam permintaan.

Contoh kebijakan

Ini adalah kebijakan GenerateAuthorizationCode dasar. Untuk opsi konfigurasi lainnya, lihat kebijakan OAuthV2:

<OAuthV2 name="GenerateAuthorizationCode">
    <Operation>GenerateAuthorizationCode</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Menampilkan

Dengan <GenerateResponse> diaktifkan, kebijakan menampilkan parameter kueri ?code ke lokasi redirect_uri (URI Callback) dengan kode otorisasi terlampir. ID ini dikirim melalui pengalihan browser 302 dengan URL di header Location respons. Misalnya: ?code=123456.

Jika <GenerateResponse> disetel ke false, kebijakan tidak akan menampilkan respons. Sebagai gantinya, variabel ini akan diisi dengan kumpulan variabel alur berikut yang berisi data terkait kode otorisasi.

oauthv2authcode.{policy-name}.code
oauthv2authcode.{policy-name}.scope
oauthv2authcode.{policy-name}.redirect_uri
oauthv2authcode.{policy-name}.client_id

Contoh:

oauthv2authcode.GenerateAuthorizationCode.code
oauthv2authcode.GenerateAuthorizationCode.scope
oauthv2authcode.GenerateAuthorizationCode.redirect_uri
oauthv2authcode.GenerateAuthorizationCode.client_id

Catatan: Anda juga dapat menetapkan atribut khusus dalam kebijakan OAuthV2. Atribut kustom akan ditampilkan dalam pola format yang sama seperti variabel lainnya: oauthv2.{policy_name}.{attribute_name}. Saat Anda membuat token akses dari kode otorisasi, token akses akan mewarisi variabel kustom yang ditetapkan dalam kode otorisasi. Lihat juga kebijakan OAuthV2.

Memperbarui token akses

Token refresh adalah kredensial yang Anda gunakan untuk mendapatkan token akses, biasanya setelah token akses berakhir masa berlakunya atau menjadi tidak valid. Token refresh ditampilkan dalam respons saat Anda menerima token akses.

Catatan: Konfigurasi kebijakan OAuthV2 di bagian ini menggunakan RefreshAccessToken operasi. Operasi ini memperbarui format token string buram. Anda juga dapat memperbarui token berformat JWT dengan mengganti operasi RefreshJWTAccessToken. Lihat juga Menggunakan operasi token OAuth JWT.

Catatan: Atribut yang ada di token akses tidak dapat ditambahkan/dihapus/diubah selama operasi RefreshAccessToken. Nilai di dalam elemen tidak diproses dalam operasi RefreshAccessToken. Gunakan kebijakan SetOAuthV2Info untuk memperbarui atribut.

Contoh permintaan

Untuk mengetahui informasi tentang encoding header autentikasi dasar dalam panggilan berikut, lihat Mengenkode kredensial autentikasi dasar.

$ curl -X POST \
  -H "Content-type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \
  https://apitest.acme.com/oauth/refresh \
  -d "grant_type=refresh_token&refresh_token=yVSL38WpuN3Kzn1UTMoE6AQ4ANZM"

Parameter yang diperlukan

Secara default, kebijakan mencari parameter ini sebagai parameter x-www-form-urlencoded yang ditentukan dalam isi permintaan, seperti yang ditunjukkan dalam contoh di atas. Untuk mengonfigurasi lokasi alternatif untuk input ini, Anda dapat menggunakan elemen <GrantType> dan <RefreshToken> dalam kebijakan OAuthV2. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.

• grant_type - Harus ditetapkan ke nilai refresh_token.
• refresh_token - Token refresh yang terkait dengan token akses yang ingin Anda perpanjang.

Parameter opsional

• status - String yang akan dikirim kembali dengan respons. Biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs.
• scope - Memungkinkan Anda memfilter daftar produk API yang dapat menggunakan token yang dicetak. Untuk mengetahui informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.

Otorisasi

Tidak memerlukan header Otorisasi, tetapi ID klien dari aplikasi klien terdaftar harus diberikan dalam permintaan.

Saat memuat ulang token akses, tidak ada autentikasi ulang pengguna.

Berikut contoh konfigurasi endpoint untuk membuat token akses menggunakan token refresh. Kebijakan RefreshAccessToken akan dijalankan.

 ...
       <Flow name="generate-refresh-token">
            <Request>
                <Step>
                    <Name>RefreshAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/refresh") and (request.verb = "POST")</Condition>
       </Flow>
...

Contoh kebijakan

Ini adalah kebijakan RefreshAccessToken dasar yang dikonfigurasi untuk menerima jenis pemberian refresh_token. Untuk mengetahui informasi tentang elemen konfigurasi opsional yang dapat Anda konfigurasi dengan kebijakan ini, lihat kebijakan OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
</OAuthV2>

Menampilkan

Dengan <GenerateResponse> diaktifkan, kebijakan akan menampilkan respons JSON yang berisi token akses baru. Jenis pemberian refresh_token mendukung pembuatan token akses dan token refresh baru. Contoh:

{
    "issued_at": "1420301470489",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "refresh_token_issued_at": "1420301470489",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "[e-mail]",
    "token_type": "BearerToken",
    "refresh_token": "8fKDHLryAD9KFBsrpixlq3qPJnG2fdZ5",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "jmZ2Hqv3iNsABUtAAsfWR3QGNctw",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "2"
}

Catatan: Masa berlaku token akses dan token refresh yang tercantum dalam respons adalah 1 detik lebih singkat dari yang ditentukan dalam konfigurasi kebijakan. Hal ini disebabkan oleh waktu transit dan margin keamanan. Ya, memang agak tidak biasa menentukan nilai habis masa berlaku dalam milidetik dalam kebijakan, tetapi menerimanya dalam detik di payload respons. Kami menyadarinya.

Anda harus tahu bahwa setelah token refresh baru dibuat, token asli tidak lagi valid.

Respons di atas adalah yang Anda dapatkan jika <GenerateResponse> disetel ke benar. Jika <GenerateResponse> disetel ke false, kebijakan tidak akan menampilkan respons. Sebagai gantinya, variabel ini akan mengisi kumpulan variabel konteks (alur) berikut dengan data yang berkaitan dengan pemberian token akses.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Contoh:

oauthv2accesstoken.RefreshAccessToken.access_token
oauthv2accesstoken.RefreshAccessToken.expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token
oauthv2accesstoken.RefreshAccessToken.refresh_token_expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token_issued_at
oauthv2accesstoken.RefreshAccessToken.refresh_token_status

Mengenkode kredensial autentikasi dasar

Saat Anda melakukan panggilan API untuk meminta token atau kode otorisasi, sebaiknya, dan direkomendasikan oleh spesifikasi OAuth 2.0 untuk meneruskan nilai client_id dan client_secret sebagai header Otorisasi HTTP-Basic, seperti yang dijelaskan dalam IETF RFC 2617. Untuk melakukannya, Anda harus mengenkode hasil penggabungan kedua nilai dengan base64, dengan titik dua sebagai pemisah.

Dalam kode semu:

result = Base64Encode(concat('ns4fQc14Zg4hKFCNaSzArVuwszX95X', ':', 'ZIjFyTsNgQNyxI'))

Dengan ns4fQc14Zg4hKFCNaSzArVuwszX95X adalah client_id dan ZIjFyTsNgQNyxI adalah rahasia klien.

Contoh

Contoh perintah ini berfungsi di Linux dan MacOS:

export CREDENTIALS=$(echo -n 'ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI' | base64)

Kemudian, Anda dapat membuat permintaan token sebagai berikut:

$ curl -i -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic $CREDENTIALS" \
  -X POST "https://apitest.acme.com/oauth/token" \
  -d "grant_type=client_credentials"

Meng-hash token dalam database

Apigee melakukan hashing pada semua token akses dan refresh OAuth untuk melindunginya jika terjadi pelanggaran keamanan database. Anda menggunakan token yang tidak di-hash dalam panggilan API, dan Apigee memvalidasinya terhadap versi yang di-hash dalam database.

Topik terkait

• Menerapkan jenis pemberian kredensial klien
• Menerapkan jenis pemberian kode otorisasi
• Kursus online keamanan API (termasuk OAuth)
• Kebijakan OAuthV2 -- Memiliki banyak contoh yang menunjukkan cara membuat permintaan ke server otorisasi dan cara mengonfigurasi kebijakan OAuthV2.