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 yang aman.

Dokumen ini menunjukkan cara men-deploy dan menyesuaikan halaman login bawaan menggunakan Cloud Run. Ini adalah cara tercepat untuk mulai menggunakan 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 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 project Anda mengaktifkan perlindungan enumerasi email.

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

Sebelum memulai

  • Aktifkan Compute Engine API.

    Aktifkan Compute Engine API

  • Aktifkan identitas eksternal, dan pilih opsi Create a sign-in page for me 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 bawaan berikut:

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

Menetapkan URI Pengalihan yang Diberi Otorisasi 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 terhosting sebagai URL pengalihan yang diberi otorisasi dalam konfigurasi penyedia Anda.

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

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

  2. Di Google Cloud konsol, buka halaman Credentials.

    Buka Kredensial

  3. Tambahkan LOGIN_URL/__/auth/handler sebagai salah satu URI pengalihan yang diberi otorisasi 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 pengalihan yang diberi otorisasi 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 untuk login. Jika Anda tidak melihat tenant atau penyedia yang tercantum, pastikan Anda telah mengonfigurasi salah satunya 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 mencakup:

  • 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 Google Cloud konsol.

    Buka halaman Penyedia Identity Platform

  2. Klik Add a Provider.

  3. Pilih Google dari daftar penyedia.

  4. Konfigurasi Web Client ID dan Web Client Secret:

    1. Di Google Cloud konsol, buka halaman Credentials.

      Buka Kredensial

    2. Gunakan klien OAuth 2.0 yang ada atau buat klien baru. Konfigurasi Client ID dan Client secret ke Web Client ID dan Web Client Secret. Tambahkan LOGIN_URL/__/auth/handler sebagai salah satu URI pengalihan yang diberi otorisasi untuk klien OAuth 2.0. LOGIN_URL adalah URL Login yang dibuat oleh IAP setelah memilih opsi Create a sign-in page for me. URL ini dapat ditemukan di halaman IAP di Google Cloud konsol, dengan memilih resource yang diamankan IAP.

  5. Klik Save 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 Admin Penyimpanan (roles/storage.admin).

  1. Buka halaman IAP di Google Cloud konsol.

    Buka halaman IAP

  2. Pilih resource Anda dari daftar.

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

  4. Login dengan Akun Google yang sama 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. Daripada menggunakan LOGIN_URL yang dibuat IAP sebagai authDomain default, Anda dapat menggunakan PROJECT_ID.firebaseapp.com.

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 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 tersebut harus dapat diakses secara publik menggunakan HTTPS (misalnya, dihosting di bucket Cloud Storage).

Contoh berikut menunjukkan cara mengganti 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: #e6eaf0;
}

Men-deploy ulang instance Cloud Run

Dalam beberapa kasus, Anda mungkin ingin men-deploy ulang instance Cloud Run yang menghosting halaman login. Skenario contoh 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 akan memastikan Anda memiliki perbaikan bug dan patch keamanan terbaru. Anda dapat melihat daftar perubahan antarversi di GitHub.

Anda dapat memperoleh versi image container 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 Google Cloud konsol.

    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 memperbarui 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. Data sensitif tidak akan di catat. Dinonaktifkan (0) secara default.
UI_CONFIG String yang berisi konfigurasi JSON untuk halaman login. Menggunakan 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 Anda 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 ini diberi nama 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 lebih lanjut tentang variabel lingkungan, lihat dokumentasi Cloud Run.

Menyesuaikan domain

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

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

  2. Konfigurasi IAP untuk menggunakan URL autentikasi baru:

    1. Buka halaman IAP di Google Cloud konsol.

      Buka halaman IAP

    2. Pilih resource yang dilindungi oleh IAP.

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

    4. Pilih Use an existing hosted sign-in page, lalu pilih domain Anda dari menu drop-down.

    5. Klik Save.

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 I'll provide my own, lalu masukkan URL layanan Cloud Run sebagai URL.

  3. Deploy ulang layanan Cloud Run.

Pemecahan masalah

Layanan tidak tersedia dengan halaman login terhosting

Saat menggunakan halaman login terhosting, Anda akan menerima error berikut:

Service unavailable

Kemudian, Anda tidak dapat mengakses halaman login.

Untuk mengatasi error ini, lakukan hal berikut:

  1. Pastikan bucket Cloud Storage default dalam format gcip-iap-bucket-CLOUD_RUN_SERVICE_NAME-PROJECT-NUMBER.

  2. Pastikan bucket Cloud Storage default ada dan berisi file bernama config.json.

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 baik. Untuk mengatasi masalah ini, lakukan hal berikut:

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

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

    Cuplikan berikut menunjukkan konfigurasi authDomain untuk halaman login kustom:

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

    Cuplikan berikut menjelaskan authDomain untuk halaman login popup:

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

Langkah berikutnya