View a markdown version of this page

Titik akhir pengalihan dan otorisasi - Amazon Cognito
DAPATKAN/oauth2/authorizeContoh: pemberian kode otorisasiContoh: pemberian kode otorisasi dengan PKCEContoh: memerlukan otentikasi ulang dengan prompt=loginContoh: otentikasi diam dengan prompt=noneContoh: pemberian kode otorisasi dengan pengikatan sumber dayaContoh: Pemberian token (implisit) tanpa cak upan openidContoh: Hibah Token (implisit) dengan cak upan openidTanggapan kesalahan

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Titik akhir pengalihan dan otorisasi

T /oauth2/authorize itik akhir adalah titik akhir pengalihan yang mendukung dua tujuan pengalihan. Jika Anda menyertakan idp_identifier parameter identity_provider atau di URL, parameter tersebut secara diam-diam akan mengalihkan pengguna Anda ke halaman masuk untuk penyedia identitas (IdP) tersebut. Jika tidak, itu dialihkan ke Titik akhir login parameter URL yang sama yang Anda sertakan dalam permintaan Anda.

Titik akhir otorisasi mengalihkan ke login terkelola atau ke halaman masuk IdP. Tujuan sesi pengguna di titik akhir ini adalah halaman web yang harus berinteraksi langsung dengan pengguna Anda di browser mereka.

Untuk menggunakan titik akhir otorisasi, panggil browser pengguna Anda di /oauth2/authorize dengan parameter yang menyediakan kumpulan pengguna Anda dengan informasi tentang detail kumpulan pengguna berikut.

  • Klien aplikasi yang ingin Anda masukkannya.

  • URL panggilan balik yang ingin Anda dapatkan.

  • Cakupan OAuth 2.0 yang ingin Anda minta di token akses pengguna Anda.

  • Secara opsional, IdP pihak ketiga yang ingin Anda gunakan untuk masuk.

Anda juga dapat menyediakan state dan nonce parameter yang digunakan Amazon Cognito untuk memvalidasi klaim yang masuk.

DAPATKAN/oauth2/authorize

Titik akhir /oauth2/authorize hanya mendukung HTTPS GET. Aplikasi Anda biasanya memulai permintaan ini di browser pengguna Anda. Anda hanya dapat membuat permintaan ke titik /oauth2/authorize akhir melalui HTTPS.

Anda dapat mempelajari lebih lanjut tentang definisi titik akhir otorisasi dalam standar OpenID Connect (OIDC) di Titik Akhir Otor isasi.

Permintaan parameter

response_type

Wajib.

Jenis respon. Harus code atau token.

Permintaan yang berhasil dengan response_type a code mengembalikan pemberian kode otorisasi. Pemberian kode otorisasi adalah code parameter yang ditambahkan Amazon Cognito ke URL pengalihan Anda. Aplikasi Anda dapat menukar kode dengan token akses, ID, dan penyegaran. Titik akhir token Sebagai praktik terbaik keamanan, dan untuk menerima token penyegaran bagi pengguna Anda, gunakan pemberian kode otorisasi di aplikasi Anda.

Permintaan yang berhasil dengan response_type pengem token balian hibah implisit. Hibah implisit adalah ID dan token akses yang ditambahkan Amazon Cognito ke URL pengalihan Anda. Hibah implisit kurang aman karena mengekspos token dan informasi identifikasi potensial kepada pengguna. Anda dapat menonaktifkan dukungan untuk hibah implisit dalam konfigurasi klien aplikasi Anda.

client_id

Wajib.

ID klien aplikasi.

Nilai client_id harus berupa ID klien aplikasi di kumpulan pengguna tempat Anda membuat permintaan. Klien aplikasi Anda harus mendukung proses masuk oleh pengguna lokal Amazon Cognito atau setidaknya satu IdP pihak ketiga.

redirect_uri

Wajib.

URL tempat server otentikasi mengalihkan browser setelah Amazon Cognito mengotorisasi pengguna.

Pengidentifikasi sumber daya seragam pengalihan (URI) harus memiliki atribut berikut:

  • Ini harus URI mutlak.

  • Anda harus melakukan pra-registrasi URI dengan klien.

  • Itu tidak dapat menyertakan komponen fragmen.

Lihat OAuth 2.0 - Titik Akhir Pengalihan.

Amazon Cognito mengharuskan URI pengalihan Anda menggunakan HTTPS, kecualihttp://localhost, yang dapat Anda tetapkan sebagai URL panggilan balik untuk tujuan pengujian.

Amazon Cognito juga mendukung URL panggilan balik aplikasi seperti. myapp://example

state

Opsional, direkomendasikan.

Saat aplikasi menambahkan parameter status ke permintaan, Amazon Cognito mengembalikan nilainya ke aplikasi Anda saat /oauth2/authorize titik akhir mengalihkan pengguna Anda.

Tambahkan nilai ini ke permintaan Anda untuk melindungi dari serangan CSRF.

Anda tidak dapat mengatur nilai state parameter ke string URL-encoded JSON. Untuk meneruskan string yang cocok dengan format ini dalam state parameter, kodekan string ke base64, lalu dekodekan di aplikasi Anda.

identity_provider

Tidak wajib.

Tambahkan parameter ini untuk melewati login terkelola dan mengarahkan pengguna Anda ke halaman masuk penyedia. Nilai parameter identity_provider adalah nama penyedia identitas (IdP) seperti yang muncul di kumpulan pengguna Anda.

  • Untuk penyedia sosial, Anda dapat menggunakan nilai identity_providerFacebook,,Google, LoginWithAmazon dan. SignInWithApple

  • Untuk kumpulan pengguna Amazon Cognito, gunakan nilainyaCOGNITO.

  • Untuk penyedia identitas SAML 2.0 dan OpenID Connect (OIDC) (IdPs), gunakan nama yang Anda tetapkan ke IdP di kumpulan pengguna Anda.

idp_identifier

Tidak wajib.

Tambahkan parameter ini untuk mengarahkan ke penyedia dengan nama alternatif untuk nama identity_provider. Anda dapat memasukkan pengidentifikasi untuk SAML 2.0 dan OIDC Anda IdPs dari menu penyedia sosial dan eksternal di konsol Amazon Cognito.

scope

Tidak wajib.

Dapat menjadi kombinasi dari cakupan sistem cadangan atau cakupan kustom yang terkait dengan klien. Lingkup harus dipisahkan oleh spasi. Cakupan sistem cadangan adalah openid, email, phone, profile, dan aws.cognito.signin.user.admin. Lingkup yang digunakan harus dikaitkan dengan klien, atau akan diabaikan pada saat waktu aktif.

Jika klien tidak meminta cakupan apa pun, server autentikasi menggunakan semua cakupan yang terkait dengan klien.

Token ID hanya dikembalikan jika cakupan openid diminta. Token akses hanya dapat digunakan terhadap kolam pengguna Amazon Cognito jika cakupan aws.cognito.signin.user.admin diminta. Cakupan phone, email, dan profile hanya dapat diminta jika cakupan openid juga diminta. Lingkup ini mendikte klaim yang masuk ke dalam token ID.

code_challenge_method

Tidak wajib.

Protokol hashing yang Anda gunakan untuk menghasilkan tantangan. PKCE RFC mendefinisikan dua metode, S256 dan polos; namun, server autentikasi Amazon Cognito hanya mendukung S256.

code_challenge

Tidak wajib.

Tantangan bukti pertukaran kode kunci (PKCE) yang Anda hasilkan dari. code_verifier Untuk informasi selengkapnya, lihat Menggunakan PKCE dalam pemberian kode otorisasi.

Diperlukan hanya ketika Anda menentukan code_challenge_method parameter.

nonce

Tidak wajib.

Nilai acak yang dapat Anda tambahkan ke permintaan. Nilai nonce yang Anda berikan disertakan dalam token ID yang dikeluarkan Amazon Cognito. Untuk mencegah serangan replay, aplikasi Anda dapat memeriksa nonce klaim di token ID dan membandingkannya dengan yang Anda buat. Untuk informasi selengkapnya tentang nonce klaim, lihat validasi token ID dalam standar OpenID Connect.

lang

Tidak wajib.

Bahasa tempat Anda ingin menampilkan halaman interaktif pengguna. Halaman login terkelola dapat dilokalkan, tetapi halaman UI (klasik) yang dihosting tidak dapat. Untuk informasi selengkapnya, lihat Pelokalan proses masuk terkelola.

login_hint

Tidak wajib.

Prompt nama pengguna yang ingin Anda sampaikan ke server otorisasi. Anda dapat mengumpulkan nama pengguna, alamat email, atau nomor telepon dari pengguna Anda dan mengizinkan penyedia tujuan untuk mengisi nama masuk pengguna terlebih dahulu. Saat Anda mengirimkan login_hint parameter dan tidak ada idp_identifier atau identity_provider parameter ke oauth2/authorize titik akhir, login terkelola mengisi bidang nama pengguna dengan nilai petunjuk Anda. Anda juga dapat meneruskan parameter ini ke Titik akhir login dan secara otomatis mengisi nilai nama pengguna.

Saat permintaan otorisasi Anda memanggil pengalihan ke OIDC IdPs, Amazon Cognito menambahkan login_hint parameter ke permintaan ke otorisasi pihak ketiga tersebut. Anda tidak dapat meneruskan petunjuk login ke SAML, Apple, Login With Amazon, Google, atau Facebook (Meta) IdPs.

prompt

Tidak wajib.

Parameter OIDC yang mengontrol perilaku otentikasi untuk sesi yang ada. Tersedia dalam versi branding login terkelola saja, tidak di UI yang dihosting klasik. Untuk informasi selengkapnya dari spesifikasi OIDC, lihat Permintaan https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest otentikasi. Nilai none dan login memiliki efek pada perilaku otentikasi kumpulan pengguna.

Amazon Cognito meneruskan semua nilai prompt kecuali none kepada Anda IdPs ketika pengguna memilih otentikasi dengan penyedia pihak ketiga. Ini benar ketika URL yang diakses pengguna menyertakan idp_identifier parameter identity_provider atau, atau ketika server otorisasi mengalihkan mereka ke Titik akhir login dan mereka memilih dan IdP dari tombol yang tersedia.

Nilai parameter prompt
prompt=none

Amazon Cognito secara diam-diam melanjutkan otentikasi untuk pengguna yang memiliki sesi otentikasi yang valid. Dengan prompt ini, pengguna dapat secara diam-diam mengotentikasi antara klien aplikasi yang berbeda di kumpulan pengguna Anda. Jika pengguna belum diautentikasi, server otorisasi mengembalikan login_required kesalahan.

prompt=login

Amazon Cognito mengharuskan pengguna untuk melakukan autentikasi ulang meskipun mereka memiliki sesi yang sudah ada. Kirim nilai ini saat Anda ingin memverifikasi identitas pengguna lagi. Pengguna terautentikasi yang memiliki sesi yang sudah ada dapat kembali masuk tanpa membatalkan sesi tersebut. Ketika pengguna yang memiliki sesi yang sudah ada masuk lagi, Amazon Cognito menetapkan cookie sesi baru kepada mereka. Parameter ini juga dapat diteruskan ke Anda IdPs. IdPsyang menerima parameter ini juga meminta upaya otentikasi baru dari pengguna.

prompt=select_account

Nilai ini tidak berpengaruh pada login lokal dan harus dikirimkan dalam permintaan yang dialihkan ke IdPs. Ketika disertakan dalam permintaan otorisasi Anda, parameter ini prompt=select_account menambah jalur URL untuk tujuan pengalihan IdP. Saat IdPs mendukung parameter ini, mereka meminta agar pengguna memilih akun yang ingin mereka gunakan untuk masuk.

prompt=consent

Nilai ini tidak berpengaruh pada login lokal dan harus dikirimkan dalam permintaan yang dialihkan ke IdPs. Ketika disertakan dalam permintaan otorisasi Anda, parameter ini prompt=consent menambah jalur URL untuk tujuan pengalihan IdP. Saat IdPs mendukung parameter ini, mereka meminta persetujuan pengguna sebelum mereka mengarahkan kembali ke kumpulan pengguna Anda.

Ketika Anda menghilangkan prompt parameter dari permintaan Anda, login terkelola mengikuti perilaku default: pengguna harus masuk kecuali browser mereka memiliki cookie sesi login terkelola yang valid. Anda dapat menggabungkan beberapa nilai untuk prompt dengan pembatas karakter spasi, misalnya. prompt=login consent

resource

Tidak wajib.

Pengidentifikasi sumber daya yang ingin Anda ikat ke token akses dalam aud klaim. Saat Anda menyertakan parameter ini, Amazon Cognito memvalidasi bahwa nilainya adalah URL dan menetapkan audiens token akses yang dihasilkan ke sumber daya yang diminta. Anda dapat meminta server sumber daya kumpulan pengguna dengan pengidentifikasi dalam format URL, atau URL pilihan Anda. Nilai untuk parameter ini harus dimulai dengan https://http://localhost,, atau skema URL khusus sepertimyapp://.

Pengikatan sumber daya didefinisikan dalam RFC 8 707. Untuk informasi selengkapnya tentang server sumber daya dan pengikatan sumber daya, lihat Pengikatan sumber daya.

Contoh: pemberian kode otorisasi

Ini adalah contoh permintaan untuk pemberian kode otorisasi.

Permintaan berikut memulai sesi untuk mengambil kode otorisasi yang diteruskan pengguna ke aplikasi Anda di redirect_uri tujuan. Sesi ini meminta cakupan untuk atribut pengguna dan untuk akses ke operasi API layanan mandiri Amazon Cognito.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=openid+profile+aws.cognito.signin.user.admin

Server autentikasi Amazon Cognito mengalihkan kembali ke aplikasi Anda dengan kode otorisasi dan status. Kode otorisasi berlaku selama lima menit.

HTTP/1.1 302 Found
Location: https://www.example.com?code=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111&state=abcdefg

Contoh: pemberian kode otorisasi dengan PKCE

Alur contoh ini melakukan pemberian kode otorisasi dengan PKCE.

Permintaan ini menambahkan code_challenge parameter. Untuk menyelesaikan pertukaran kode untuk token, Anda harus menyertakan code_verifier parameter dalam permintaan Anda ke /oauth2/token titik akhir.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=aws.cognito.signin.user.admin&
code_challenge_method=S256&
code_challenge=a1b2c3d4...

Server otorisasi mengalihkan kembali ke aplikasi Anda dengan kode otorisasi dan status. Aplikasi Anda memproses kode otorisasi dan menukarnya dengan token.

HTTP/1.1 302 Found
Location: https://www.example.com?code=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111&state=abcdefg

Contoh: memerlukan otentikasi ulang dengan prompt=login

Permintaan berikut menambahkan prompt=login parameter yang mengharuskan pengguna untuk mengotentikasi lagi, bahkan jika mereka memiliki sesi yang sudah ada.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=openid+profile+aws.cognito.signin.user.admin&
prompt=login

Server otorisasi mengalihkan ke titik akhir login, memerlukan otentikasi ulang.

HTTP/1.1 302 Found Location: https://mydomain.auth.us-east-1.amazoncognito.com/login?response_type=code&client_id=1example23456789&redirect_uri=https://www.example.com&state=abcdefg&scope=openid+profile+aws.cognito.signin.user.admin&prompt=login

Contoh: otentikasi diam dengan prompt=none

Permintaan berikut menambahkan prompt=none parameter yang secara diam-diam memeriksa apakah pengguna memiliki sesi yang valid.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=openid+profile+aws.cognito.signin.user.admin&
prompt=none

Ketika tidak ada sesi yang valid, server otorisasi mengembalikan kesalahan ke URI pengalihan

HTTP/1.1 302 Found Location: https://www.example.com?error=login_required&state=abcdefg

Ketika sesi yang valid ada, server otorisasi mengembalikan kode otorisasi.

HTTP/1.1 302 Found Location: https://www.example.com?code=AUTHORIZATION_CODE&state=abcdefg

Contoh: pemberian kode otorisasi dengan pengikatan sumber daya

Permintaan berikut menambahkan resource parameter untuk mengikat token akses ke server sumber daya tertentu. Token akses yang dihasilkan menciptakan kondisi untuk API target untuk memvalidasi bahwa itu adalah audiens yang dituju dari permintaan pengguna yang diautentikasi.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=solar-system-data-api.example.com/asteroids.add&
resource=https://solar-system-data-api.example.com

Server otorisasi mengembalikan kode otorisasi yang menghasilkan token akses dengan aud klaimhttps://solar-system-data-api.example.com.

HTTP/1.1 302 Found Location: https://www.example.com?code=AUTHORIZATION_CODE&state=abcdefg

Contoh: Pemberian token (implisit) tanpa cak upan openid

Alur contoh ini menghasilkan hibah implisit dan mengembalikan JWT langsung ke sesi pengguna.

Permintaannya adalah untuk hibah implisit dari server otorisasi Anda. Ini meminta cakupan dalam token akses yang mengotorisasi operasi swalayan profil pengguna.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=token&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=aws.cognito.signin.user.admin

Server otorisasi mengalihkan kembali ke aplikasi Anda hanya dengan token akses. Karena openid cakupan tidak diminta, Amazon Cognito tidak mengembalikan token ID. Selain itu, Amazon Cognito tidak mengembalikan token penyegaran dalam alur ini.

HTTP/1.1 302 Found
Location: https://example.com/callback#access_token=eyJra456defEXAMPLE&token_type=bearer&expires_in=3600&state=STATE

Contoh: Hibah Token (implisit) dengan cak upan openid

Alur contoh ini menghasilkan hibah implisit dan mengembalikan token ke browser pengguna.

Permintaannya adalah untuk hibah implisit dari server otorisasi Anda. Ini meminta cakupan dalam token akses yang mengotorisasi akses ke atribut pengguna dan operasi layanan mandiri.

GET
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize? 
response_type=token& 
client_id=1example23456789& 
redirect_uri=https://www.example.com& 
state=abcdefg&
scope=aws.cognito.signin.user.admin+openid+profile

Server otorisasi mengalihkan kembali ke aplikasi Anda dengan token akses dan token ID (karena cak openid upan disertakan):

HTTP/1.1 302 Found
Location: https://www.example.com#id_token=eyJra67890EXAMPLE&access_token=eyJra12345EXAMPLE&token_type=bearer&expires_in=3600&state=abcdefg

Contoh tanggapan negatif

Amazon Cognito mungkin menolak permintaan Anda. Permintaan negatif datang dengan kode kesalahan HTTP dan deskripsi yang dapat Anda gunakan untuk memperbaiki parameter permintaan Anda. Berikut ini adalah contoh tanggapan negatif.

  • redirect_uriJika client_id dan valid, tetapi parameter permintaan tidak diformat dengan benar, server otentikasi mengalihkan kesalahan ke klien redirect_uri dan menambahkan pesan kesalahan dalam parameter URL. Berikut ini adalah contoh pemformatan yang salah.

    • Permintaan tidak menyertakan response_type parameter.

    • Permintaan otorisasi memberikan code_challenge parameter, tetapi bukan code_challenge_method parameter.

    • Nilai code_challenge_method parameter tidakS256.

    Berikut ini adalah respons terhadap permintaan contoh dengan pemformatan yang salah.

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request

  • Jika klien meminta code atau token masukresponse_type, tetapi tidak memiliki izin untuk permintaan ini, server otorisasi Amazon Cognito kembali unauthorized_client ke klienredirect_uri, sebagai berikut:

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=unauthorized_client

  • Jika klien meminta cakupan yang tidak diketahui, cacat, atau tidak valid, server otorisasi Amazon Cognito kembali invalid_scope ke klienredirect_uri, sebagai berikut: 

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_scope

  • Jika ada kesalahan tak terduga di server, server otentikasi kembali server_error ke klienredirect_uri. Karena kesalahan HTTP 500 tidak dikirim ke klien, kesalahan tidak ditampilkan di browser pengguna. Server otorisasi mengembalikan kesalahan berikut.

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=server_error

  • Saat Amazon Cognito melakukan otentikasi melalui federasi ke pihak ketiga IdPs, Amazon Cognito mungkin mengalami masalah koneksi, seperti berikut ini:

    • Jika batas waktu koneksi terjadi saat meminta token dari IdP, server otentikasi mengalihkan kesalahan ke klien redirect_uri sebagai berikut:

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Timeout+occurred+in+calling+IdP+token+endpoint

    • Jika batas waktu koneksi terjadi saat memanggil jwks_uri titik akhir untuk validasi token ID, server otentikasi akan mengalihkan dengan kesalahan ke klien redirect_uri sebagai berikut:

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=error_description=Timeout+in+calling+jwks+uri

  • Saat mengotentikasi dengan federasi ke pihak ketiga IdPs, penyedia dapat mengembalikan respons kesalahan. Hal ini dapat disebabkan oleh kesalahan konfigurasi atau alasan lain, seperti berikut ini:

    • Jika respons kesalahan diterima dari penyedia lain, server autentikasi mengalihkan kesalahan ke redirect_uri klien sebagai berikut:

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=[IdP name]+Error+-+[status code]+error getting token

    • Jika respons kesalahan diterima dari Google, server otentikasi mengalihkan kesalahan ke klien redirect_uri sebagai berikut: 

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Google+Error+-+[status code]+[Google-provided error code]

  • Ketika Amazon Cognito menemukan pengecualian komunikasi saat terhubung ke IdP eksternal, server otentikasi mengalihkan dengan kesalahan ke klien redirect_uri dengan salah satu pesan berikut:

    • HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Connection+reset
    • HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Read+timed+out