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. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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. Make sure that billing is enabled for your Google Cloud project.

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. Make sure that billing is enabled for your Google Cloud project.

6. Aktifkan Identity Platform, dan tambahkan SDK klien ke aplikasi Anda. Lihat Mulai Cepat untuk mempelajari caranya.

Mengonfigurasi penyedia

1. Buka halaman Penyedia Identitas di konsol Google Cloud.
   Buka halaman Penyedia Identitas
   

2. Klik Tambahkan Penyedia, 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 di penyedia. Pastikan untuk menyertakan string awal dan akhir. Contoh:

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

4. Di bagian Penyedia layanan, masukkan ID Entitas aplikasi Anda. Ini biasanya URL aplikasi Anda. Di penyedia identitas SAML Anda, hal ini disebut sebagai audiens.

5. Tambahkan aplikasi Anda ke daftar Domain yang Diizinkan. 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.

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

7. Klik Simpan.

Elemen yang diperlukan penyedia

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

Menandatangani permintaan

Anda dapat meningkatkan keamanan permintaan autentikasi dengan menandatanganinya.

Untuk menandatangani permintaan, aktifkan terlebih dahulu permintaan yang ditandatangani 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 gcloud CLI dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login , atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI . Anda dapat memeriksa akun yang saat ini aktif 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 gcloud CLI dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login . Anda dapat memeriksa akun yang saat ini aktif 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

API Explorer (browser)

Salin isi permintaan dan buka halaman referensi metode. Panel API Explorer terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Tempelkan isi permintaan di alat ini, lengkapi kolom lainnya yang wajib diisi, 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 mencakup array SpCertificate. Konfigurasikan nilai sertifikat X509 dengan penyedia identitas SAML Anda agar dapat memvalidasi tanda tangan permintaan Anda.

Pengguna sedang login

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

1. Buat instance SAMLAuthProvider dengan ID penyedia yang Anda konfigurasikan 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 { getAuth, signInWithPopup, SAMLAuthProvider } from "firebase/auth";
   
   const auth = getAuth();
   signInWithPopup(auth, provider)
     .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_popup.js

   Web versi 8

   firebase.auth().signInWithPopup(provider)
     .then((result) => {
       // User is signed in.
       // Identity 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

   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

   Kemudian, 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 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 diterbitkan Firebase dan di objek UserInfo.

Saat ini, hanya alur SAML yang dimulai oleh penyedia layanan dari SDK klien 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

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