# Managing SAML and OIDC providers programmatically

This document shows you how to use the Identity Platform Admin SDK to manage
Security Assertion Markup Language (SAML) 2.0 and OpenID Connect (OIDC) provider
configurations programmatically.

Using the Admin SDK, you can automatically configure providers, perform
basic CRUD operations, rotate certificates, and more. This is useful when you
have a large number of providers that would be cumbersome to manage manually
using the Google Cloud console.

## Before you begin

- [Enable Identity Platform](https://docs.cloud.google.com/identity-platform/docs/sign-in-user-email.md.txt).
- [Install the Admin SDK](https://docs.cloud.google.com/identity-platform/docs/install-admin-sdk.md.txt).

## Working with SAML providers

### Creating a SAML provider configuration

You'll need to supply the following parameters when creating a SAML provider
configuration. You may need to consult your identity provider's documentation
for details on how to obtain some of the values.

Display name
:
    A user-friendly display name for the configuration. This name is also
    the provider label in the Google Cloud console.

Enabled
:
    Whether the current provider configuration is enabled or
    disabled. Users cannot sign in with disabled providers.

Provider ID
:
    The provider's unique identifier, beginning with `saml.`.

Identity provider entity ID
:
    The entity ID for the provider.

SSO URL
:
    The SAML SSO URL for the provider. The URL must be valid.

X.509 certificates

:
    A list of SAML provider X.509 certificates, including the
    `---BEGIN CERTIFICATE---` and
    `---END CERTIFICATE---` strings. These are used for
    token-signing on the identity provider.


    When Identity Platform receives a SAML response, it will verify its
    signature using a certificate on record. If verification fails, the
    response will be rejected. You will need to update these certificates as
    keys are rotated. Consider uploading multiple certificates to prevent
    outages during rotations.

Relaying party entity ID
:
    The SAML relying party (RP/SP) entity ID. This is commonly the URL of the
    app. On the SAML identity provider, this is referred to as the audience.

Callback URL

:
    The URL to return to when authentication completes. SAML providers
    commonly refer to this as the Assertion Consumer Service
    (ACS) URL. You'll need to register this URL with the SAML provider.
    It should look something like
    `https://PROJECT-ID.firebaseapp.com/__/auth/handler`,
    similar to the URLs displayed in the Google Cloud console. To learn
    more, see [Signing in users with
    SAML](https://docs.cloud.google.com/identity-platform/docs/web/saml).


    Using the default callback URL will decrease the complexity of validating
    SAML responses. However, you can also choose to show a
    [custom domain](https://docs.cloud.google.com/identity-platform/docs/show-custom-domain.md.txt).
    In this case, make sure the Identity Platform callback URL for
    your project is properly correctly configured with your SAML identity
    provider. Typically, this looks something like
    `https://AUTH-DOMAIN/__/auth/handler`.

The following example demonstrates how to create a SAML provider configuration:

### Node.js

```javascript
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

```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

```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

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

On completion, the method returns a
[`SAMLAuthProviderConfig`](https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects.inboundSamlConfigs)
object for the newly created configuration.

### Updating a SAML provider configuration

The following example demonstrates how to modify a SAML provider configuration.
You can update any field, except for the provider ID.

### Node.js

```javascript
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

```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

```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

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

On completion, the method returns a
[`SAMLAuthProviderConfig`](https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects.inboundSamlConfigs)
object for the updated configuration.

### Getting a SAML provider configuration

The primary way to identify a SAML configuration is using its provider ID.
The following example shows how to get a SAML provider configuration:

### Node.js

```javascript
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

```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

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

### Java

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

If a provider with the given ID exists, the method returns a
[`SAMLAuthProviderConfig`](https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects.inboundSamlConfigs)
object.

### Deleting a SAML provider configuration

The following example shows how to delete a SAML provider configuration:

### Node.js

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

### Go

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

### Python

```python
auth.delete_saml_provider_config('saml.myProvider')
```

### Java

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

### Listing SAML provider configurations

The following example shows how to list existing SAML provider configurations:

### Node.js

```javascript
// 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

```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

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

### Java

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

Each batch of results contains a list of provider configurations, and a next
page token used to fetch the next batch. When all providers have been listed,
no token is returned.

By default, 100 providers are returned with each batch. This is also the maximum
number of providers per batch.

## Working with OIDC providers

### Creating an OIDC provider configuration

You'll need to supply the following parameters when creating an OIDC provider
configuration. You may need to consult your identity provider's documentation
for details on how to obtain some of the values.

Display name
:
    A user-friendly display name for the configuration. This name is also
    the provider label in the Google Cloud console.

Enabled
:
    Whether the current provider configuration is enabled or
    disabled. Users cannot sign in with disabled providers.

Provider ID
:
    The provider's unique identifier, beginning with `oidc.`.

Client ID
:
    The ID used to confirm the audience of an OIDC provider's
    [ID token](https://openid.net/specs/openid-connect-core-1_0-final.html#IDToken).

Client Secret
:
    The client secret required to enable the OIDC code flow.

Issuer
:
    The provider's `Issuer`. This should look something like
    `https://example.com`. Identity Platform uses this URL to
    locate the OIDC discovery document (typically found at
    `/.well-known/openid-configuration`), which specifies the
    provider's OAuth endpoints and public keys.

    Identity Platform validates ID tokens according to the
    [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation). If your provider doesn't comply with the
    OIDC specification for discovery, it won't work with Identity Platform.

Response Type
:
    The provider's response type for the OAuth authorization flow. You can set
    one of {`idToken`, `code`} to `true`, not
    both. If the code flow is enabled, you must provide a client secret.

> [!NOTE]
> **Note:** The authorization code flow is currently only supported in Node.js and Java.

The following example demonstrates how to create an OIDC provider configuration
that uses the implicit authorization flow:

### Node.js

```javascript
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

```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

```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

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

On completion, the method returns an
[`OIDCAuthProviderConfig`](https://docs.cloud.google.com/identity-platform/docs/reference/rest/v2/projects.oauthIdpConfigs.md.txt)
object for the newly created configuration.

### Updating an OIDC provider configuration

The following example demonstrates how to modify an OIDC provider configuration.
You can update any field, except for the provider ID.

### Node.js

```javascript
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

```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

```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

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

On completion, the method returns an
[`OIDCAuthProviderConfig`](https://docs.cloud.google.com/identity-platform/docs/reference/rest/v2/projects.oauthIdpConfigs.md.txt)
object for the updated configuration.

### Getting an OIDC provider configuration

The primary way to identify an OIDC configuration is using its provider ID. The
following example shows how to get an OIDC provider configuration:

### Node.js

```javascript
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

```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

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

print(oidc.display_name, oidc.enabled)
```

### Java

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

If a provider with the given ID exists, the method returns an
[`OIDCAuthProviderConfig`](https://docs.cloud.google.com/identity-platform/docs/reference/rest/v2/projects.oauthIdpConfigs.md.txt)
object.

### Deleting an OIDC provider configuration

The following example demonstrates how to delete an OIDC provider configuration:

### Node.js

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

### Go

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

### Python

```python
auth.delete_oidc_provider_config('oidc.myProvider')
```

### Java

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

### Listing OIDC provider configurations

The following example shows how to list existing OIDC provider configurations:

### Node.js

```javascript
// 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

```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

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

### Java

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

Each batch of results contains a list of provider configurations, and a next
page token used to fetch the next batch. When all providers have been listed, no
token is returned.

By default, 100 providers are returned with each batch. This is also the maximum
number of providers per batch.

## What's next

- [Migrate users](https://docs.cloud.google.com/identity-platform/docs/migrating-users.md.txt) from an existing app.
- Sign in users with [SAML](https://docs.cloud.google.com/identity-platform/docs/web/saml.md.txt) and [OIDC](https://docs.cloud.google.com/identity-platform/docs/web/oidc.md.txt).