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 memulai identitas eksternal, dan tidak mengharuskan Anda menulis kode apa pun.

Anda juga dapat membuat halaman login sendiri. Membuat halaman sendiri lebih sulit, tetapi meningkatkan kontrol 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, lalu pilih opsi Buat halaman login untuk saya selama penyiapan. Dengan demikian, Cloud Run dan FirebaseUI dapat membuat halaman login untuk Anda.
Pastikan akun layanan yang digunakan oleh Cloud Run, PROJECT_NUMBER-compute@developer.gserviceaccount.com, memiliki peran yang telah ditetapkan berikut:
- roles/identitytoolkit.viewer
- roles/iap.settingsAdmin
- roles/compute.networkViewer

Menyetel URL alihan halaman yang dihosting

Halaman login yang dihosting menggunakan domainnya sendiri sebagai domain Firebase auth untuk memastikan login melalui pengalihan berfungsi dengan benar di semua lingkungan. Anda harus menambahkan URL halaman yang dihosting sebagai URL alihan resmi pada konfigurasi penyedia.

Untuk menambahkan URL halaman login yang dihosting sebagai URL alihan yang diotorisasi, lakukan hal berikut:

Salin Login URL setelah memilih aplikasi Anda.
Di Konsol Google Cloud, buka halaman Kredensial.

Buka Credentials
Tambahkan LOGIN_URL/__/auth/handler sebagai salah satu URI pengalihan yang diberi otorisasi untuk klien OAuth 2.0 aplikasi Anda. Pilih client ID dan kunci rahasia OAuth yang sama dengan yang Anda gunakan saat mengonfigurasi penyedia.
Jika aplikasi Anda menggunakan penyedia SAML dan OIDC lain, tambahkan LOGIN_URL/__/auth/handler sebagai URI pengalihan resmi atau URL ACS.

Atau, Anda dapat menggunakan PROJECT_ID.firebaseapp.com dan bukan LOGIN_URL/__/auth/handler sebagai domain autentikasi dengan menyesuaikan halaman login menggunakan alur login pop-up.

Untuk menerapkan alur login pop-up di halaman Anda, lakukan hal berikut:

Klik Sesuaikan Halaman.
Dalam file konfigurasi berformat JSON, setel authDomain ke PROJECT_ID.firebaseapp.com dan signInFlow ke popup.
Untuk menyimpan konfigurasi, klik Simpan.

Ganti kode berikut:

LOGIN_URL: domain halaman login Anda yang dihosting
PROJECT_ID: project ID Firebase

Berikut adalah contoh konfigurasi alur login pop-up:

{
  "AIzaSyC5DtmRUR...": {
    "authDomain": "example.firebaseapp.com",
    "displayMode": "optionFirst",
    ...
    ...
    "tenants": {
      "tenant-a-id": {
        "fullLabel": "Company A Portal",
        "displayName": "Company A",
        ...
        ...
        "signInFlow": "popup",
        ...
        ...
      }
    }
  }
}

Untuk informasi selengkapnya tentang praktik terbaik pengalihan dan partisi penyimpanan, lihat Praktik terbaik untuk menggunakan signInWithRedirect di browser yang memblokir akses penyimpanan pihak ketiga.

Menguji halaman login

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

Buka resource yang dilindungi oleh IAP. Anda akan otomatis dialihkan ke halaman login.
Pilih tenant dan penyedia untuk login. Jika tidak melihat tenant atau penyedia tercantum, pastikan Anda telah mengonfigurasinya menggunakan Identity Platform.
Login dengan kredensial Anda.

Anda akan dialihkan ke resource yang dilindungi.

Menyesuaikan halaman login

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

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

Bagian berikut menjelaskan cara mengakses dan mengupdate 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.

Buka halaman Identity Platform Provider di Google Cloud Console.

Buka halaman Penyedia Identitas Platform
Klik Add a Provider.
Pilih Google dari daftar penyedia.
Konfigurasikan Client ID Web dan Rahasia Klien Web:
1. Di tab terpisah, buka halaman IAP.
  
  Buka halaman IAP
2. Luaskan menu View more untuk resource Anda, lalu klik Edit OAuth Client.
3. Salin kolom Client ID dan Client secret ke dalam konfigurasi penyedia Google untuk Identity Platform.
4. Tambahkan URL alihan Identity Platform ke daftar URI Pengalihan yang Diotorisasi untuk klien OAuth. URL diformat seperti https://PROJECT_ID.firebaseapp.com/__/auth/handler.
Klik Save di kedua halaman.

Login ke panel admin

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

Buka halaman IAP di Konsol Google Cloud.

Buka halaman IAP
Pilih referensi dari daftar.
Luncurkan URL yang tercantum di bagian Customize page di panel info. Class tersebut akan terlihat seperti https://servicename-xyz-uc.a.run.app/admin.

Catatan: Jika melihat peringatan yang menunjukkan bahwa aplikasi belum diverifikasi, Anda dapat mengabaikannya untuk tujuan pengembangan. Lihat Pengecualian untuk persyaratan verifikasi untuk mempelajari lebih lanjut.
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. 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",
        "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,
        "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,
        "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 menggantikan 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
Memperbarui 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 antar-versi di GitHub.

Anda bisa mendapatkan versi 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:

Buka halaman Cloud Run di Konsol Google Cloud.

Buka halaman Cloud Run
Pilih instance yang menghosting halaman login.
Klik Edit & Deploy New revision.
Jika ingin, tentukan setelan lanjutan untuk revisi, atau tambahkan variabel lingkungan dengan mengklik tab Variables & Secrets.
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 ke dalam log. Data sensitif tidak akan dicatat. 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 sebelum menetapkan variabel ini dapat membantu meminimalkan error sintaksis.
`GCS_BUCKET_NAME`	String yang menggantikan bucket Cloud Storage default yang digunakan untuk menyimpan konfigurasi JSON. Filenya bernama `config.json`, dan lokasi default-nya 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` atau tidak. Diaktifkan (`1`) secara default.

Anda harus men-deploy revisi baru instance Cloud Run setelah memperbarui variabel sebelum perubahannya berlaku. 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:

Ikuti langkah-langkah dalam artikel Memetakan domain kustom untuk menetapkan domain kustom untuk instance Cloud Run.
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 Login URL.
4. Pilih Use an existing host 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:

Ikuti langkah-langkah dalam artikel ini untuk men-deploy halaman autentikasi bagi resource pertama yang dilindungi oleh IAP.
Aktifkan IAP untuk resource kedua. Saat diminta untuk menentukan halaman login, pilih I'll provide my own, dan masukkan URL layanan Cloud Run sebagai URL.
Deploy ulang layanan Cloud Run.

Pemecahan masalah

Halaman login tidak berfungsi di browser yang menonaktifkan cookie pihak ketiga atau menerapkan partisi penyimpanan.

Untuk mengatasi masalah ini, lakukan langkah berikut:

Deploy ulang halaman login Anda. Versi terbaru halaman login menggunakan domain halaman login sebagai authDomain.
Sesuaikan konfigurasi halaman login untuk memastikan bahwa authDomain ditetapkan sebagai URL halaman login untuk aplikasi yang dilindungi IAP.
```
{
  "AIzaSyC5DtmRUR...": {
    "authDomain": "LOGIN_URL",
    ...
  }
}
```

Langkah selanjutnya

Membuat UI autentikasi dengan FirebaseUI.
Membuat UI autentikasi kustom.
Dapatkan pemahaman lebih mendalam tentang cara kerja identitas eksternal dengan IAP.