Memproses login pengguna dengan SAML

Dokumen ini menunjukkan cara menggunakan Identity Platform untuk memproses login pengguna dengan penyedia Security Assertion Markup Language (SAML) 2.0.

Sebelum memulai

1. Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

2. Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.

   Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

   Buka pemilih project

3. Pastikan penagihan telah diaktifkan untuk project Google Cloud Anda.

4. Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.

   Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

   Buka pemilih project

5. Pastikan penagihan telah diaktifkan untuk project Google Cloud Anda.

6. Aktifkan Identity Platform, dan tambahkan SDK Klien ke aplikasi Anda. Lihat Panduan Memulai untuk mempelajari caranya.

Mengonfigurasi penyedia

1. Buka halaman Identity Provider di Konsol Google Cloud.
   Buka halaman Penyedia Identitas
   

2. Klik Add a Provider, lalu pilih SAML dari daftar.

3. Masukkan detail berikut:

   1. Nama penyedia. Nama ini dapat sama dengan ID penyedia, atau nama kustom. Jika Anda memasukkan nama kustom, klik Edit di samping ID Penyedia untuk menentukan ID (yang harus diawali dengan saml.).

   2. ID Entitas penyedia.

   3. URL SSO SAML penyedia.

   4. Sertifikat yang digunakan untuk penandatanganan token pada penyedia. Pastikan untuk menyertakan string awal dan akhir. Contoh:

      -----BEGIN CERTIFICATE-----
      MIICajCCAdOgAwIBAgIBADANBgkqhkiG9w0BAQ0FADBSMQswCQYDVQQGEwJ1czEL
      ...
      LEzc1JwEGQQVDYQCwsQMSBDAF0QAB0w9GikhqkgBNADABIgABIwAgOdACCjaCIIM
      -----END CERTIFICATE-----
      

4. Di bagian Service provider, masukkan ID Entitas aplikasi Anda. ID ini biasanya adalah URL aplikasi Anda. Di penyedia identitas SAML, hal ini disebut sebagai audience.

5. Tambahkan aplikasi Anda ke daftar Authorized Domains. Misalnya, jika URL login aplikasi Anda adalah https://example.com/login, tambahkan example.com.

6. Jika perlu, sesuaikan URL callback untuk aplikasi Anda. URL ini biasanya disebut URL Assertion Consumer Service (ACS) oleh penyedia identitas SAML.

   Penggunaan URL callback default akan mengurangi kerumitan validasi respons SAML. Jika Anda menyesuaikan alur ini, pastikan URL callback Identity Platform untuk project Anda dikonfigurasi di penyedia identitas SAML. Nama ini biasanya terlihat seperti https://[PROJECT-ID].firebaseapp.com/__/auth/handler. Baca bagian Menyesuaikan pengendali autentikasi untuk mempelajari lebih lanjut.

7. Klik Save.

Elemen wajib penyedia

Identity Platform mengharapkan elemen <saml:Subject> dan <saml:NameID> dalam respons dari penyedia. Jika Anda tidak menetapkan nilai untuk elemen tersebut saat mengonfigurasi penyedia, pernyataan SAML akan gagal.

Permintaan penandatanganan

Anda dapat meningkatkan keamanan permintaan autentikasi dengan menandatanganinya.

Untuk menandatangani permintaan, pertama-tama aktifkan permintaan bertanda tangan untuk penyedia identitas Anda dengan memanggil inboundSamlConfigs.patch(), dan menetapkan idp_config.sign_request ke true:

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

• project-id: ID untuk project Google Cloud
• provider-id: ID penyedia SAML

Metode HTTP dan URL:

PATCH https://identitytoolkit.googleapis.com/admin/v2/projects/project-id/inboundSamlConfigs/provider-id?updateMask=idpConfig.signRequest

Meminta isi JSON:

{
  "idp_config": {
    "sign_request": true
  }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://identitytoolkit.googleapis.com/admin/v2/projects/project-id/inboundSamlConfigs/provider-id?updateMask=idpConfig.signRequest"

PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://identitytoolkit.googleapis.com/admin/v2/projects/project-id/inboundSamlConfigs/provider-id?updateMask=idpConfig.signRequest" | Select-Object -Expand Content

APIs Explorer (browser)

Salin isi permintaan dan buka halaman referensi metode. Panel APIs Explorer akan terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Tempelkan isi permintaan di alat ini, lengkapi kolom wajib lainnya, lalu klik Jalankan.

 

Anda harus menggunakan REST API untuk mengaktifkan permintaan yang ditandatangani. Penggunaan konsol Google Cloud atau Google Cloud CLI tidak didukung.

Responsnya adalah objek InboundSamlConfig, yang menyertakan array SpCertificate. Konfigurasikan nilai sertifikat X509 dengan penyedia identitas SAML agar Anda dapat memvalidasi tanda tangan permintaan Anda.

Pengguna sedang login

Saat Anda memproses login pengguna, Client SDK akan menangani handshake autentikasi, lalu menampilkan token ID yang berisi atribut SAML di payload-nya. Untuk memproses login pengguna dan mendapatkan atribut dari penyedia SAML:

1. Buat instance SAMLAuthProvider dengan ID penyedia yang Anda konfigurasi di bagian sebelumnya. ID penyedia harus diawali dengan saml..

   Web versi 9

   Pelajari lebih lanjut Web API modular yang dapat di-tree-shaking dan upgrade dari API namespace.

   import { SAMLAuthProvider } from "firebase/auth";
   
   const provider = new SAMLAuthProvider("saml.myProvider");
   auth_saml_provider_create.js

   Web versi 8

   const provider = new firebase.auth.SAMLAuthProvider('saml.myProvider');
   saml.js

2. Mulai alur login. Anda dapat memilih untuk menggunakan pop-up atau pengalihan.

   Pop-up

   Web versi 9

   Pelajari lebih lanjut Web API modular yang dapat di-tree-shaking dan upgrade dari API namespace.

   import { SAMLAuthProvider } from "firebase/auth";
   
   const provider = new SAMLAuthProvider("saml.myProvider");
   auth_saml_provider_create.js

   Web versi 8

   const provider = new firebase.auth.SAMLAuthProvider('saml.myProvider');
   saml.js

   Pengalihan

   Untuk mengalihkan ke halaman login, panggil signInWithRedirect():

   Web versi 9

   Pelajari lebih lanjut Web API modular yang dapat di-tree-shaking dan upgrade dari API namespace.

   import { getAuth, signInWithRedirect } from "firebase/auth";
   
   const auth = getAuth();
   signInWithRedirect(auth, provider);
   auth_saml_signin_redirect.js

   Web versi 8

   firebase.auth().signInWithRedirect(provider);
   saml.js

   Lalu, panggil getRedirectResult() untuk mendapatkan hasil saat pengguna kembali ke aplikasi Anda:

   Web versi 9

   Pelajari lebih lanjut Web API modular yang dapat di-tree-shaking dan upgrade dari API namespace.

   import { getAuth, getRedirectResult, SAMLAuthProvider } from "firebase/auth";
   
   const auth = getAuth();
   getRedirectResult(auth)
     .then((result) => {
       // User is signed in.
       // Provider data available from the result.user.getIdToken()
       // or from result.user.providerData
     })
     .catch((error) => {
       // Handle Errors here.
       const errorCode = error.code;
       const errorMessage = error.message;
       // The email of the user's account used.
       const email = error.customData.email;
       // The AuthCredential type that was used.
       const credential = SAMLAuthProvider.credentialFromError(error);
       // Handle / display error.
       // ...
     });
   auth_saml_signin_redirect_result.js

   Web versi 8

   firebase.auth().getRedirectResult()
     .then((result) => {
       // User is signed in.
       // Provider data available in result.additionalUserInfo.profile,
       // or from the user's ID token obtained from result.user.getIdToken()
       // as an object in the firebase.sign_in_attributes custom claim
       // This is also available from result.user.getIdTokenResult()
       // idTokenResult.claims.firebase.sign_in_attributes.
     }).catch((error) => {
       // Handle / display error.
       // ...
     });
   saml.js

3. Ambil atribut pengguna yang terkait dengan penyedia SAML dari token ID menggunakan klaim firebase.sign_in_attributes. Pastikan untuk memverifikasi token ID menggunakan Admin SDK saat Anda mengirimkannya ke server.

   Token ID menyertakan alamat email pengguna hanya jika alamat tersebut diberikan dalam atribut NameID pernyataan SAML dari penyedia identitas:

   <Subject>
     <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">[e-mail]</NameID>
   </Subject>
   

   Ini diisi di token ID yang dikeluarkan Firebase dan di objek UserInfo.

Saat ini, hanya alur SAML yang dimulai penyedia layanan dari Client SDK yang didukung.

Menautkan akun pengguna

Jika pengguna telah login ke aplikasi Anda menggunakan metode lain (seperti email/sandi), Anda dapat menautkan akun mereka yang sudah ada ke penyedia SAML menggunakan linkWithPopup() atau linkWithRedirect(): Misalnya, kita dapat menautkan dengan Akun Google:

Web versi 9

Pelajari lebih lanjut Web API modular yang dapat di-tree-shaking dan upgrade dari API namespace.

import { getAuth, linkWithPopup, GoogleAuthProvider } from "firebase/auth";
const provider = new GoogleAuthProvider();

const auth = getAuth();
linkWithPopup(auth.currentUser, provider).then((result) => {
  // Accounts successfully linked.
  const credential = GoogleAuthProvider.credentialFromResult(result);
  const user = result.user;
  // ...
}).catch((error) => {
  // Handle Errors here.
  // ...
});
auth_link_with_popup.js

Web versi 8

auth.currentUser.linkWithPopup(provider).then((result) => {
  // Accounts successfully linked.
  var credential = result.credential;
  var user = result.user;
  // ...
}).catch((error) => {
  // Handle Errors here.
  // ...
});
link-multiple-accounts.js

Langkah selanjutnya

• Membuat pengguna login dengan OIDC
• Menampilkan domain kustom selama login
• Mengelola penyedia OIDC dan SAML secara terprogram