Meminta token akses dan kode otorisasi

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Dalam topik ini, kami akan menunjukkan cara meminta token akses dan kode otorisasi, mengonfigurasi endpoint OAuth 2.0, dan mengonfigurasi kebijakan untuk setiap jenis pemberian yang didukung.

Kode contoh

Untuk mempermudah, kebijakan dan endpoint yang dibahas dalam topik ini tersedia di GitHub dalam project oauth-doc-examples di repositori api-platform-samples Apigee. Anda dapat men-deploy kode contoh dan mencoba permintaan contoh yang ditampilkan dalam topik ini. Lihat README project untuk mengetahui detailnya.

Meminta token akses: jenis pemberian kode otorisasi

Bagian ini menjelaskan cara meminta token akses menggunakan alur jenis pemberian kode otorisasi. Untuk pengantar jenis pemberian izin OAuth 2.0, lihat Pengantar OAuth 2.0.

Contoh permintaan

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
   -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
   -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com'

Parameter wajib

Secara default, parameter ini harus 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 yang dilampirkan ke endpoint /accesstoken ini. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.

  • grant_type - Harus disetel ke nilai authorization_code.
  • code - Kode otorisasi yang diterima dari endpoint /authorize (atau nama apa pun yang Anda pilih). Untuk meminta token akses dalam alur jenis pemberian kode otorisasi, Anda harus mendapatkan kode otorisasi terlebih dahulu. Lihat Meminta kode otorisasi di bawah. Lihat juga Menerapkan jenis pemberian kode otorisasi.
  • redirect_uri - Anda harus memberikan parameter ini jika parameter redirect_uri disertakan dalam permintaan kode otorisasi sebelumnya. Jika parameter redirect_uri tidak disertakan dalam permintaan kode otorisasi, dan jika Anda tidak memberikan parameter ini, maka kebijakan ini akan menggunakan nilai URL Panggilan Balik yang diberikan saat aplikasi developer didaftarkan.

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 dibuat. Untuk mengetahui informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.

Authentication

Anda harus meneruskan ID Klien dan Rahasia Klien sebagai header Autentikasi 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 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>

Pengembalian

Dengan <GenerateResponse> diaktifkan, kebijakan akan menampilkan respons JSON yang mencakup token akses, seperti yang ditunjukkan di bawah. Jenis pemberian izin 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": "tesla@weathersample.com",
    "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"
}

Jika <GenerateResponse> disetel ke false, kebijakan tidak akan menampilkan respons. Sebagai gantinya, kebijakan ini akan mengisi kumpulan variabel 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.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

Meminta token akses: jenis pemberian kredensial klien

Bagian ini menjelaskan cara meminta token akses menggunakan alur jenis pemberian kredensial klien. Untuk pengantar jenis pemberian izin OAuth 2.0, lihat Pengantar OAuth 2.0.

Contoh permintaan

Untuk mengetahui informasi tentang cara mengenkode header autentikasi dasar dalam panggilan berikut, lihat "Mengenkode kredensial autentikasi dasar". 

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHoAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

Parameter wajib

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, default ini dapat diubah dengan mengonfigurasi elemen <GrantType> dalam kebijakan OAuthV2 yang terlampir pada endpoint /accesstoken ini. Misalnya, Anda dapat memilih untuk meneruskan parameter dalam parameter kueri. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.

  • grant_type - Harus disetel ke nilai client_credentials.

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 dibuat. Untuk mengetahui informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.

Authentication

Anda harus meneruskan ID Klien dan Rahasia Klien sebagai header Autentikasi 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 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>

Pengembalian

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": "tesla@weathersample.com",
    "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, kebijakan ini akan mengisi kumpulan variabel alur berikut dengan data yang berkaitan dengan 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

Meminta token akses: jenis pemberian sandi

Bagian ini menjelaskan cara meminta token akses menggunakan alur jenis pemberian kredensial (sandi) sandi pemilik resource. Untuk mengetahui pengantar jenis pemberian izin OAuth 2.0, lihat Pengantar OAuth 2.0.

Untuk mengetahui detail selengkapnya tentang jenis pemberian sandi, termasuk video berdurasi 4 menit yang menunjukkan cara menerapkannya, lihat Menerapkan jenis pemberian sandi.

Contoh permintaan

Untuk mengetahui informasi tentang cara mengenkode header autentikasi dasar dalam panggilan berikut, lihat "Mengenkode kredensial autentikasi dasar". 

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST https://docs-test.apigee.net/oauth/token \
  -d 'grant_type=password&username=the-user-name&password=the-users-password'

Parameter wajib

Secara default, parameter ini harus 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 yang dilampirkan ke endpoint /token ini. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.

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

  • grant_type - Harus disetel 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 dibuat. Untuk mengetahui informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.

Authentication

Anda harus meneruskan ID Klien dan Rahasia Klien sebagai header Autentikasi 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 contoh konfigurasi endpoint untuk membuat token akses. Kebijakan ini akan mengeksekusi kebijakan GenerateAccessToken, 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>

Pengembalian

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

{
    "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": "tesla@weathersample.com",
    "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, kebijakan ini akan mengisi kumpulan variabel 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.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

Meminta token akses: jenis pemberian izin implisit

Bagian ini menjelaskan cara meminta token akses menggunakan alur jenis pemberian implisit. Untuk pengantar jenis pemberian izin OAuth 2.0, lihat Pengantar OAuth 2.0.

Contoh permintaan

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'https://docs-test.apigee.net/oauth/implicit?response_type=token&client_id=ABC123&redirect_uri=http://callback-example.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 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 dibuat. Untuk mengetahui informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.

Authentication

Pemberian implisit tidak memerlukan autentikasi dasar. Anda harus meneruskan client ID sebagai parameter permintaan, seperti yang dijelaskan di sini.

Endpoint contoh

Berikut 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>

Pengembalian

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, kebijakan ini akan mengisi kumpulan variabel alur berikut dengan data yang berkaitan dengan 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

Meminta kode otorisasi

Jika menggunakan alur jenis pemberian kode otorisasi, Anda harus mendapatkan kode otorisasi sebelum dapat meminta token akses.

Contoh permintaan

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code'

dengan kebijakan OAuthV2 GenerateAuthorizationCode dilampirkan di endpoint proxy /oauth/authorize (lihat contoh endpoint di bawah).

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 yang dilampirkan ke endpoint /authorize ini. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.

  • 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 Edge mengirimkan kode auth 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 dibuat. Untuk mengetahui informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.

Authentication

Tidak memerlukan autentikasi dasar, tetapi ID klien aplikasi klien terdaftar harus disediakan dalam permintaan.

Endpoint contoh

Berikut adalah contoh konfigurasi endpoint untuk membuat kode otorisasi:

<OAuthV2 name="GenerateAuthorizationCode">
  <Operation>GenerateAuthorizationCode</Operation>
    <!--
    ExpiresIn, in milliseconds. The ref is optional. The explicitly specified
    value is the default, when the variable reference cannot be resolved.
        60000 = 1 minute
       120000 = 2 minutes
    -->
  <ExpiresIn>60000</ExpiresIn>
  <GenerateResponse enabled="true"/>
</OAuthV2>

Contoh kebijakan

Ini adalah kebijakan GenerateAuthorizationCode dasar. Untuk mengetahui informasi tentang elemen konfigurasi opsional yang dapat Anda konfigurasi dengan kebijakan ini, lihat kebijakan OAuthV2.

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

Pengembalian

Dengan <GenerateResponse> diaktifkan, kebijakan menampilkan parameter kueri ?code ke lokasi redirect_uri (URI Callback) dengan kode otorisasi terlampir. URL 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 data yang berkaitan dengan 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

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.

Untuk meminta token akses baru menggunakan token refresh:

Contoh permintaan

Untuk mengetahui informasi tentang cara mengenkode 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://myorg-test.apigee.net/my_oauth_endpoint/refresh_accesstoken \
  -d 'grant_type=refresh_token&refresh_token=my-refresh-token'

Parameter yang diperlukan

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

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.

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 dibuat. Untuk mengetahui informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.

Authentication

  • client_id
  • client_secret

Anda harus meneruskan ID Klien dan Rahasia Klien sebagai header Autentikasi Dasar (berenkode Base64) atau sebagai parameter formulir client_id dan client_secret. Lihat juga "Mengenkode kredensial autentikasi dasar".

Saat memperbarui token akses, tidak ada autentikasi ulang pengguna.

Berikut contoh konfigurasi endpoint untuk membuat token akses menggunakan token refresh. Kebijakan ini akan menjalankan kebijakan RefreshAccessToken.

 ...
       <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>

Pengembalian

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": "tesla@weathersample.com",
    "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"
}

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 Autentikasi 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'))

Dalam contoh ini, ns4fQc14Zg4hKFCNaSzArVuwszX95X adalah client_id dan ZIjFyTsNgQNyxI adalah rahasia klien.

Terlepas dari bahasa pemrograman yang Anda gunakan untuk menghitung nilai berenkode base64, untuk kredensial klien yang diberikan tersebut, hasil berenkode base64 adalah: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

Kemudian, Anda dapat membuat permintaan token sebagai berikut:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

Utilitas curl akan membuat header HTTP Basic untuk Anda, jika Anda menggunakan opsi -u. Berikut ini setara dengan di atas:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

Lingkungan pemrograman lain mungkin memiliki pintasan serupa yang otomatis membuat header berenkode base64.

Melakukan hashing pada token dalam database

Untuk melindungi token akses dan refresh OAuth jika terjadi pelanggaran keamanan database, Anda dapat mengaktifkan hashing token otomatis di organisasi Edge Anda. Jika fitur ini diaktifkan, Edge akan otomatis membuat versi hash dari token akses dan token refresh OAuth yang baru dibuat menggunakan algoritma yang Anda tentukan. (Informasi tentang hashing massal token yang ada akan dijelaskan di bawah.) Token yang tidak di-hash digunakan dalam panggilan API, dan Edge memvalidasinya terhadap versi yang di-hash dalam database.

Properti tingkat organisasi berikut mengontrol hashing token OAuth.

features.isOAuthTokenHashingEnabled = true
features.OAuthTokenHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Jika Anda memiliki token hash yang ada dan ingin mempertahankannya hingga masa berlakunya berakhir, tetapkan properti berikut di organisasi Anda, dengan algoritma hashing yang cocok dengan algoritma yang ada (misalnya, SHA1, default Edge sebelumnya). Jika token tidak di-hash, gunakan PLAIN.

features.isOAuthTokenFallbackHashingEnabled = true
features.OAuthTokenFallbackHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Jika Anda adalah pelanggan cloud Edge, hubungi Dukungan Apigee Edge untuk menyetel properti ini di organisasi Anda dan secara opsional untuk melakukan hashing massal pada token yang ada.

Topik terkait