Memproses login pengguna dengan SAML

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

Sebelum memulai

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.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Aktifkan Identity Platform, dan tambahkan SDK klien ke aplikasi Anda. Untuk mengetahui informasi dan petunjuk selengkapnya, lihat panduan memulai Login pengguna dengan email menggunakan Identity Platform.

Mengonfigurasi penyedia

1. Di konsol Google Cloud , buka halaman Identity Platform > Penyedia identitas.
   Buka Penyedia identitas
   

2. Klik Tambahkan Penyedia, lalu pilih SAML dari daftar.

3. Masukkan detail berikut:

   1. Nama penyedia. Nilai ini bisa sama dengan ID penyedia atau nama kustom. Jika Anda memasukkan nama kustom, klik Edit di samping ID Penyedia untuk menentukan ID (yang harus dimulai 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. Biasanya, ID ini adalah URL aplikasi Anda. Di penyedia identitas SAML Anda, ini disebut sebagai audiens.

5. Di panel samping Project settings, klik Add Domain, lalu tambahkan domain aplikasi Anda. Misalnya, jika URL login aplikasi Anda adalah https://example.com/login, tambahkan example.com.

6. Untuk menyelesaikan penyiapan, lakukan salah satu hal berikut:

   • Salin URL callback otorisasi default dari kolom Callback otorisasi (URL) dan tambahkan ke konfigurasi aplikasi SAML Anda.

     Menggunakan URL callback otorisasi default akan mengurangi kompleksitas validasi respons SAML.

   • Tambahkan URL callback otorisasi yang disesuaikan ke konfigurasi aplikasi SAML Anda—misalnya, https://PROJECT-ID.firebaseapp.com/__/auth/handler.

7. Di bagian Konfigurasi aplikasi Anda, klik Detail Penyiapan. Salin cuplikan ke dalam kode aplikasi Anda untuk melakukan inisialisasi SDK klien Identity Platform.

8. Klik Simpan.

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

Permintaan tanda tangan

Anda dapat meningkatkan keamanan permintaan autentikasi dengan menandatanganinya.

Untuk menandatangani permintaan, aktifkan terlebih dahulu permintaan bertanda tangan untuk penyedia identitas Anda dengan memanggil inboundSamlConfigs.patch() dan menyetel idp_config.sign_request ke true:

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

• project-id: ID untuk Google Cloud project
• 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 menggunakan 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 menggunakan 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

APIs 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 bertanda tangan; penggunaan konsolGoogle Cloud atau Google Cloud CLI tidak didukung.

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

Login pengguna

Saat Anda membuat pengguna login, Client SDK 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 konfigurasi di bagian sebelumnya. ID penyedia harus diawali dengan saml.

   Web versi 9

   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

   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

   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 hasilnya saat pengguna kembali ke aplikasi Anda:

   Web versi 9

   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>
   

   Nilai ini diisi dalam token ID yang dikeluarkan Firebase dan dalam objek UserInfo.

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 yang sudah ada ke penyedia SAML menggunakan linkWithPopup() atau linkWithRedirect().

Cuplikan kode berikut menunjukkan cara menautkan Akun Google pengguna ke penyedia SAML:

Web versi 9

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 berikutnya

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