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 menggunakan Admin SDK, Anda dapat mengonfigurasi penyedia secara otomatis, melakukan operasi CRUD dasar, merotasi sertifikat, dan lainnya. Hal ini berguna jika Anda memiliki banyak penyedia yang akan sulit dikelola secara manual menggunakan konsol Google Cloud.

Sebelum memulai

Bekerja sama dengan penyedia SAML

Membuat konfigurasi penyedia SAML

Anda harus memberikan parameter berikut saat membuat konfigurasi penyedia SAML. Anda mungkin perlu melihat 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.
Aktif
Apakah konfigurasi penyedia saat ini diaktifkan atau dinonaktifkan. Pengguna tidak dapat login dengan penyedia yang dinonaktifkan.
ID Penyedia
ID unik penyedia, yang diawali 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----. Ini digunakan untuk penandatanganan token di penyedia identitas.

Saat menerima respons SAML, Identity Platform akan memverifikasi tanda tangannya menggunakan sertifikat yang tercatat. Jika verifikasi gagal, respons akan ditolak. Anda harus memperbarui sertifikat ini saat kunci dirotasi. Pertimbangkan untuk mengupload beberapa sertifikat guna mencegah pemadaman 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 audiens.
URL callback

URL yang akan ditampilkan saat autentikasi selesai. Penyedia SAML biasanya menyebutnya sebagai URL Assertion Consumer Service (ACS). Anda harus mendaftarkan URL ini ke penyedia SAML. Tampilannya 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 kompleksitas 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 dengan penyedia identitas SAML Anda. Biasanya, tampilannya terlihat seperti 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)

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)

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());

Setelah selesai, metode ini 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)

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)

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());

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

Mendapatkan konfigurasi penyedia SAML

Cara utama untuk mengidentifikasi konfigurasi SAML adalah 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)

Python

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

Java

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

Jika penyedia dengan ID yang diberikan 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)
}

Python

auth.delete_saml_provider_config('saml.myProvider')

Java

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

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)
}

Python

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

Java

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

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

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

Menggunakan penyedia OIDC

Membuat konfigurasi penyedia OIDC

Anda harus memberikan parameter berikut saat membuat konfigurasi penyedia OIDC. Anda mungkin perlu melihat 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.
Aktif
Apakah konfigurasi penyedia saat ini diaktifkan atau dinonaktifkan. Pengguna tidak dapat login dengan penyedia yang dinonaktifkan.
ID Penyedia
ID unik penyedia, yang diawali dengan oidc..
ID Klien
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 penyedia Anda tidak mematuhi specifikasi OIDC untuk penemuan, penyedia tersebut 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 secret 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)

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)

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());

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)

Python

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

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

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());

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

Mendapatkan konfigurasi penyedia OIDC

Cara utama untuk mengidentifikasi konfigurasi OIDC adalah 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)

Python

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

print(oidc.display_name, oidc.enabled)

Java

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

Jika penyedia dengan ID yang diberikan 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)
}

Python

auth.delete_oidc_provider_config('oidc.myProvider')

Java

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

Mencantumkan konfigurasi penyedia OIDC

Contoh berikut menunjukkan cara mencantumkan 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)
}

Python

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

Java

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

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

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

Langkah selanjutnya