Menghosting halaman login dengan Cloud Run

Untuk menggunakan identitas eksternal dengan Identity-Aware Proxy (IAP), aplikasi Anda memerlukan halaman login. IAP akan mengalihkan pengguna ke halaman ini untuk melakukan autentikasi sebelum mereka dapat mengakses resource aman.

Dokumen ini menunjukkan cara men-deploy dan menyesuaikan halaman login bawaan menggunakan Cloud Run. Ini adalah cara tercepat untuk memulai dengan identitas eksternal, dan Anda tidak perlu menulis kode apa pun.

Anda juga dapat membuat halaman login sendiri. Membuat halaman sendiri lebih sulit, tetapi meningkatkan kontrol Anda atas alur autentikasi dan pengalaman pengguna. Lihat artikel Membuat halaman login dengan FirebaseUI dan Membuat halaman login kustom untuk mempelajari lebih lanjut.

Batasan halaman login

Anda tidak dapat menggunakan halaman login bawaan jika perlindungan enumerasi email diaktifkan di project Anda.

Jika project Anda mengaktifkan perlindungan enumerasi email, nonaktifkan email-enumeration-protection sebelum melanjutkan dengan prosedur dalam dokumen ini.

Sebelum memulai

  • Aktifkan Compute Engine API.

    Mengaktifkan Compute Engine API

  • Aktifkan identitas eksternal, lalu pilih opsi Buat halaman login untuk saya selama penyiapan. Tindakan ini memungkinkan Cloud Run dan FirebaseUI membuat halaman login untuk Anda.

  • Pastikan akun layanan yang digunakan oleh Cloud Run, PROJECT_NUMBER-compute@developer.gserviceaccount.com, memiliki peran standar berikut:

    • roles/identitytoolkit.viewer
    • roles/iap.settingsAdmin
    • roles/compute.networkViewer

Menetapkan URI Pengalihan yang Sah untuk penyedia Identity Platform

Jika Anda menggunakan penyedia Identity Platform yang memerlukan pengalihan login (pengalihan ke halaman login IdP eksternal). Anda harus menambahkan URL halaman login yang dihosting sebagai URL alihan yang diotorisasi dalam konfigurasi penyedia.

Misalnya, untuk penyedia Google, Anda perlu melakukan hal berikut:

  1. Salin Login URL setelah memilih aplikasi yang diamankan oleh IAP.

  2. Di Konsol Google Cloud, buka halaman Kredensial.

    Buka Kredensial

  3. Tambahkan LOGIN_URL/__/auth/handler sebagai salah satu URI pengalihan yang diotorisasi untuk klien OAuth 2.0 aplikasi Anda. Pilih client ID OAuth yang sama dengan yang Anda gunakan saat mengonfigurasi penyedia Google.

Untuk penyedia SAML dan OIDC lainnya, lakukan hal yang sama dengan menambahkan LOGIN_URL/__/auth/handler sebagai URI alihan yang diotorisasi atau URL ACS.

Menguji halaman login

Halaman login awal yang dibuat oleh IAP berfungsi penuh. Untuk mengujinya:

  1. Buka resource yang dilindungi oleh IAP. Anda akan otomatis dialihkan ke halaman login.

  2. Pilih tenant dan penyedia yang akan digunakan untuk login. Jika Anda tidak melihat tenant atau penyedia yang tercantum, pastikan Anda telah mengonfigurasinya menggunakan Identity Platform.

  3. Login dengan kredensial Anda.

Anda akan dialihkan ke resource yang dilindungi.

Menyesuaikan halaman login

Anda dapat menyesuaikan halaman login menggunakan file konfigurasi JSON. Beberapa opsi meliputi:

  • Menambahkan header dan logo ke halaman login.
  • Menentukan tenant dan penyedia yang tersedia.
  • Menyesuaikan ikon dan gaya setiap tombol tenant dan penyedia.
  • Menambahkan link ke kebijakan privasi dan persyaratan layanan aplikasi Anda.

Bagian berikut menjelaskan cara mengakses dan memperbarui file konfigurasi JSON.

Mendapatkan token akses

Untuk mengelola halaman login, Anda memerlukan token akses Google. Cara termudah untuk mendapatkannya adalah dengan mengaktifkan Google sebagai penyedia untuk Identity Platform. Jika aplikasi Anda sudah menggunakan Google sebagai penyedia identitas, Anda dapat melewati bagian ini.

  1. Buka halaman Identity Platform Providers di konsol Google Cloud.

    Buka halaman Penyedia Identity Platform

  2. Klik Tambahkan Penyedia.

  3. Pilih Google dari daftar penyedia.

  4. Konfigurasikan Client ID Web dan Rahasia Klien Web:

    1. Di Konsol Google Cloud, buka halaman Kredensial.

      Buka Kredensial

    2. Gunakan klien OAuth 2.0 yang ada atau buat klien baru. Konfigurasikan Client ID dan Client secret ke Client ID Web dan Rahasia Klien Web. Tambahkan LOGIN_URL/__/auth/handler sebagai salah satu URI pengalihan yang diotorisasi untuk klien OAuth 2.0. LOGIN_URL adalah URL Login yang dibuat oleh IAP setelah memilih opsi Buat halaman login untuk saya. IAP dapat ditemukan di halaman IAP di konsol Google Cloud, dengan memilih resource yang diamankan IAP.

  5. Klik Simpan di kedua halaman.

Login ke panel admin

Konfigurasi JSON untuk halaman login yang dihosting oleh Cloud Run di panel LOGIN_URL/admin. Langkah-langkah berikut menunjukkan cara mengakses panel. Perhatikan bahwa Anda memerlukan peran Storage Admin (roles/storage.admin).

  1. Buka halaman IAP di konsol Google Cloud.

    Buka halaman IAP

  2. Pilih resource Anda dari daftar.

  3. Luncurkan URL yang tercantum di bagian Sesuaikan halaman di panel info. Tampilannya akan terlihat seperti https://servicename-xyz-uc.a.run.app/admin.

  4. Login dengan Akun Google yang sama dengan yang Anda gunakan untuk mengonfigurasi IAP. Editor teks yang berisi file konfigurasi JSON akan muncul.

Mengubah konfigurasi

Skema konfigurasi untuk halaman login didasarkan pada FirebaseUI, dan mewarisi banyak propertinya. Anda dapat menggunakan PROJECT_ID.firebaseapp.com, bukan LOGIN_URL yang dibuat IAP sebagai authDomain default.

Jika Anda ingin menggunakan PROJECT_ID.firebaseapp.com sebagai authDomain, ubah signInFlow sebagai popup untuk menghindari masalah akses penyimpanan pihak ketiga di browser utama(Lihat Praktik terbaik untuk menggunakan signInWithRedirect di browser yang memblokir akses penyimpanan pihak ketiga). Selain itu, ikuti petunjuk di Menetapkan URI Pengalihan yang Diberi Otorisasi untuk Penyedia Identity Platform untuk menambahkan PROJECT_ID.firebaseapp.com/__/auth/handler sebagai salah satu URI pengalihan yang diberi otorisasi atau URL ACS untuk penyedia Identity Platform yang akan digunakan pengguna untuk login.

Kode berikut menunjukkan contoh konfigurasi dengan tiga tenant:

{
  "AIzaSyC5DtmRUR...": {
    "authDomain": "awesomeco.firebaseapp.com",
    "displayMode": "optionFirst",
    "selectTenantUiTitle": "Awesome Company Portal",
    "selectTenantUiLogo": "https://awesome.com/abcd/logo.png",
    "styleUrl": "https://awesome.com/abcd/overrides/stylesheet.css",
    "tosUrl": "https://awesome.com/abcd/tos.html",
    "privacyPolicyUrl": "https://awesome.com/abcd/privacypolicy.html",
    "tenants": {
      "tenant-a-id": {
        "fullLabel": "Company A Portal",
        "displayName": "Company A",
        "iconUrl": "https://companya.com/img/icon.png",
        "logoUrl": "https://companya.com/img/logo.png",
        "buttonColor": "#007bff",
        "signInFlow": "popup",
        "signInOptions": [
          {
            "provider": "password",
            "requireDisplayName": false,
            "disableSignUp": {
              "status": true,
              "adminEmail": "admin@example.com",
              "helpLink": "https://www.example.com/trouble_signing_in"
            }
          },
          "facebook.com",
          "google.com",
          "microsoft.com",
          {
            "provider": "saml.okta-cicp-app",
            "providerName": "Corp Account",
            "fullLabel": "Employee Corporate Login",
            "buttonColor": "#ff0000",
            "iconUrl": "https://companya.com/abcd/icon-1.png"
          },
          {
            "provider": "oidc.okta-oidc",
            "providerName": "Contractor Account",
            "fullLabel": "Contractor Account Portal",
            "buttonColor": "#00ff00",
            "iconUrl": "https://companya.com/abcd/icon-2.png"
          }
        ],
        "tosUrl": "https://companya.com/abcd/tos.html",
        "privacyPolicyUrl": "https://companya.com/abcd/privacypolicy.html"
      },
      "tenant-b-id": {
        "fullLabel": "Company B Portal",
        "displayName": "Company B",
        "iconUrl": "https://companyb.com/img/icon.png",
        "logoUrl": "https://companyb.com/img/logo.png",
        "buttonColor": "#007bff",
        "immediateFederatedRedirect": true,
        "signInFlow": "popup",
        "signInOptions": [
          {
            "provider": "saml.okta-bla-app",
            "providerName": "Corp Account",
            "buttonColor": "#0000ff",
            "iconUrl": "https://companyb.com/abcd/icon.png"
          }
        ],
        "tosUrl": "https://companyb.com/abcd/tos.html",
        "privacyPolicyUrl": "https://companyb.com/abcd/privacypolicy.html"
      },
      "tenant-c-id": {
        "fullLabel": "Company C Portal",
        "displayName": "Company C",
        "iconUrl": "https://companyc.com/img/icon.png",
        "logoUrl": "https://companyc.com/img/logo.png",
        "buttonColor": "#007bff",
        "immediateFederatedRedirect": true,
        "signInFlow": "popup",
        "signInOptions": [
          {
            "provider": "password",
            "requireDisplayName": false
          },
          {
            "provider": "google.com",
            "scopes": ["scope1", "scope2", "https://example.com/scope3"],
            "loginHintKey": "login_hint",
            "customParameters": {
              "prompt": "consent",
            },
          }
        ],
        "tosUrl": "https://companyc.com/abcd/tos.html",
        "privacyPolicyUrl": "https://companyc.com/abcd/privacypolicy.html",
        "adminRestrictedOperation": {
          "status": true,
          "adminEmail": "admin@example.com",
          "helpLink": "https://www.example.com/trouble_signing_in"
        }
      },
    }
  }
}

Untuk mengetahui daftar lengkap properti yang tersedia, lihat dokumentasi referensi.

Mengganti CSS

Anda dapat menggunakan properti styleUrl untuk menentukan file CSS kustom. Gaya dalam file ini akan mengganti CSS default. File harus dapat diakses secara publik menggunakan HTTPS (misalnya, dihosting di bucket Cloud Storage).

Contoh berikut menunjukkan penggantian CSS default:

/** Change header title style. */
.heading-center {
  color: #7181a5;
  font-family: Arial, Helvetica, sans-serif;
  font-size: 20px;
  font-weight: bold;
}

/** Use round edged borders for container. */
.main-container {
  border-radius: 5px;
}

/** Change page background color. */
body {
  background-color: #f8f9fa;
}

Men-deploy ulang instance Cloud Run

Dalam beberapa kasus, Anda mungkin ingin men-deploy ulang instance Cloud Run yang menghosting halaman login. Contoh skenario mencakup:

  • Menambahkan, mengubah, atau menghapus penyedia identitas
  • Mengubah konfigurasi tenant
  • Menyetel variabel lingkungan
  • Mengupdate image container ke versi terbaru

Mengupdate dan men-deploy ulang image container secara rutin memastikan Anda memiliki perbaikan bug dan patch keamanan terbaru. Anda dapat melihat daftar perubahan antara versi di GitHub.

Anda bisa mendapatkan versi penampung yang di-deploy saat ini menggunakan endpoint /versionz. Contoh:

curl 'https://servicename-xyz-uc.a.run.app/versionz'

Untuk men-deploy ulang instance Cloud Run:

  1. Buka halaman Cloud Run di konsol Google Cloud.

    Buka halaman Cloud Run

  2. Pilih instance yang menghosting halaman login.

  3. Klik Edit & Deploy New Revision.

  4. Secara opsional, tentukan setelan lanjutan untuk revisi, atau tambahkan variabel lingkungan dengan mengklik tab Variables & Secrets.

  5. Klik Deploy.

Opsi lanjutan

Menyesuaikan halaman login secara terprogram

Selain menggunakan konsol /admin, Anda dapat mengupdate konfigurasi JSON secara terprogram.

Untuk mendapatkan konfigurasi saat ini, gunakan endpoint /get_admin_config. Contoh:

curl -H 'Authorization: Bearer [TOKEN]'
  'https://servicename-xyz-uc.a.run.app/get_admin_config'

Untuk memperbarui konfigurasi, gunakan /set_admin_config. Contoh:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' -H "Content-type: application/json"
  -d '[UPDATED-CONFIG]' 'https://servicename-xyz-uc.a.run.app/set_admin_config'

Kedua panggilan REST memerlukan cakupan https://www.googleapis.com/auth/devstorage.read_write, dan token OAuth yang valid harus dilampirkan ke header Authorization.

Menyetel variabel lingkungan

Anda dapat menetapkan variabel lingkungan pada instance Cloud Run untuk menyesuaikan setelan lanjutan. Tabel berikut mencantumkan variabel yang tersedia:

Variabel Deskripsi
DEBUG_CONSOLE Nilai boolean (0 atau 1) yang menunjukkan apakah akan mencatat semua error dan detail permintaan jaringan ke dalam log. Data sensitif tidak akan dicatat ke dalam log. Dinonaktifkan (0) secara default.
UI_CONFIG String yang berisi konfigurasi JSON untuk halaman login. Penggunaan variabel ini, bukan panel /admin, akan menghindari pembacaan dan penulisan ke Cloud Storage saat mengakses konfigurasi. Konfigurasi yang tidak valid akan diabaikan. Menggunakan panel /admin untuk memvalidasi JSON sebelum menetapkan variabel ini dapat membantu meminimalkan error sintaksis.
GCS_BUCKET_NAME String yang mengganti bucket Cloud Storage default yang digunakan untuk menyimpan konfigurasi JSON. File tersebut bernama config.json, dan lokasi defaultnya adalah gcip-iap-bucket-[CLOUD-RUN-SERVICE-NAME]-[PROJECT-NUMBER].
ALLOW_ADMIN Nilai boolean (0 atau 1) yang menunjukkan apakah akan mengizinkan akses ke panel konfigurasi /admin. Diaktifkan (1) secara default.

Anda harus men-deploy revisi baru instance Cloud Run setelah memperbarui variabel sebelum perubahan diterapkan. Untuk mempelajari variabel lingkungan lebih lanjut, lihat dokumentasi Cloud Run.

Menyesuaikan domain

Secara default, pengguna akan melihat URL instance Cloud Run saat login. Untuk menentukan domain kustom:

  1. Ikuti langkah-langkah di Memetakan domain kustom untuk menetapkan domain kustom untuk instance Cloud Run.

  2. Konfigurasikan IAP untuk menggunakan URL autentikasi baru:

    1. Buka halaman IAP di konsol Google Cloud.

      Buka halaman IAP

    2. Pilih resource yang dilindungi oleh IAP.

    3. Di panel samping, pilih ikon Edit di samping kolom URL Login.

    4. Pilih Gunakan halaman login terhosting yang sudah ada, lalu pilih domain Anda dari menu drop-down.

    5. Klik Simpan.

Menggunakan satu halaman login untuk beberapa resource IAP

Anda dapat melindungi beberapa resource IAP menggunakan halaman login yang sama. Hal ini mengurangi pekerjaan yang terkait dengan pengelolaan beberapa konfigurasi.

Untuk menggunakan kembali halaman login:

  1. Ikuti langkah-langkah dalam artikel ini untuk men-deploy halaman autentikasi untuk resource pertama yang dilindungi oleh IAP.

  2. Aktifkan IAP untuk resource kedua. Saat diminta untuk menentukan halaman login, pilih Saya akan memberikan halaman saya sendiri, lalu masukkan URL layanan Cloud Run sebagai URL.

  3. Deploy ulang layanan Cloud Run.

Pemecahan masalah

Cookie Pihak Ketiga dan Partisi Penyimpanan di Browser

Untuk browser yang menonaktifkan cookie pihak ketiga atau menerapkan partisi penyimpanan, halaman login atau halaman admin mungkin tidak berfungsi dengan benar. Untuk menyelesaikan masalah ini, lakukan tindakan berikut:

  1. Deploy ulang halaman login untuk menggunakan versi terbaru 1.0.1.

  2. Jika Anda menggunakan fitur Menyesuaikan halaman login, pastikan authDomain ditetapkan sebagai LOGIN_URL yang dibuat IAP. Atau, Anda dapat menetapkan authDomain sebagai PROJECT_ID.firebaseapp.com jika signInFlow ditetapkan sebagai popup.

    {
  "AIzaSyC5DtmRUR...": {
    "authDomain": "LOGIN_URL",
    ...
  }
}

    atau

    {
  "AIzaSyC5DtmRUR...": {
    "authDomain": "PROJECT_ID.firebaseapp.com",
    "tenants": {
      "tenant-a-id": {
        ...
        "signInFlow": "popup"
        ...
      }
    }
    ...
  }
}

Langkah selanjutnya