Halaman ini diterjemahkan oleh Cloud Translation API.

Meminta token akses dan kode otorisasi

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

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

Kode contoh

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

Meminta token akses: jenis pemberian kode otorisasi

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

Contoh meminta

$ 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'

Wajib diisi parameter

Secara default, parameter ini harus berupa x-www-form-urlencoded dan ditentukan dalam kolom isi permintaan (seperti yang ditunjukkan dalam contoh di atas); Namun, Anda dapat mengubah setelan default ini mengonfigurasi <GrantType>, <Code>, dan Elemen <RedirectUri> dalam kebijakan OAuthV2 yang dilampirkan Endpoint /accesstoken. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.

grant_type - Harus ditetapkan ke nilai authorization_code.
code - Kode otorisasi yang diterima dari /authorize endpoint (atau apa pun nama yang Anda pilih). Untuk meminta token akses dalam otorisasi dalam alur jenis pemberian kode, Anda harus terlebih dahulu mendapatkan kode otorisasi. 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 menyediakan parameter ini, kebijakan ini akan menggunakan nilai URL Callback yang diberikan saat aplikasi developer didaftarkan.

Opsional parameter

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

Autentikasi

Anda harus meneruskan Client ID 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 yang terdaftar. Lihat juga "Dasar pengkodean kredensial autentikasi".

Contoh endpoint

Berikut adalah contoh konfigurasi endpoint untuk membuat token akses. Fungsi ini akan menjalankan Kebijakan GenerateAccessToken, yang harus dikonfigurasi untuk mendukung pemberian otorisasi_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 authorization_code jenis pemberian. Untuk 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 mengaktifkan <GenerateResponse>, kebijakan akan menampilkan respons JSON yang menyertakan token akses, seperti yang ditunjukkan di bawah ini. 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": "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 salah (false), kebijakan tidak akan menampilkan yang dihasilkan. Sebaliknya, ia mengisi rangkaian variabel aliran 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: klien jenis pemberian kredensial

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

Contoh meminta

Untuk informasi tentang pengkodean 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'

Wajib diisi parameter

Secara default, parameter Grants_type yang diperlukan harus berupa x-www-form-urlencoded dan ditentukan dalam isi permintaan (seperti yang ditunjukkan dalam contoh di atas); Namun, ada kemungkinan untuk mengubah secara default dengan mengonfigurasi elemen <GrantType> dalam kebijakan OAuthV2 yang dilampirkan ke endpoint /accesstoken ini. Misalnya, Anda dapat memilih untuk meneruskan dalam parameter kueri. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.

grant_type - Harus ditetapkan ke nilai client_credentials.

Opsional parameter

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

Autentikasi

Anda harus meneruskan Client ID 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 yang terdaftar yang terkait dengan permintaan. Lihat juga "Autentikasi dasar encoding kredensial".

Contoh endpoint

Berikut adalah contoh konfigurasi endpoint untuk membuat token akses. Fungsi ini akan menjalankan Kebijakan GenerateAccessToken, yang harus dikonfigurasi untuk mendukung 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 client_credentials jenis pemberian. Untuk 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 mengaktifkan <GenerateResponse>, kebijakan akan menampilkan respons JSON. Catatan bahwa dengan jenis pemberian client_credentials, token refresh tidak didukung. Hanya token akses dicetak. 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"
}

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 sandi pemilik resource aliran jenis pemberian kredensial ({i>password<i}). Untuk pengenalan 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 sandi jenis pemberian izin.

Contoh meminta

Untuk informasi tentang pengkodean 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'

Wajib diisi parameter

Secara default, parameter ini harus berupa x-www-form-urlencoded dan ditentukan dalam kolom isi permintaan (seperti yang ditunjukkan dalam contoh di atas); Namun, Anda dapat mengubah setelan default ini mengonfigurasi <GrantType>, <Username>, dan Elemen <Password> dalam kebijakan OAuthV2 yang dilampirkan Endpoint /token. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.

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

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

Opsional parameter

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

Autentikasi

Anda harus meneruskan Client ID 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 yang terdaftar yang terkait dengan permintaan. Lihat juga "Autentikasi dasar encoding kredensial".

Contoh endpoint

Berikut adalah contoh konfigurasi endpoint untuk membuat token akses. Fungsi ini akan menjalankan 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 pemberian sandi . Untuk 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 mengaktifkan <GenerateResponse>, kebijakan akan menampilkan respons JSON. Catatan dengan tipe pemberian {i>password<i}, kedua token akses dan token pembaruan akan dicetak. 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"
}

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: pemberian implisit (jenis

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

Contoh meminta

$ 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'

Wajib diisi parameter

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

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

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

Opsional parameter

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

Autentikasi

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

Contoh endpoint

Berikut adalah contoh konfigurasi endpoint untuk membuat token akses. Fungsi ini akan menjalankan Kebijakan GenerateAccessTokenImplicitGrant.

...
       <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 aliran jenis pemberian izin implisit. Untuk informasi tentang elemen konfigurasi opsional yang bisa Anda mengonfigurasi 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 redirect_uri dan ditambahkan dengan token akses dan waktu habis masa berlaku token. Perhatikan bahwa perintah jenis pemberian izin tidak mendukung token refresh. Contoh:

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

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 otorisasi sebelum Anda 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 GenerateAuthorizationCode OAuthV2 dilampirkan pada Endpoint proxy /oauth/authorize (lihat endpoint contoh di bawah).

Wajib diisi parameter

Secara default, parameter ini harus berupa parameter kueri (seperti yang ditunjukkan pada contoh di atas); namun, Anda dapat mengubah setelan default ini dengan mengonfigurasi <ResponseType>, Elemen <ClientId>, dan <RedirectUri> di OAuthV2 kebijakan yang dilampirkan ke endpoint /authorize ini. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.

response_type - Harus ditetapkan ke nilai code.
client_id - ID klien aplikasi developer terdaftar.

Opsional parameter

redirect_uri - Jika URI Callback penuh (bukan sebagian) ditentukan dalam aplikasi klien yang terdaftar, parameter ini bersifat opsional; jika tidak, maka diperlukan. Callback adalah URL tempat Edge mengirimkan kode otentikasi yang baru dibuat. Lihat juga Mendaftarkan aplikasi dan mengelola API .
state - String yang akan dikirim kembali dengan respons. Biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs.
scope - Memungkinkan Anda memfilter daftar produk API yang digunakan yang dibuat token dapat digunakan. Untuk informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.

Autentikasi

Tidak memerlukan otentikasi dasar, namun ID klien dari aplikasi klien yang terdaftar harus disediakan dalam permintaan.

Contoh endpoint

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 konfigurasi opsional yang dapat Anda konfigurasi dengan kebijakan ini, baca kebijakan OAuthV2.

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

Pengembalian

Jika <GenerateResponse> diaktifkan, kebijakan akan menampilkan ?code parameter kueri ke lokasi redirect_uri (URI Callback) dengan otorisasi kode terlampir. Ini dikirim melalui pengalihan browser 302 dengan URL di header Location pada yang dihasilkan. Contoh: ?code=123456.

Jika <GenerateResponse> disetel ke false, kebijakan tidak akan membalas respons. Sebaliknya, ia mengisi rangkaian variabel {i>flow<i} berikut dengan data yang berkaitan di 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. Khusus akan ditampilkan dalam pola format yang sama dengan variabel lainnya: oauthv2.{policy_name}.{attribute_name}. Saat Anda membuat token akses dari kode autentikasi, token akses akan mewarisi variabel kustom apa pun yang ditetapkan dalam kode autentikasi. Lihat juga Kebijakan OAuthV2.

Memperbarui token akses

Token refresh adalah kredensial yang Anda gunakan untuk mendapatkan token akses, biasanya setelah akses masa berlaku token telah habis atau menjadi tidak valid. Token refresh ditampilkan sebagai respons ketika Anda menerima token akses.

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

Untuk meminta token akses baru menggunakan token refresh:

Contoh permintaan

Untuk informasi tentang pengkodean 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 ditetapkan ke nilai refresh_token.
refresh_token - Token refresh yang terkait dengan token akses yang ingin memperpanjang.

Secara default, kebijakan akan mencarinya 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 <GrantType> dan <RefreshToken> dalam kebijakan OAuthV2. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.

Parameter opsional

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

Autentikasi

client_id
client_secret

Anda harus meneruskan Client ID 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 memuat ulang token akses, tidak ada autentikasi ulang pengguna.

Berikut contoh konfigurasi endpoint untuk membuat token akses menggunakan token refresh. Tindakan ini akan mengeksekusi 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 refresh_token jenis pemberian. Untuk informasi tentang elemen konfigurasi opsional yang 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 mengaktifkan <GenerateResponse>, kebijakan akan menampilkan respons JSON yang berisi token akses baru. Jenis pemberian refresh_token mendukung pencetakan 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 mengetahui bahwa setelah token refresh baru dibuat, token asli tidak lagi valid.

Respons di atas adalah yang Anda dapatkan jika <GenerateResponse> ditetapkan ke true. Jika <GenerateResponse> disetel ke salah (false), kebijakan tidak akan menampilkan respons. Sebaliknya, ia 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

Encoding kredensial autentikasi dasar

Saat Anda melakukan panggilan API untuk meminta token atau kode otentikasi, ini adalah praktik yang baik, dan direkomendasikan oleh spesifikasi OAuth 2.0 untuk meneruskan nilai client_id dan client_secret sebagai header Autentikasi Dasar HTTP, seperti yang dijelaskan di IETF RFC 2617. Untuk melakukannya, Anda harus melakukan enkode base64 pada hasil penggabungan dua nilai bersama dengan tanda titik dua yang memisahkannya.

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 berdasarkan kredensial klien, hasil yang dienkode dengan 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. Hal berikut setara dengan yang 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 secara otomatis menghasilkan header berenkode base64.

Token hashing dalam database

Untuk melindungi akses OAuth dan memperbarui token jika terjadi pelanggaran keamanan database, Anda dapat mengaktifkan {i>hashing<i} token otomatis di organisasi Edge Anda. Saat fitur ini diaktifkan, Edge otomatis membuat versi hash dari akses OAuth dan token refresh yang baru dibuat menggunakan algoritma yang Anda tentukan. (Berikut informasi tentang cara melakukan hashing massal pada token yang sudah ada.) Tujuan token tanpa hash digunakan dalam panggilan API, dan Edge memvalidasinya terhadap versi yang di-hash di {i>database<i}.

Properti tingkat organisasi berikut mengontrol hashing token OAuth.

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

Jika Anda memiliki token yang di-hash dan ingin mempertahankannya sampai habis masa berlakunya, tetapkan properti berikut di organisasi Anda, dengan algoritma {i>hashing <i}yang cocok dengan (misalnya, SHA1, default Edge sebelumnya). Jika token tidak di-hash, gunakan PLAIN.

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

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

Private Cloud: Untuk pelanggan Edge bagi pelanggan Private Cloud, gunakan panggilan API berikut dengan kredensial administrator sistem.

curl -u email:password -X PUT -H "Content-Type: application/xml" https://host:port/v1/o/{myorg} \
  -d '<Organization type="trial" name="MyOrganization">
    <Properties>
        <Property name="features.isOAuthTokenHashingEnabled">true</Property>
        <Property name="features.OAuthTokenHashingAlgorithm">SHA256</Property>
        <Property name="features.isOAuthTokenFallbackHashingEnabled">true</Property>
        <Property name="features.OAuthTokenFallbackHashingAlgorithm">SHA1</Property>
        <Property...(an existing property)
        <Property...(an existing property)
        <Property...(an existing property)
    </Properties>
  </Organization>'

Melakukan hashing token yang ada secara massal

Edge juga menyediakan skrip yang dapat Anda jalankan untuk melakukan hashing pada token yang ada. Untuk informasi selengkapnya, lihat Edge for Private Cloud Operations Guide versi 4.15.07.00 dan yang lebih baru.

Topik terkait

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