Mengelola penyedia SAML dan OIDC secara terprogram

Dokumen ini menunjukkan cara menggunakan Identity Platform Admin SDK untuk mengelola konfigurasi penyedia Security Assertion Markup Language (SAML) 2.0 dan OpenID Connect (OIDC) secara terprogram.

Dengan Admin SDK, Anda dapat mengonfigurasi penyedia secara otomatis, melakukan operasi CRUD dasar, merotasi sertifikat, dan lainnya. Hal ini berguna ketika Anda memiliki sejumlah besar penyedia yang rumit untuk dikelola secara manual menggunakan Konsol Google Cloud.

Sebelum memulai

Bekerja sama dengan penyedia SAML

Membuat konfigurasi penyedia SAML

Anda harus menyediakan parameter berikut saat membuat konfigurasi penyedia SAML. Anda mungkin perlu membaca dokumentasi penyedia identitas untuk mengetahui detail tentang cara mendapatkan beberapa nilai.

Nama tampilan

Nama tampilan yang mudah digunakan untuk konfigurasi. Nama ini juga merupakan label penyedia di Konsol Google Cloud.

Diaktifkan

Apakah konfigurasi penyedia saat ini diaktifkan atau dinonaktifkan. Pengguna tidak dapat login dengan penyedia yang dinonaktifkan.

ID Penyedia

ID unik penyedia, dimulai dengan saml..

ID entitas penyedia identitas

ID entitas untuk penyedia.

URL SSO

URL SSO SAML untuk penyedia. URL harus valid.

Sertifikat X.509

Daftar sertifikat X.509 penyedia SAML, termasuk string -----BEGIN CERTIFICATE----- dan -----END CERTIFICATE----. ID ini digunakan untuk penandatanganan token pada penyedia identitas.

Ketika Identity Platform menerima respons SAML, ia akan memverifikasi tanda tangannya menggunakan sertifikat pada rekaman. Jika verifikasi gagal, respons akan ditolak. Anda harus memperbarui sertifikat ini saat kunci dirotasi. Pertimbangkan untuk mengupload beberapa sertifikat guna mencegah gangguan selama rotasi.

ID entitas pihak yang meneruskan

ID entitas pihak tepercaya (RP/SP) SAML. Ini biasanya adalah URL aplikasi. Di penyedia identitas SAML, ini disebut sebagai audience.

URL callback

URL yang akan menjadi tujuan saat autentikasi selesai. Penyedia SAML biasanya menyebutnya sebagai URL Assertion Consumer Service (ACS). Anda harus mendaftarkan URL ini ke penyedia SAML. URL tersebut akan terlihat seperti https://PROJECT-ID.firebaseapp.com/__/auth/handler, mirip dengan URL yang ditampilkan di Konsol Google Cloud. Untuk mempelajari lebih lanjut, lihat Memproses login pengguna dengan SAML.

Menggunakan URL callback default akan mengurangi kerumitan validasi respons SAML. Namun, Anda juga dapat memilih untuk menampilkan domain kustom. Dalam hal ini, pastikan URL callback Identity Platform untuk project Anda dikonfigurasi dengan benar menggunakan penyedia identitas SAML Anda. Biasanya akan terlihat seperti ini https://AUTH-DOMAIN/__/auth/handler.

Contoh berikut menunjukkan cara membuat konfigurasi penyedia SAML:

Node.js

const newConfig = {
  displayName: 'SAML provider name',
  enabled: true,
  providerId: 'saml.myProvider',
  idpEntityId: 'IDP_ENTITY_ID',
  ssoURL: 'https://example.com/saml/sso/1234/'
  x509Certificates: [
    '-----BEGIN CERTIFICATE-----\nCERT1...\n-----END CERTIFICATE-----',
    '-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----',
  ],
  rpEntityId: 'RP_ENTITY_ID',
  // Using the default callback URL.
  callbackURL: 'https://project-id.firebaseapp.com/__/auth/handler',
};
admin.auth().createProviderConfig(newConfig).then(() => {
  // Successful creation.
}).catch((error) => {
  // Handle error.
});

Go

newConfig := (&auth.SAMLProviderConfigToCreate{}).
	DisplayName("SAML provider name").
	Enabled(true).
	ID("saml.myProvider").
	IDPEntityID("IDP_ENTITY_ID").
	SSOURL("https://example.com/saml/sso/1234/").
	X509Certificates([]string{
		"-----BEGIN CERTIFICATE-----\nCERT1...\n-----END CERTIFICATE-----",
		"-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----",
	}).
	RPEntityID("RP_ENTITY_ID").
	CallbackURL("https://project-id.firebaseapp.com/__/auth/handler")
saml, err := client.CreateSAMLProviderConfig(ctx, newConfig)
if err != nil {
	log.Fatalf("error creating SAML provider: %v\n", err)
}

log.Printf("Created new SAML provider: %s", saml.ID)auth.go

Python

saml = auth.create_saml_provider_config(
    display_name='SAML provider name',
    enabled=True,
    provider_id='saml.myProvider',
    idp_entity_id='IDP_ENTITY_ID',
    sso_url='https://example.com/saml/sso/1234/',
    x509_certificates=[
        '-----BEGIN CERTIFICATE-----\nCERT1...\n-----END CERTIFICATE-----',
        '-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----',
    ],
    rp_entity_id='P_ENTITY_ID',
    callback_url='https://project-id.firebaseapp.com/__/auth/handler')

print('Created new SAML provider:', saml.provider_id)index.py

Java

SamlProviderConfig.CreateRequest request = new SamlProviderConfig.CreateRequest()
    .setDisplayName("SAML provider name")
    .setEnabled(true)
    .setProviderId("saml.myProvider")
    .setIdpEntityId("IDP_ENTITY_ID")
    .setSsoUrl("https://example.com/saml/sso/1234/")
    .addX509Certificate("-----BEGIN CERTIFICATE-----\nCERT1...\n-----END CERTIFICATE-----")
    .addX509Certificate("-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----")
    .setRpEntityId("RP_ENTITY_ID")
    .setCallbackUrl("https://project-id.firebaseapp.com/__/auth/handler");
SamlProviderConfig saml = FirebaseAuth.getInstance().createSamlProviderConfig(request);
System.out.println("Created new SAML provider: " + saml.getProviderId());FirebaseAuthSnippets.java

Setelah selesai, metode akan menampilkan objek SAMLAuthProviderConfig untuk konfigurasi yang baru dibuat.

Memperbarui konfigurasi penyedia SAML

Contoh berikut menunjukkan cara mengubah konfigurasi penyedia SAML. Anda dapat memperbarui kolom apa pun, kecuali ID penyedia.

Node.js

const updatedConfig = {
  x509Certificates: [
    '-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----',
    '-----BEGIN CERTIFICATE-----\nCERT3...\n-----END CERTIFICATE-----',
  ],
};
admin.auth().updateProviderConfig('saml.myProvider', updatedConfig).then(() => {
  // Successful update.
}).catch((error) => {
  // Handle error.
});

Go

updatedConfig := (&auth.SAMLProviderConfigToUpdate{}).
	X509Certificates([]string{
		"-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----",
		"-----BEGIN CERTIFICATE-----\nCERT3...\n-----END CERTIFICATE-----",
	})
saml, err := client.UpdateSAMLProviderConfig(ctx, "saml.myProvider", updatedConfig)
if err != nil {
	log.Fatalf("error updating SAML provider: %v\n", err)
}

log.Printf("Updated SAML provider: %s", saml.ID)auth.go

Python

saml = auth.update_saml_provider_config(
    'saml.myProvider',
    x509_certificates=[
        '-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----',
        '-----BEGIN CERTIFICATE-----\nCERT3...\n-----END CERTIFICATE-----',
    ])

print('Updated SAML provider:', saml.provider_id)index.py

Java

SamlProviderConfig.UpdateRequest request =
    new SamlProviderConfig.UpdateRequest("saml.myProvider")
      .addX509Certificate("-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----")
      .addX509Certificate("-----BEGIN CERTIFICATE-----\nCERT3...\n-----END CERTIFICATE-----");
SamlProviderConfig saml = FirebaseAuth.getInstance().updateSamlProviderConfig(request);
System.out.println("Updated SAML provider: " + saml.getProviderId());FirebaseAuthSnippets.java

Setelah selesai, metode akan menampilkan objek SAMLAuthProviderConfig untuk konfigurasi yang diperbarui.

Mendapatkan konfigurasi penyedia SAML

Cara utama untuk mengidentifikasi konfigurasi SAML adalah dengan menggunakan ID penyedianya. Contoh berikut menunjukkan cara mendapatkan konfigurasi penyedia SAML:

Node.js

admin.auth().getProviderConfig('saml.myProvider').then((config) => {
  // Get display name and whether it is enabled.
  console.log(config.displayName, config.enabled);
}).catch((error) => {
  // Handle error. Common error is that config is not found.
});

Go

saml, err := client.SAMLProviderConfig(ctx, "saml.myProvider")
if err != nil {
	log.Fatalf("error retrieving SAML provider: %v\n", err)
}

log.Printf("%s %t", saml.DisplayName, saml.Enabled)auth.go

Python

saml = auth.get_saml_provider_config('saml.myProvider')
print(saml.display_name, saml.enabled)index.py

Java

SamlProviderConfig saml = FirebaseAuth.getInstance().getSamlProviderConfig("saml.myProvider");
System.out.println(saml.getDisplayName() + ": " + saml.isEnabled());FirebaseAuthSnippets.java

Jika penyedia dengan ID yang diberikan sudah ada, metode akan menampilkan objek SAMLAuthProviderConfig.

Menghapus konfigurasi penyedia SAML

Contoh berikut menunjukkan cara menghapus konfigurasi penyedia SAML:

Node.js

admin.auth().deleteProviderConfig('saml.myProvider').then(() => {
  // Successful deletion.
}).catch((error) => {
  // Handle error.
});

Go

if err := client.DeleteSAMLProviderConfig(ctx, "saml.myProvider"); err != nil {
	log.Fatalf("error deleting SAML provider: %v\n", err)
}auth.go

Python

auth.delete_saml_provider_config('saml.myProvider')index.py

Java

FirebaseAuth.getInstance().deleteSamlProviderConfig("saml.myProvider");FirebaseAuthSnippets.java

Mencantumkan konfigurasi penyedia SAML

Contoh berikut menunjukkan cara mencantumkan konfigurasi penyedia SAML yang ada:

Node.js

// Returns 10 SAML provider configs starting from the specified nextPageToken offset.
admin.auth().listProviderConfigs({type: 'saml', maxResults: 10, pageToken: 'nextPageToken'}).then((results) => {
  results.providerConfigs.forEach((config) => {
    console.log(config.providerId);
  });
  // To list the next 10:
  // return admin.auth().listProviderConfigs(
  //     {type: 'saml', maxResults: 10, pageToken: results.pageToken});
}).catch((error) => {
  // Handle error.
});

Go

iter := client.SAMLProviderConfigs(ctx, "nextPageToken")
for {
	saml, err := iter.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		log.Fatalf("error retrieving SAML providers: %v\n", err)
	}

	log.Printf("%s\n", saml.ID)
}auth.go

Python

for saml in auth.list_saml_provider_configs('nextPageToken').iterate_all():
    print(saml.provider_id)index.py

Java

ListProviderConfigsPage<SamlProviderConfig> page = FirebaseAuth.getInstance()
    .listSamlProviderConfigs("nextPageToken");
for (SamlProviderConfig config : page.iterateAll()) {
  System.out.println(config.getProviderId());
}FirebaseAuthSnippets.java

Setiap batch hasil berisi daftar konfigurasi penyedia, dan token halaman berikutnya yang digunakan untuk mengambil batch berikutnya. Setelah semua penyedia telah tercantum, tidak ada token yang ditampilkan.

Secara default, 100 penyedia ditampilkan dengan setiap batch. Ini juga merupakan jumlah maksimum penyedia per batch.

Bekerja sama dengan penyedia OIDC

Membuat konfigurasi penyedia OIDC

Anda harus menyediakan parameter berikut saat membuat konfigurasi penyedia OIDC. Anda mungkin perlu membaca dokumentasi penyedia identitas untuk mengetahui detail tentang cara mendapatkan beberapa nilai.

Nama tampilan: Nama tampilan yang mudah digunakan untuk konfigurasi. Nama ini juga merupakan label penyedia di Konsol Google Cloud.
Diaktifkan: Apakah konfigurasi penyedia saat ini diaktifkan atau dinonaktifkan. Pengguna tidak dapat login dengan penyedia yang dinonaktifkan.
ID Penyedia: ID unik penyedia, dimulai dengan oidc..
Client ID: ID yang digunakan untuk mengonfirmasi audiens token ID penyedia OIDC.
Rahasia Klien: Rahasia klien yang diperlukan untuk mengaktifkan alur kode OIDC.
Penerbit: Issuer penyedia. Tampilannya akan terlihat seperti https://example.com. Identity Platform menggunakan URL ini untuk menemukan dokumen penemuan OIDC (biasanya ditemukan di /.well-known/openid-configuration), yang menentukan endpoint OAuth dan kunci publik penyedia. Identity Platform memvalidasi token ID sesuai dengan spesifikasi OpenID Connect. Jika tidak mematuhi spesifikasi OIDC untuk penemuan, penyedia Anda tidak akan berfungsi dengan Identity Platform.
Jenis Respons: Jenis respons penyedia untuk alur otorisasi OAuth. Anda dapat menetapkan salah satu dari {idToken, code} ke true, bukan keduanya. Jika alur kode diaktifkan, Anda harus memberikan rahasia klien.

Contoh berikut menunjukkan cara membuat konfigurasi penyedia OIDC yang menggunakan alur otorisasi implisit:

Node.js

const newConfig = {
  displayName: 'OIDC provider name',
  enabled: true,
  clientId: 'CLIENT_ID2',
  issuer: 'https://oidc.com/CLIENT_ID2',
  providerId: 'oidc.provider2',
  responseType: {
    idToken: true,
    code: false,
  },
};
admin.auth().createProviderConfig(newConfig).then(() => {
  // Successful creation.
}).catch((error) => {
  // Handle error.
});

Go

newConfig := (&auth.OIDCProviderConfigToCreate{}).
	DisplayName("OIDC provider name").
	Enabled(true).
	ID("oidc.myProvider").
	ClientID("CLIENT_ID2").
	Issuer("https://oidc.com/CLIENT_ID2")
oidc, err := client.CreateOIDCProviderConfig(ctx, newConfig)
if err != nil {
	log.Fatalf("error creating OIDC provider: %v\n", err)
}

log.Printf("Created new OIDC provider: %s", oidc.ID)auth.go

Python

oidc = auth.create_oidc_provider_config(
    display_name='OIDC provider name',
    enabled=True,
    provider_id='oidc.myProvider',
    client_id='CLIENT_ID2',
    issuer='https://oidc.com/CLIENT_ID2')

print('Created new OIDC provider:', oidc.provider_id)index.py

Java

OidcProviderConfig.CreateRequest request = new OidcProviderConfig.CreateRequest()
    .setDisplayName("OIDC provider name")
    .setEnabled(true)
    .setProviderId("oidc.myProvider")
    .setClientId("CLIENT_ID2")
    .setIssuer("https://oidc.com/CLIENT_ID2");
OidcProviderConfig oidc = FirebaseAuth.getInstance().createOidcProviderConfig(request);
System.out.println("Created new OIDC provider: " + oidc.getProviderId());FirebaseAuthSnippets.java

Setelah selesai, metode akan menampilkan objek OIDCAuthProviderConfig untuk konfigurasi yang baru dibuat.

Memperbarui konfigurasi penyedia OIDC

Contoh berikut menunjukkan cara mengubah konfigurasi penyedia OIDC. Anda dapat memperbarui kolom apa pun, kecuali ID penyedia.

Node.js

const updatedConfig = {
  displayName: 'OIDC provider name',
  enabled: true,
  clientId: 'CLIENT_ID',
  clientSecret: 'CLIENT_SECRET'
  issuer: 'https://oidc.com/',
  responseType: {
    code: true,
    idToken: false,
  },
};
admin.auth().updateProviderConfig('oidc.myProvider', updatedConfig).then(() => {
  // Successful update.
}).catch((error) => {
  // Handle error.
});

Go

updatedConfig := (&auth.OIDCProviderConfigToUpdate{}).
	DisplayName("OIDC provider name").
	Enabled(true).
	ClientID("CLIENT_ID").
	Issuer("https://oidc.com")
oidc, err := client.UpdateOIDCProviderConfig(ctx, "oidc.myProvider", updatedConfig)
if err != nil {
	log.Fatalf("error updating OIDC provider: %v\n", err)
}

log.Printf("Updated OIDC provider: %s", oidc.ID)auth.go

Python

oidc = auth.update_oidc_provider_config(
    'oidc.myProvider',
    client_id='CLIENT_ID',
    issuer='https://oidc.com')

print('Updated OIDC provider:', oidc.provider_id)index.py

Java

OidcProviderConfig.UpdateRequest request =
    new OidcProviderConfig.UpdateRequest("oidc.myProvider")
        .setDisplayName("OIDC provider name")
        .setEnabled(true)
        .setClientId("CLIENT_ID")
        .setIssuer("https://oidc.com");
OidcProviderConfig oidc = FirebaseAuth.getInstance().updateOidcProviderConfig(request);
System.out.println("Updated OIDC provider: " + oidc.getProviderId());FirebaseAuthSnippets.java

Setelah selesai, metode akan menampilkan objek OIDCAuthProviderConfig untuk konfigurasi yang diperbarui.

Mendapatkan konfigurasi penyedia OIDC

Cara utama untuk mengidentifikasi konfigurasi OIDC adalah dengan menggunakan ID penyedianya. Contoh berikut menunjukkan cara mendapatkan konfigurasi penyedia OIDC:

Node.js

admin.auth().getProviderConfig('oidc.myProvider').then((config) => {
  // Get display name and whether it is enabled.
  console.log(config.displayName, config.enabled);
}).catch((error) => {
  // Handle error. Common error is that config is not found.
});

Go

oidc, err := client.OIDCProviderConfig(ctx, "oidc.myProvider")
if err != nil {
	log.Fatalf("error retrieving OIDC provider: %v\n", err)
}

log.Printf("%s %t", oidc.DisplayName, oidc.Enabled)auth.go

Python

oidc = auth.get_oidc_provider_config('oidc.myProvider')

print(oidc.display_name, oidc.enabled)index.py

Java

OidcProviderConfig oidc = FirebaseAuth.getInstance().getOidcProviderConfig("oidc.myProvider");
System.out.println(oidc.getDisplayName() + ": " + oidc.isEnabled());FirebaseAuthSnippets.java

Jika penyedia dengan ID yang diberikan sudah ada, metode akan menampilkan objek OIDCAuthProviderConfig.

Menghapus konfigurasi penyedia OIDC

Contoh berikut menunjukkan cara menghapus konfigurasi penyedia OIDC:

Node.js

admin.auth().deleteProviderConfig('oidc.myProvider').then(() => {
  // Successful deletion.
}).catch((error) => {
  // Handle error.
});

Go

if err := client.DeleteOIDCProviderConfig(ctx, "oidc.myProvider"); err != nil {
	log.Fatalf("error deleting OIDC provider: %v\n", err)
}auth.go

Python

auth.delete_oidc_provider_config('oidc.myProvider')index.py

Java

FirebaseAuth.getInstance().deleteOidcProviderConfig("oidc.myProvider");FirebaseAuthSnippets.java

Mencantumkan konfigurasi penyedia OIDC

Contoh berikut menunjukkan cara menampilkan daftar konfigurasi penyedia OIDC yang ada:

Node.js

// Returns 10 OIDC provider configs starting from the specified nextPageToken offset.
admin.auth().listProviderConfigs({type: 'oidc', maxResults: 10, pageToken: 'nextPageToken'}).then((results) => {
  results.providerConfigs.forEach((config) => {
    console.log(config.providerId);
  });
  // To list the next 10:
  // return admin.auth().listProviderConfigs(
  //     {type: 'oidc', maxResults: 10, pageToken: results.pageToken});
}).catch((error) => {
  // Handle error.
});

Go

iter := client.OIDCProviderConfigs(ctx, "nextPageToken")
for {
	oidc, err := iter.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		log.Fatalf("error retrieving OIDC providers: %v\n", err)
	}

	log.Printf("%s\n", oidc.ID)
}auth.go

Python

for oidc in auth.list_oidc_provider_configs('nextPageToken').iterate_all():
    print(oidc.provider_id)index.py

Java

ListProviderConfigsPage<OidcProviderConfig> page = FirebaseAuth.getInstance()
    .listOidcProviderConfigs("nextPageToken");
for (OidcProviderConfig oidc : page.iterateAll()) {
  System.out.println(oidc.getProviderId());
}FirebaseAuthSnippets.java

Setiap batch hasil berisi daftar konfigurasi penyedia, dan token halaman berikutnya yang digunakan untuk mengambil batch berikutnya. Jika semua penyedia telah tercantum, tidak ada token yang ditampilkan.

Secara default, 100 penyedia ditampilkan dengan setiap batch. Ini juga merupakan jumlah maksimum penyedia per batch.

Langkah selanjutnya

Migrasikan pengguna dari aplikasi yang ada.
Proses login pengguna dengan SAML dan OIDC.