Managing SAML and OIDC providers programmatically

The Admin SDK provides an API for managing Security Assertion Markup Language (SAML) 2.0 and OpenID Connect (OIDC) provider configurations programmatically from a secure server environment. This is useful when dealing with large numbers of SAML or OIDC providers that would be burdensome to handle manually using the Google Cloud Platform Console. Using the Admin SDK, you can automatically configure providers, perform basic CRUD operations, rotate certificates, and more.

Before you begin

You need a service account to use the provider configuration management API. Follow the setup instructions for more information on how to initialize the Admin SDK.

Create a SAML provider configuration

You'll need to supply the following parameters when creating a SAML provider configuration:

Display name: The user friendly display name to the current configuration. This name is also the provider label in the Cloud Console.
Enabled: Whether the current provider configuration is enabled or disabled. A user cannot sign in using a disabled provider.
Provider ID: The unique provider identifier. For a SAML provider, this must be prefixed by saml..
IdP entity ID: The SAML IdP entity identifier
SSO URL: The SAML IdP SSO URL. This has to be a valid URL.
X.509 certificates: The list of SAML IdP X.509 certificates used for token-signing on the identity provider. Multiple certificates are accepted to prevent outages during IdP key rotation. When Identity Platform receives a SAML response, it will verify the signing on the response with a certificate on record. Otherwise the response will be rejected. Developers are expected to manage certificate updates as keys are rotated.
RP/SP entity ID: The SAML relying party (service provider) entity ID. This is commonly the URL of the application. On the SAML identity provider, this is referred to as the audience.
Callback URL: Commonly known as the Assertion Consumer Service (ACS) URL in the SAML identity provider. This should be the same as the OAuth redirect URL provisioned when the product is enabled (https://project-id.firebaseapp.com/__/auth/handler), unless a custom authDomain is used. The callback URL should also be provided to the SAML IdP during configuration.

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

When configuring the certificates, make sure to include the "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" strings.

Note that using the default callback URL can help minimize the complexity of validating the SAML response. When you use this flow, make sure the Identity Platform callback URL for your project is configured at your SAML identity provider. This is usually in the form of https://<authDomain>/__/auth/handler. For information on customizing the callback URL, see Customizing the Redirect Domain.

Refer to Handling the sign-in flow with the client SDK to learn more about how to sign in with the created provider using the client SDK.

The method returns a SAMLAuthProviderConfig object for the newly created configuration.

If the provided providerId is already in use by an existing provider or the configuration cannot be created for any other reason, the method fails with an error.

Update a SAML provider configuration

When updating a SAML provider configuration, you can modify any existing field except the Provider ID.

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

The method returns an updated SAMLAuthProviderConfig object when the update successfully completes.

If the provided providerId does not correspond to an existing configuration or the configuration cannot be updated for any other reason, the method fails with an error.

Retrieve a SAML provider configuration

The primary way to identify a SAML configuration is by its providerId, a unique identifier for that configuration. The Admin SDK provides a method for fetching provider configuration information using its providerId:

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

Delete a SAML provider configuration

The Admin SDK allows deleting ab existing SAML provider using its providerId.

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

The method returns an empty result when the deletion completes successfully.

If the provided providerId does not correspond to an existing configuration or the configuration cannot be deleted for any other reason, the method throws an error.

List all SAML provider configurations

The Admin SDK allows retrieving the entire list of SAML provider configurations in batches.

// 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.
});

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

If no maxResults field is specified, a default of 100 providers per batch is used. This is also the maximum number of providers allowed to be listed at a time. Any value greater than the maximum will throw an argument error. If no pageToken is specified, the operation will list providers from the beginning, ordered by providerId.

Create an OIDC provider configuration

You'll need to supply the following parameters when creating an OIDC provider configuration:

Display name: The user friendly display name to the current configuration. This name is also the provider label in the GCP Console.
Enabled: Whether the current provider configuration is enabled or disabled. A user cannot sign in using a disabled provider.
Provider ID: The unique provider identifier. For an OIDC provider, this is always prefixed by oidc..
Client ID: This is the required client ID used to confirm the audience of an OIDC provider's ID token.
Issuer: This is the required provider issuer used to match the provider issuer of the ID token and to figure out the OIDC discovery document: e.g., /.well-known/openid-configuration. This is needed to:
- Verify the provided issuer.
- Determine the authentication/authorization endpoint during the OAuth id_token authentication flow.
- Retrieve the public signing keys via jwks_uri to verify the OIDC provider's ID token's signature.
- Determine the claims_supported to construct the user attributes to be returned in the additional user info response.
ID token validation will be performed as defined in the OpenID Connect specification.

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

Refer to Handling the sign-in flow with the client SDK to learn more about how to sign in with the created provider using the client SDK.

The method returns a OIDCAuthProviderConfig object for the newly created configuration.

If the provided providerId is already in use by an existing provider or the configuration cannot be created for any other reason, the method fails with an error.

Update an OIDC provider configuration

When updating an OIDC provider configuration, you can modify any existing field except the Provider ID.

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

The method returns an updated OIDCAuthProviderConfig object when the update successfully completes.

If the provided providerId does not correspond to an existing configuration or the configuration cannot be updated for any other reason, the method fails with an error.

Retrieve an OIDC provider configuration

The primary way to identify an OIDC configuration is by its providerId, a unique identifier for that configuration. The Admin SDK provides a method for fetching provider configuration information using its providerId:

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

Delete an OIDC provider configuration

The Admin SDK allows deleting an existing OIDC provider using its providerId:

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

The method returns an empty result when deletion completes successfully.