feat(backend): Add enterprise connection resource

.changeset/slick-berries-tie.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add `EnterpriseConnection` resource, allowing to create both OIDC and SAML connections

packages/backend/src/api/endpoints/EnterpriseConnectionApi.ts

@@ -0,0 +1,106 @@
+import type { ClerkPaginationRequest } from '@clerk/shared/types';
+
+import { joinPaths } from '../../util/path';
+import type { EnterpriseConnection } from '../resources';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/enterprise_connections';
+
+type EnterpriseConnectionListParams = ClerkPaginationRequest<{
+ organizationId?: string;
+ active?: boolean;
+}>;
+
+export interface EnterpriseConnectionOidcParams {
+ authUrl?: string;
+ clientId?: string;
+ clientSecret?: string;
+ discoveryUrl?: string;
+ requiresPkce?: boolean;
+ tokenUrl?: string;
+ userInfoUrl?: string;
+}
+
+export interface EnterpriseConnectionSamlAttributeMappingParams {
+ userId?: string | null;
+ emailAddress?: string | null;
+ firstName?: string | null;
+ lastName?: string | null;
+}
+
+export interface EnterpriseConnectionSamlParams {
+ allowIdpInitiated?: boolean;
+ allowSubdomains?: boolean;
+ attributeMapping?: EnterpriseConnectionSamlAttributeMappingParams;
+ forceAuthn?: boolean;
+ idpCertificate?: string;
+ idpEntityId?: string;
+ idpMetadata?: string;
+ idpMetadataUrl?: string;
+ idpSsoUrl?: string;
+}
+
+type CreateEnterpriseConnectionParams = {
+ name?: string;
+ domains?: string[];
+ organizationId?: string;
+ active?: boolean;
+ syncUserAttributes?: boolean;
+ oidc?: EnterpriseConnectionOidcParams;
+ saml?: EnterpriseConnectionSamlParams;
+};
+
+type UpdateEnterpriseConnectionParams = {
+ name?: string;
+ domains?: string[];
+ organizationId?: string;
+ active?: boolean;
+ syncUserAttributes?: boolean;
+ provider?: string;
+ oidc?: EnterpriseConnectionOidcParams;
+ saml?: EnterpriseConnectionSamlParams;
+};
+
+export class EnterpriseConnectionAPI extends AbstractAPI {
+ public async createEnterpriseConnection(params: CreateEnterpriseConnectionParams) {
+ return this.request<EnterpriseConnection>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ public async updateEnterpriseConnection(enterpriseConnectionId: string, params: UpdateEnterpriseConnectionParams) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'PATCH',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ bodyParams: params,
+ });
+ }
+
+ public async getEnterpriseConnectionList(params: EnterpriseConnectionListParams = {}) {
+ return this.request<PaginatedResourceResponse<EnterpriseConnection[]>>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ });
+ }
+
+ public async getEnterpriseConnection(enterpriseConnectionId: string) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'GET',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ });
+ }
+
+ public async deleteEnterpriseConnection(enterpriseConnectionId: string) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'DELETE',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ });
+ }
+}

packages/backend/src/api/endpoints/index.ts

@@ -9,6 +9,7 @@ export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './EnterpriseConnectionApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';
 export * from './InvitationApi';

packages/backend/src/api/factory.ts

@@ -9,6 +9,7 @@ import {
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ EnterpriseConnectionAPI,
  IdPOAuthAccessTokenApi,
  InstanceAPI,
  InvitationAPI,
@@ -67,6 +68,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),
+ enterpriseConnections: new EnterpriseConnectionAPI(request),
  idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
  buildRequest({
  ...options,
@@ -96,13 +98,17 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  phoneNumbers: new PhoneNumberAPI(request),
  proxyChecks: new ProxyCheckAPI(request),
  redirectUrls: new RedirectUrlAPI(request),
- samlConnections: new SamlConnectionAPI(request),
  sessions: new SessionAPI(request),
  signInTokens: new SignInTokenAPI(request),
  signUps: new SignUpAPI(request),
  testingTokens: new TestingTokenAPI(request),
  users: new UserAPI(request),
  waitlistEntries: new WaitlistEntryAPI(request),
  webhooks: new WebhookAPI(request),
+
+ /**
+ * @deprecated Use `enterpriseConnections` instead.
+ */
+ samlConnections: new SamlConnectionAPI(request),
  };
 }

packages/backend/src/api/resources/Deserializer.ts

@@ -10,6 +10,7 @@ import {
  Domain,
  Email,
  EmailAddress,
+ EnterpriseConnection,
  IdPOAuthAccessToken,
  Instance,
  InstanceRestrictions,
@@ -193,6 +194,8 @@ function jsonToObject(item: any): any {
  return ProxyCheck.fromJSON(item);
  case ObjectType.RedirectUrl:
  return RedirectUrl.fromJSON(item);
+ case ObjectType.EnterpriseConnection:
+ return EnterpriseConnection.fromJSON(item);
  case ObjectType.SamlConnection:
  return SamlConnection.fromJSON(item);
  case ObjectType.SignInToken:

packages/backend/src/api/resources/EnterpriseConnection.ts

@@ -0,0 +1,64 @@
+import type { EnterpriseConnectionJSON } from './JSON';
+
+/**
+ * The Backend `EnterpriseConnection` object holds information about an enterprise connection (SAML or OAuth) for an instance or organization.
+ */
+export class EnterpriseConnection {
+ constructor(
+ /**
+ * The unique identifier for the connection.
+ */
+ readonly id: string,
+ /**
+ * The name to use as a label for the connection.
+ */
+ readonly name: string,
+ /**
+ * The domain of the enterprise. Sign-in flows using an email with this domain may use the connection.
+ */
+ readonly domains: Array<string>,
+ /**
+ * The Organization ID if the connection is scoped to an organization.
+ */
+ readonly organizationId: string | null,
+ /**
+ * Indicates whether the connection is active or not.
+ */
+ readonly active: boolean,
+ /**
+ * Indicates whether the connection syncs user attributes between the IdP and Clerk or not.
+ */
+ readonly syncUserAttributes: boolean,
+ /**
+ * Indicates whether users with an email address subdomain are allowed to use this connection or not.
+ */
+ readonly allowSubdomains: boolean,
+ /**
+ * Indicates whether additional identifications are disabled for this connection.
+ */
+ readonly disableAdditionalIdentifications: boolean,
+ /**
+ * The date when the connection was first created.
+ */
+ readonly createdAt: number,
+ /**
+ * The date when the connection was last updated.
+ */
+ readonly updatedAt: number,
+ ) {}
+
+ static fromJSON(data: EnterpriseConnectionJSON): EnterpriseConnection {
+ return new EnterpriseConnection(
+ data.id,
+ data.name,
+ data.domains,
+ data.organization_id,
+ data.active,
+ data.sync_user_attributes,
+ data.allow_subdomains,
+ data.disable_additional_identifications,
+ data.created_at,
+ data.updated_at,
+ );
+ }
+}

packages/backend/src/api/resources/JSON.ts

@@ -27,6 +27,7 @@ export const ObjectType = {
  Cookies: 'cookies',
  Domain: 'domain',
  Email: 'email',
+ EnterpriseConnection: 'enterprise_connection',
  EmailAddress: 'email_address',
  ExternalAccount: 'external_account',
  FacebookAccount: 'facebook_account',
@@ -670,6 +671,44 @@ export interface PaginatedResponseJSON {
  total_count?: number;
 }
 
+export interface EnterpriseConnectionJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.EnterpriseConnection;
+ name: string;
+ domains: string[];
+ organization_id: string | null;
+ active: boolean;
+ sync_user_attributes: boolean;
+ allow_subdomains: boolean;
+ disable_additional_identifications: boolean;
+ created_at: number;
+ updated_at: number;
+ saml_connection?: Pick<
+ SamlConnectionJSON,
+ | 'id'
+ | 'name'
+ | 'idp_entity_id'
+ | 'idp_sso_url'
+ | 'idp_certificate'
+ | 'idp_metadata_url'
+ | 'idp_metadata'
+ | 'acs_url'
+ | 'sp_entity_id'
+ | 'sp_metadata_url'
+ | 'sync_user_attributes'
+ | 'allow_subdomains'
+ | 'allow_idp_initiated'
+ >;
+ oauth_config?: {
+ id: string;
+ name: string;
+ client_id: string;
+ discovery_url: string;
+ logo_public_url: string;
+ created_at: number;
+ updated_at: number;
+ };
+}
+
 export interface SamlConnectionJSON extends ClerkResourceJSON {
  object: typeof ObjectType.SamlConnection;
  name: string;

packages/backend/src/api/resources/SamlConnection.ts

@@ -2,6 +2,7 @@ import type { AttributeMappingJSON, SamlConnectionJSON } from './JSON';
 
 /**
  * The Backend `SamlConnection` object holds information about a SAML connection for an organization.
+ * @deprecated Use `EnterpriseConnection` instead.
  */
 export class SamlConnection {
  constructor(

packages/backend/src/api/resources/index.ts

@@ -26,6 +26,7 @@ export type { SignUpStatus } from '@clerk/shared/types';
 export * from './CommercePlan';
 export * from './CommerceSubscription';
 export * from './CommerceSubscriptionItem';
+export * from './EnterpriseConnection';
 export * from './ExternalAccount';
 export * from './Feature';
 export * from './IdentificationLink';

packages/backend/src/index.ts

@@ -66,6 +66,7 @@ export type {
  DomainJSON,
  EmailJSON,
  EmailAddressJSON,
+ EnterpriseConnectionJSON,
  ExternalAccountJSON,
  IdentificationLinkJSON,
  InstanceJSON,
@@ -121,6 +122,7 @@ export type {
  CnameTarget,
  Domain,
  EmailAddress,
+ EnterpriseConnection,
  ExternalAccount,
  Feature,
  Instance,

.changeset/slick-berries-tie.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add `EnterpriseConnection` resource, allowing to create both OIDC and SAML connections

packages/backend/src/api/endpoints/EnterpriseConnectionApi.ts

@@ -0,0 +1,106 @@
+import type { ClerkPaginationRequest } from '@clerk/shared/types';
+
+import { joinPaths } from '../../util/path';
+import type { EnterpriseConnection } from '../resources';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/enterprise_connections';
+
+type EnterpriseConnectionListParams = ClerkPaginationRequest<{
+ organizationId?: string;
+ active?: boolean;
+}>;
+
+export interface EnterpriseConnectionOidcParams {
+ authUrl?: string;
+ clientId?: string;
+ clientSecret?: string;
+ discoveryUrl?: string;
+ requiresPkce?: boolean;
+ tokenUrl?: string;
+ userInfoUrl?: string;
+}
+
+export interface EnterpriseConnectionSamlAttributeMappingParams {
+ userId?: string | null;
+ emailAddress?: string | null;
+ firstName?: string | null;
+ lastName?: string | null;
+}
+
+export interface EnterpriseConnectionSamlParams {
+ allowIdpInitiated?: boolean;
+ allowSubdomains?: boolean;
+ attributeMapping?: EnterpriseConnectionSamlAttributeMappingParams;
+ forceAuthn?: boolean;
+ idpCertificate?: string;
+ idpEntityId?: string;
+ idpMetadata?: string;
+ idpMetadataUrl?: string;
+ idpSsoUrl?: string;
+}
+
+type CreateEnterpriseConnectionParams = {
+ name?: string;
+ domains?: string[];
+ organizationId?: string;
+ active?: boolean;
+ syncUserAttributes?: boolean;
+ oidc?: EnterpriseConnectionOidcParams;
+ saml?: EnterpriseConnectionSamlParams;
+};
+
+type UpdateEnterpriseConnectionParams = {
+ name?: string;
+ domains?: string[];
+ organizationId?: string;
+ active?: boolean;
+ syncUserAttributes?: boolean;
+ provider?: string;
+ oidc?: EnterpriseConnectionOidcParams;
+ saml?: EnterpriseConnectionSamlParams;
+};
+
+export class EnterpriseConnectionAPI extends AbstractAPI {
+ public async createEnterpriseConnection(params: CreateEnterpriseConnectionParams) {
+ return this.request<EnterpriseConnection>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ public async updateEnterpriseConnection(enterpriseConnectionId: string, params: UpdateEnterpriseConnectionParams) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'PATCH',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ bodyParams: params,
+ });
+ }
+
+ public async getEnterpriseConnectionList(params: EnterpriseConnectionListParams = {}) {
+ return this.request<PaginatedResourceResponse<EnterpriseConnection[]>>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ });
+ }
+
+ public async getEnterpriseConnection(enterpriseConnectionId: string) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'GET',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ });
+ }
+
+ public async deleteEnterpriseConnection(enterpriseConnectionId: string) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'DELETE',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ });
+ }
+}

packages/backend/src/api/endpoints/index.ts

@@ -9,6 +9,7 @@ export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './EnterpriseConnectionApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';
 export * from './InvitationApi';

packages/backend/src/api/factory.ts

@@ -9,6 +9,7 @@ import {
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ EnterpriseConnectionAPI,
  IdPOAuthAccessTokenApi,
  InstanceAPI,
  InvitationAPI,
@@ -67,6 +68,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),
+ enterpriseConnections: new EnterpriseConnectionAPI(request),
  idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
  buildRequest({
  ...options,
@@ -96,13 +98,17 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  phoneNumbers: new PhoneNumberAPI(request),
  proxyChecks: new ProxyCheckAPI(request),
  redirectUrls: new RedirectUrlAPI(request),
- samlConnections: new SamlConnectionAPI(request),
  sessions: new SessionAPI(request),
  signInTokens: new SignInTokenAPI(request),
  signUps: new SignUpAPI(request),
  testingTokens: new TestingTokenAPI(request),
  users: new UserAPI(request),
  waitlistEntries: new WaitlistEntryAPI(request),
  webhooks: new WebhookAPI(request),
+
+ /**
+ * @deprecated Use `enterpriseConnections` instead.
+ */
+ samlConnections: new SamlConnectionAPI(request),
  };
 }

packages/backend/src/api/resources/Deserializer.ts

@@ -10,6 +10,7 @@ import {
  Domain,
  Email,
  EmailAddress,
+ EnterpriseConnection,
  IdPOAuthAccessToken,
  Instance,
  InstanceRestrictions,
@@ -193,6 +194,8 @@ function jsonToObject(item: any): any {
  return ProxyCheck.fromJSON(item);
  case ObjectType.RedirectUrl:
  return RedirectUrl.fromJSON(item);
+ case ObjectType.EnterpriseConnection:
+ return EnterpriseConnection.fromJSON(item);
  case ObjectType.SamlConnection:
  return SamlConnection.fromJSON(item);
  case ObjectType.SignInToken:

packages/backend/src/api/resources/EnterpriseConnection.ts

@@ -0,0 +1,64 @@
+import type { EnterpriseConnectionJSON } from './JSON';
+
+/**
+ * The Backend `EnterpriseConnection` object holds information about an enterprise connection (SAML or OAuth) for an instance or organization.
+ */
+export class EnterpriseConnection {
+ constructor(
+ /**
+ * The unique identifier for the connection.
+ */
+ readonly id: string,
+ /**
+ * The name to use as a label for the connection.
+ */
+ readonly name: string,
+ /**
+ * The domain of the enterprise. Sign-in flows using an email with this domain may use the connection.
+ */
+ readonly domains: Array<string>,
+ /**
+ * The Organization ID if the connection is scoped to an organization.
+ */
+ readonly organizationId: string | null,
+ /**
+ * Indicates whether the connection is active or not.
+ */
+ readonly active: boolean,
+ /**
+ * Indicates whether the connection syncs user attributes between the IdP and Clerk or not.
+ */
+ readonly syncUserAttributes: boolean,
+ /**
+ * Indicates whether users with an email address subdomain are allowed to use this connection or not.
+ */
+ readonly allowSubdomains: boolean,
+ /**
+ * Indicates whether additional identifications are disabled for this connection.
+ */
+ readonly disableAdditionalIdentifications: boolean,
+ /**
+ * The date when the connection was first created.
+ */
+ readonly createdAt: number,
+ /**
+ * The date when the connection was last updated.
+ */
+ readonly updatedAt: number,
+ ) {}
+
+ static fromJSON(data: EnterpriseConnectionJSON): EnterpriseConnection {
+ return new EnterpriseConnection(
+ data.id,
+ data.name,
+ data.domains,
+ data.organization_id,
+ data.active,
+ data.sync_user_attributes,
+ data.allow_subdomains,
+ data.disable_additional_identifications,
+ data.created_at,
+ data.updated_at,
+ );
+ }
+}

packages/backend/src/api/resources/JSON.ts

@@ -27,6 +27,7 @@ export const ObjectType = {
  Cookies: 'cookies',
  Domain: 'domain',
  Email: 'email',
+ EnterpriseConnection: 'enterprise_connection',
  EmailAddress: 'email_address',
  ExternalAccount: 'external_account',
  FacebookAccount: 'facebook_account',
@@ -670,6 +671,44 @@ export interface PaginatedResponseJSON {
  total_count?: number;
 }
 
+export interface EnterpriseConnectionJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.EnterpriseConnection;
+ name: string;
+ domains: string[];
+ organization_id: string | null;
+ active: boolean;
+ sync_user_attributes: boolean;
+ allow_subdomains: boolean;
+ disable_additional_identifications: boolean;
+ created_at: number;
+ updated_at: number;
+ saml_connection?: Pick<
+ SamlConnectionJSON,
+ | 'id'
+ | 'name'
+ | 'idp_entity_id'
+ | 'idp_sso_url'
+ | 'idp_certificate'
+ | 'idp_metadata_url'
+ | 'idp_metadata'
+ | 'acs_url'
+ | 'sp_entity_id'
+ | 'sp_metadata_url'
+ | 'sync_user_attributes'
+ | 'allow_subdomains'
+ | 'allow_idp_initiated'
+ >;
+ oauth_config?: {
+ id: string;
+ name: string;
+ client_id: string;
+ discovery_url: string;
+ logo_public_url: string;
+ created_at: number;
+ updated_at: number;
+ };
+}
+
 export interface SamlConnectionJSON extends ClerkResourceJSON {
  object: typeof ObjectType.SamlConnection;
  name: string;

packages/backend/src/api/resources/SamlConnection.ts

@@ -2,6 +2,7 @@ import type { AttributeMappingJSON, SamlConnectionJSON } from './JSON';
 
 /**
  * The Backend `SamlConnection` object holds information about a SAML connection for an organization.
+ * @deprecated Use `EnterpriseConnection` instead.
  */
 export class SamlConnection {
  constructor(

packages/backend/src/api/resources/index.ts

@@ -26,6 +26,7 @@ export type { SignUpStatus } from '@clerk/shared/types';
 export * from './CommercePlan';
 export * from './CommerceSubscription';
 export * from './CommerceSubscriptionItem';
+export * from './EnterpriseConnection';
 export * from './ExternalAccount';
 export * from './Feature';
 export * from './IdentificationLink';

packages/backend/src/index.ts

@@ -66,6 +66,7 @@ export type {
  DomainJSON,
  EmailJSON,
  EmailAddressJSON,
+ EnterpriseConnectionJSON,
  ExternalAccountJSON,
  IdentificationLinkJSON,
  InstanceJSON,
@@ -121,6 +122,7 @@ export type {
  CnameTarget,
  Domain,
  EmailAddress,
+ EnterpriseConnection,
  ExternalAccount,
  Feature,
  Instance,

.changeset/slick-berries-tie.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add `EnterpriseConnection` resource, allowing to create both OIDC and SAML connections

packages/backend/src/api/endpoints/EnterpriseConnectionApi.ts

@@ -0,0 +1,106 @@
+import type { ClerkPaginationRequest } from '@clerk/shared/types';
+
+import { joinPaths } from '../../util/path';
+import type { EnterpriseConnection } from '../resources';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/enterprise_connections';
+
+type EnterpriseConnectionListParams = ClerkPaginationRequest<{
+ organizationId?: string;
+ active?: boolean;
+}>;
+
+export interface EnterpriseConnectionOidcParams {
+ authUrl?: string;
+ clientId?: string;
+ clientSecret?: string;
+ discoveryUrl?: string;
+ requiresPkce?: boolean;
+ tokenUrl?: string;
+ userInfoUrl?: string;
+}
+
+export interface EnterpriseConnectionSamlAttributeMappingParams {
+ userId?: string | null;
+ emailAddress?: string | null;
+ firstName?: string | null;
+ lastName?: string | null;
+}
+
+export interface EnterpriseConnectionSamlParams {
+ allowIdpInitiated?: boolean;
+ allowSubdomains?: boolean;
+ attributeMapping?: EnterpriseConnectionSamlAttributeMappingParams;
+ forceAuthn?: boolean;
+ idpCertificate?: string;
+ idpEntityId?: string;
+ idpMetadata?: string;
+ idpMetadataUrl?: string;
+ idpSsoUrl?: string;
+}
+
+type CreateEnterpriseConnectionParams = {
+ name?: string;
+ domains?: string[];
+ organizationId?: string;
+ active?: boolean;
+ syncUserAttributes?: boolean;
+ oidc?: EnterpriseConnectionOidcParams;
+ saml?: EnterpriseConnectionSamlParams;
+};
+
+type UpdateEnterpriseConnectionParams = {
+ name?: string;
+ domains?: string[];
+ organizationId?: string;
+ active?: boolean;
+ syncUserAttributes?: boolean;
+ provider?: string;
+ oidc?: EnterpriseConnectionOidcParams;
+ saml?: EnterpriseConnectionSamlParams;
+};
+
+export class EnterpriseConnectionAPI extends AbstractAPI {
+ public async createEnterpriseConnection(params: CreateEnterpriseConnectionParams) {
+ return this.request<EnterpriseConnection>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ public async updateEnterpriseConnection(enterpriseConnectionId: string, params: UpdateEnterpriseConnectionParams) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'PATCH',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ bodyParams: params,
+ });
+ }
+
+ public async getEnterpriseConnectionList(params: EnterpriseConnectionListParams = {}) {
+ return this.request<PaginatedResourceResponse<EnterpriseConnection[]>>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ });
+ }
+
+ public async getEnterpriseConnection(enterpriseConnectionId: string) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'GET',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ });
+ }
+
+ public async deleteEnterpriseConnection(enterpriseConnectionId: string) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'DELETE',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ });
+ }
+}

packages/backend/src/api/endpoints/index.ts

@@ -9,6 +9,7 @@ export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './EnterpriseConnectionApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';
 export * from './InvitationApi';

packages/backend/src/api/factory.ts

@@ -9,6 +9,7 @@ import {
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ EnterpriseConnectionAPI,
  IdPOAuthAccessTokenApi,
  InstanceAPI,
  InvitationAPI,
@@ -67,6 +68,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),
+ enterpriseConnections: new EnterpriseConnectionAPI(request),
  idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
  buildRequest({
  ...options,
@@ -96,13 +98,17 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  phoneNumbers: new PhoneNumberAPI(request),
  proxyChecks: new ProxyCheckAPI(request),
  redirectUrls: new RedirectUrlAPI(request),
- samlConnections: new SamlConnectionAPI(request),
  sessions: new SessionAPI(request),
  signInTokens: new SignInTokenAPI(request),
  signUps: new SignUpAPI(request),
  testingTokens: new TestingTokenAPI(request),
  users: new UserAPI(request),
  waitlistEntries: new WaitlistEntryAPI(request),
  webhooks: new WebhookAPI(request),
+
+ /**
+ * @deprecated Use `enterpriseConnections` instead.
+ */
+ samlConnections: new SamlConnectionAPI(request),
  };
 }

packages/backend/src/api/resources/Deserializer.ts

@@ -10,6 +10,7 @@ import {
  Domain,
  Email,
  EmailAddress,
+ EnterpriseConnection,
  IdPOAuthAccessToken,
  Instance,
  InstanceRestrictions,
@@ -193,6 +194,8 @@ function jsonToObject(item: any): any {
  return ProxyCheck.fromJSON(item);
  case ObjectType.RedirectUrl:
  return RedirectUrl.fromJSON(item);
+ case ObjectType.EnterpriseConnection:
+ return EnterpriseConnection.fromJSON(item);
  case ObjectType.SamlConnection:
  return SamlConnection.fromJSON(item);
  case ObjectType.SignInToken:

packages/backend/src/api/resources/EnterpriseConnection.ts

@@ -0,0 +1,64 @@
+import type { EnterpriseConnectionJSON } from './JSON';
+
+/**
+ * The Backend `EnterpriseConnection` object holds information about an enterprise connection (SAML or OAuth) for an instance or organization.
+ */
+export class EnterpriseConnection {
+ constructor(
+ /**
+ * The unique identifier for the connection.
+ */
+ readonly id: string,
+ /**
+ * The name to use as a label for the connection.
+ */
+ readonly name: string,
+ /**
+ * The domain of the enterprise. Sign-in flows using an email with this domain may use the connection.
+ */
+ readonly domains: Array<string>,
+ /**
+ * The Organization ID if the connection is scoped to an organization.
+ */
+ readonly organizationId: string | null,
+ /**
+ * Indicates whether the connection is active or not.
+ */
+ readonly active: boolean,
+ /**
+ * Indicates whether the connection syncs user attributes between the IdP and Clerk or not.
+ */
+ readonly syncUserAttributes: boolean,
+ /**
+ * Indicates whether users with an email address subdomain are allowed to use this connection or not.
+ */
+ readonly allowSubdomains: boolean,
+ /**
+ * Indicates whether additional identifications are disabled for this connection.
+ */
+ readonly disableAdditionalIdentifications: boolean,
+ /**
+ * The date when the connection was first created.
+ */
+ readonly createdAt: number,
+ /**
+ * The date when the connection was last updated.
+ */
+ readonly updatedAt: number,
+ ) {}
+
+ static fromJSON(data: EnterpriseConnectionJSON): EnterpriseConnection {
+ return new EnterpriseConnection(
+ data.id,
+ data.name,
+ data.domains,
+ data.organization_id,
+ data.active,
+ data.sync_user_attributes,
+ data.allow_subdomains,
+ data.disable_additional_identifications,
+ data.created_at,
+ data.updated_at,
+ );
+ }
+}

packages/backend/src/api/resources/JSON.ts

@@ -27,6 +27,7 @@ export const ObjectType = {
  Cookies: 'cookies',
  Domain: 'domain',
  Email: 'email',
+ EnterpriseConnection: 'enterprise_connection',
  EmailAddress: 'email_address',
  ExternalAccount: 'external_account',
  FacebookAccount: 'facebook_account',
@@ -670,6 +671,44 @@ export interface PaginatedResponseJSON {
  total_count?: number;
 }
 
+export interface EnterpriseConnectionJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.EnterpriseConnection;
+ name: string;
+ domains: string[];
+ organization_id: string | null;
+ active: boolean;
+ sync_user_attributes: boolean;
+ allow_subdomains: boolean;
+ disable_additional_identifications: boolean;
+ created_at: number;
+ updated_at: number;
+ saml_connection?: Pick<
+ SamlConnectionJSON,
+ | 'id'
+ | 'name'
+ | 'idp_entity_id'
+ | 'idp_sso_url'
+ | 'idp_certificate'
+ | 'idp_metadata_url'
+ | 'idp_metadata'
+ | 'acs_url'
+ | 'sp_entity_id'
+ | 'sp_metadata_url'
+ | 'sync_user_attributes'
+ | 'allow_subdomains'
+ | 'allow_idp_initiated'
+ >;
+ oauth_config?: {
+ id: string;
+ name: string;
+ client_id: string;
+ discovery_url: string;
+ logo_public_url: string;
+ created_at: number;
+ updated_at: number;
+ };
+}
+
 export interface SamlConnectionJSON extends ClerkResourceJSON {
  object: typeof ObjectType.SamlConnection;
  name: string;

packages/backend/src/api/resources/SamlConnection.ts

@@ -2,6 +2,7 @@ import type { AttributeMappingJSON, SamlConnectionJSON } from './JSON';
 
 /**
  * The Backend `SamlConnection` object holds information about a SAML connection for an organization.
+ * @deprecated Use `EnterpriseConnection` instead.
  */
 export class SamlConnection {
  constructor(

packages/backend/src/api/resources/index.ts

@@ -26,6 +26,7 @@ export type { SignUpStatus } from '@clerk/shared/types';
 export * from './CommercePlan';
 export * from './CommerceSubscription';
 export * from './CommerceSubscriptionItem';
+export * from './EnterpriseConnection';
 export * from './ExternalAccount';
 export * from './Feature';
 export * from './IdentificationLink';

packages/backend/src/index.ts

@@ -66,6 +66,7 @@ export type {
  DomainJSON,
  EmailJSON,
  EmailAddressJSON,
+ EnterpriseConnectionJSON,
  ExternalAccountJSON,
  IdentificationLinkJSON,
  InstanceJSON,
@@ -121,6 +122,7 @@ export type {
  CnameTarget,
  Domain,
  EmailAddress,
+ EnterpriseConnection,
  ExternalAccount,
  Feature,
  Instance,

.changeset/slick-berries-tie.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add `EnterpriseConnection` resource, allowing to create both OIDC and SAML connections

packages/backend/src/api/endpoints/EnterpriseConnectionApi.ts

@@ -0,0 +1,106 @@
+import type { ClerkPaginationRequest } from '@clerk/shared/types';
+
+import { joinPaths } from '../../util/path';
+import type { EnterpriseConnection } from '../resources';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/enterprise_connections';
+
+type EnterpriseConnectionListParams = ClerkPaginationRequest<{
+ organizationId?: string;
+ active?: boolean;
+}>;
+
+export interface EnterpriseConnectionOidcParams {
+ authUrl?: string;
+ clientId?: string;
+ clientSecret?: string;
+ discoveryUrl?: string;
+ requiresPkce?: boolean;
+ tokenUrl?: string;
+ userInfoUrl?: string;
+}
+
+export interface EnterpriseConnectionSamlAttributeMappingParams {
+ userId?: string | null;
+ emailAddress?: string | null;
+ firstName?: string | null;
+ lastName?: string | null;
+}
+
+export interface EnterpriseConnectionSamlParams {
+ allowIdpInitiated?: boolean;
+ allowSubdomains?: boolean;
+ attributeMapping?: EnterpriseConnectionSamlAttributeMappingParams;
+ forceAuthn?: boolean;
+ idpCertificate?: string;
+ idpEntityId?: string;
+ idpMetadata?: string;
+ idpMetadataUrl?: string;
+ idpSsoUrl?: string;
+}
+
+type CreateEnterpriseConnectionParams = {
+ name?: string;
+ domains?: string[];
+ organizationId?: string;
+ active?: boolean;
+ syncUserAttributes?: boolean;
+ oidc?: EnterpriseConnectionOidcParams;
+ saml?: EnterpriseConnectionSamlParams;
+};
+
+type UpdateEnterpriseConnectionParams = {
+ name?: string;
+ domains?: string[];
+ organizationId?: string;
+ active?: boolean;
+ syncUserAttributes?: boolean;
+ provider?: string;
+ oidc?: EnterpriseConnectionOidcParams;
+ saml?: EnterpriseConnectionSamlParams;
+};
+
+export class EnterpriseConnectionAPI extends AbstractAPI {
+ public async createEnterpriseConnection(params: CreateEnterpriseConnectionParams) {
+ return this.request<EnterpriseConnection>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ public async updateEnterpriseConnection(enterpriseConnectionId: string, params: UpdateEnterpriseConnectionParams) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'PATCH',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ bodyParams: params,
+ });
+ }
+
+ public async getEnterpriseConnectionList(params: EnterpriseConnectionListParams = {}) {
+ return this.request<PaginatedResourceResponse<EnterpriseConnection[]>>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ });
+ }
+
+ public async getEnterpriseConnection(enterpriseConnectionId: string) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'GET',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ });
+ }
+
+ public async deleteEnterpriseConnection(enterpriseConnectionId: string) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'DELETE',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ });
+ }
+}

packages/backend/src/api/endpoints/index.ts

@@ -9,6 +9,7 @@ export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './EnterpriseConnectionApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';
 export * from './InvitationApi';

packages/backend/src/api/factory.ts

@@ -9,6 +9,7 @@ import {
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ EnterpriseConnectionAPI,
  IdPOAuthAccessTokenApi,
  InstanceAPI,
  InvitationAPI,
@@ -67,6 +68,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),
+ enterpriseConnections: new EnterpriseConnectionAPI(request),
  idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
  buildRequest({
  ...options,
@@ -96,13 +98,17 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  phoneNumbers: new PhoneNumberAPI(request),
  proxyChecks: new ProxyCheckAPI(request),
  redirectUrls: new RedirectUrlAPI(request),
- samlConnections: new SamlConnectionAPI(request),
  sessions: new SessionAPI(request),
  signInTokens: new SignInTokenAPI(request),
  signUps: new SignUpAPI(request),
  testingTokens: new TestingTokenAPI(request),
  users: new UserAPI(request),
  waitlistEntries: new WaitlistEntryAPI(request),
  webhooks: new WebhookAPI(request),
+
+ /**
+ * @deprecated Use `enterpriseConnections` instead.
+ */
+ samlConnections: new SamlConnectionAPI(request),
  };
 }

packages/backend/src/api/resources/Deserializer.ts

@@ -10,6 +10,7 @@ import {
  Domain,
  Email,
  EmailAddress,
+ EnterpriseConnection,
  IdPOAuthAccessToken,
  Instance,
  InstanceRestrictions,
@@ -193,6 +194,8 @@ function jsonToObject(item: any): any {
  return ProxyCheck.fromJSON(item);
  case ObjectType.RedirectUrl:
  return RedirectUrl.fromJSON(item);
+ case ObjectType.EnterpriseConnection:
+ return EnterpriseConnection.fromJSON(item);
  case ObjectType.SamlConnection:
  return SamlConnection.fromJSON(item);
  case ObjectType.SignInToken:

packages/backend/src/api/resources/EnterpriseConnection.ts

@@ -0,0 +1,64 @@
+import type { EnterpriseConnectionJSON } from './JSON';
+
+/**
+ * The Backend `EnterpriseConnection` object holds information about an enterprise connection (SAML or OAuth) for an instance or organization.
+ */
+export class EnterpriseConnection {
+ constructor(
+ /**
+ * The unique identifier for the connection.
+ */
+ readonly id: string,
+ /**
+ * The name to use as a label for the connection.
+ */
+ readonly name: string,
+ /**
+ * The domain of the enterprise. Sign-in flows using an email with this domain may use the connection.
+ */
+ readonly domains: Array<string>,
+ /**
+ * The Organization ID if the connection is scoped to an organization.
+ */
+ readonly organizationId: string | null,
+ /**
+ * Indicates whether the connection is active or not.
+ */
+ readonly active: boolean,
+ /**
+ * Indicates whether the connection syncs user attributes between the IdP and Clerk or not.
+ */
+ readonly syncUserAttributes: boolean,
+ /**
+ * Indicates whether users with an email address subdomain are allowed to use this connection or not.
+ */
+ readonly allowSubdomains: boolean,
+ /**
+ * Indicates whether additional identifications are disabled for this connection.
+ */
+ readonly disableAdditionalIdentifications: boolean,
+ /**
+ * The date when the connection was first created.
+ */
+ readonly createdAt: number,
+ /**
+ * The date when the connection was last updated.
+ */
+ readonly updatedAt: number,
+ ) {}
+
+ static fromJSON(data: EnterpriseConnectionJSON): EnterpriseConnection {
+ return new EnterpriseConnection(
+ data.id,
+ data.name,
+ data.domains,
+ data.organization_id,
+ data.active,
+ data.sync_user_attributes,
+ data.allow_subdomains,
+ data.disable_additional_identifications,
+ data.created_at,
+ data.updated_at,
+ );
+ }
+}

packages/backend/src/api/resources/JSON.ts

@@ -27,6 +27,7 @@ export const ObjectType = {
  Cookies: 'cookies',
  Domain: 'domain',
  Email: 'email',
+ EnterpriseConnection: 'enterprise_connection',
  EmailAddress: 'email_address',
  ExternalAccount: 'external_account',
  FacebookAccount: 'facebook_account',
@@ -670,6 +671,44 @@ export interface PaginatedResponseJSON {
  total_count?: number;
 }
 
+export interface EnterpriseConnectionJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.EnterpriseConnection;
+ name: string;
+ domains: string[];
+ organization_id: string | null;
+ active: boolean;
+ sync_user_attributes: boolean;
+ allow_subdomains: boolean;
+ disable_additional_identifications: boolean;
+ created_at: number;
+ updated_at: number;
+ saml_connection?: Pick<
+ SamlConnectionJSON,
+ | 'id'
+ | 'name'
+ | 'idp_entity_id'
+ | 'idp_sso_url'
+ | 'idp_certificate'
+ | 'idp_metadata_url'
+ | 'idp_metadata'
+ | 'acs_url'
+ | 'sp_entity_id'
+ | 'sp_metadata_url'
+ | 'sync_user_attributes'
+ | 'allow_subdomains'
+ | 'allow_idp_initiated'
+ >;
+ oauth_config?: {
+ id: string;
+ name: string;
+ client_id: string;
+ discovery_url: string;
+ logo_public_url: string;
+ created_at: number;
+ updated_at: number;
+ };
+}
+
 export interface SamlConnectionJSON extends ClerkResourceJSON {
  object: typeof ObjectType.SamlConnection;
  name: string;

packages/backend/src/api/resources/SamlConnection.ts

@@ -2,6 +2,7 @@ import type { AttributeMappingJSON, SamlConnectionJSON } from './JSON';
 
 /**
  * The Backend `SamlConnection` object holds information about a SAML connection for an organization.
+ * @deprecated Use `EnterpriseConnection` instead.
  */
 export class SamlConnection {
  constructor(

packages/backend/src/api/resources/index.ts

@@ -26,6 +26,7 @@ export type { SignUpStatus } from '@clerk/shared/types';
 export * from './CommercePlan';
 export * from './CommerceSubscription';
 export * from './CommerceSubscriptionItem';
+export * from './EnterpriseConnection';
 export * from './ExternalAccount';
 export * from './Feature';
 export * from './IdentificationLink';

packages/backend/src/index.ts

@@ -66,6 +66,7 @@ export type {
  DomainJSON,
  EmailJSON,
  EmailAddressJSON,
+ EnterpriseConnectionJSON,
  ExternalAccountJSON,
  IdentificationLinkJSON,
  InstanceJSON,
@@ -121,6 +122,7 @@ export type {
  CnameTarget,
  Domain,
  EmailAddress,
+ EnterpriseConnection,
  ExternalAccount,
  Feature,
  Instance,

.changeset/slick-berries-tie.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add `EnterpriseConnection` resource, allowing to create both OIDC and SAML connections

packages/backend/src/api/endpoints/EnterpriseConnectionApi.ts

@@ -0,0 +1,106 @@
+import type { ClerkPaginationRequest } from '@clerk/shared/types';
+
+import { joinPaths } from '../../util/path';
+import type { EnterpriseConnection } from '../resources';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/enterprise_connections';
+
+type EnterpriseConnectionListParams = ClerkPaginationRequest<{
+ organizationId?: string;
+ active?: boolean;
+}>;
+
+export interface EnterpriseConnectionOidcParams {
+ authUrl?: string;
+ clientId?: string;
+ clientSecret?: string;
+ discoveryUrl?: string;
+ requiresPkce?: boolean;
+ tokenUrl?: string;
+ userInfoUrl?: string;
+}
+
+export interface EnterpriseConnectionSamlAttributeMappingParams {
+ userId?: string | null;
+ emailAddress?: string | null;
+ firstName?: string | null;
+ lastName?: string | null;
+}
+
+export interface EnterpriseConnectionSamlParams {
+ allowIdpInitiated?: boolean;
+ allowSubdomains?: boolean;
+ attributeMapping?: EnterpriseConnectionSamlAttributeMappingParams;
+ forceAuthn?: boolean;
+ idpCertificate?: string;
+ idpEntityId?: string;
+ idpMetadata?: string;
+ idpMetadataUrl?: string;
+ idpSsoUrl?: string;
+}
+
+type CreateEnterpriseConnectionParams = {
+ name?: string;
+ domains?: string[];
+ organizationId?: string;
+ active?: boolean;
+ syncUserAttributes?: boolean;
+ oidc?: EnterpriseConnectionOidcParams;
+ saml?: EnterpriseConnectionSamlParams;
+};
+
+type UpdateEnterpriseConnectionParams = {
+ name?: string;
+ domains?: string[];
+ organizationId?: string;
+ active?: boolean;
+ syncUserAttributes?: boolean;
+ provider?: string;
+ oidc?: EnterpriseConnectionOidcParams;
+ saml?: EnterpriseConnectionSamlParams;
+};
+
+export class EnterpriseConnectionAPI extends AbstractAPI {
+ public async createEnterpriseConnection(params: CreateEnterpriseConnectionParams) {
+ return this.request<EnterpriseConnection>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ public async updateEnterpriseConnection(enterpriseConnectionId: string, params: UpdateEnterpriseConnectionParams) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'PATCH',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ bodyParams: params,
+ });
+ }
+
+ public async getEnterpriseConnectionList(params: EnterpriseConnectionListParams = {}) {
+ return this.request<PaginatedResourceResponse<EnterpriseConnection[]>>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ });
+ }
+
+ public async getEnterpriseConnection(enterpriseConnectionId: string) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'GET',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ });
+ }
+
+ public async deleteEnterpriseConnection(enterpriseConnectionId: string) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'DELETE',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ });
+ }
+}

packages/backend/src/api/endpoints/index.ts

@@ -9,6 +9,7 @@ export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './EnterpriseConnectionApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';
 export * from './InvitationApi';

packages/backend/src/api/factory.ts

@@ -9,6 +9,7 @@ import {
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ EnterpriseConnectionAPI,
  IdPOAuthAccessTokenApi,
  InstanceAPI,
  InvitationAPI,
@@ -67,6 +68,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),
+ enterpriseConnections: new EnterpriseConnectionAPI(request),
  idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
  buildRequest({
  ...options,
@@ -96,13 +98,17 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  phoneNumbers: new PhoneNumberAPI(request),
  proxyChecks: new ProxyCheckAPI(request),
  redirectUrls: new RedirectUrlAPI(request),
- samlConnections: new SamlConnectionAPI(request),
  sessions: new SessionAPI(request),
  signInTokens: new SignInTokenAPI(request),
  signUps: new SignUpAPI(request),
  testingTokens: new TestingTokenAPI(request),
  users: new UserAPI(request),
  waitlistEntries: new WaitlistEntryAPI(request),
  webhooks: new WebhookAPI(request),
+
+ /**
+ * @deprecated Use `enterpriseConnections` instead.
+ */
+ samlConnections: new SamlConnectionAPI(request),
  };
 }

packages/backend/src/api/resources/Deserializer.ts

@@ -10,6 +10,7 @@ import {
  Domain,
  Email,
  EmailAddress,
+ EnterpriseConnection,
  IdPOAuthAccessToken,
  Instance,
  InstanceRestrictions,
@@ -193,6 +194,8 @@ function jsonToObject(item: any): any {
  return ProxyCheck.fromJSON(item);
  case ObjectType.RedirectUrl:
  return RedirectUrl.fromJSON(item);
+ case ObjectType.EnterpriseConnection:
+ return EnterpriseConnection.fromJSON(item);
  case ObjectType.SamlConnection:
  return SamlConnection.fromJSON(item);
  case ObjectType.SignInToken:

packages/backend/src/api/resources/EnterpriseConnection.ts

@@ -0,0 +1,64 @@
+import type { EnterpriseConnectionJSON } from './JSON';
+
+/**
+ * The Backend `EnterpriseConnection` object holds information about an enterprise connection (SAML or OAuth) for an instance or organization.
+ */
+export class EnterpriseConnection {
+ constructor(
+ /**
+ * The unique identifier for the connection.
+ */
+ readonly id: string,
+ /**
+ * The name to use as a label for the connection.
+ */
+ readonly name: string,
+ /**
+ * The domain of the enterprise. Sign-in flows using an email with this domain may use the connection.
+ */
+ readonly domains: Array<string>,
+ /**
+ * The Organization ID if the connection is scoped to an organization.
+ */
+ readonly organizationId: string | null,
+ /**
+ * Indicates whether the connection is active or not.
+ */
+ readonly active: boolean,
+ /**
+ * Indicates whether the connection syncs user attributes between the IdP and Clerk or not.
+ */
+ readonly syncUserAttributes: boolean,
+ /**
+ * Indicates whether users with an email address subdomain are allowed to use this connection or not.
+ */
+ readonly allowSubdomains: boolean,
+ /**
+ * Indicates whether additional identifications are disabled for this connection.
+ */
+ readonly disableAdditionalIdentifications: boolean,
+ /**
+ * The date when the connection was first created.
+ */
+ readonly createdAt: number,
+ /**
+ * The date when the connection was last updated.
+ */
+ readonly updatedAt: number,
+ ) {}
+
+ static fromJSON(data: EnterpriseConnectionJSON): EnterpriseConnection {
+ return new EnterpriseConnection(
+ data.id,
+ data.name,
+ data.domains,
+ data.organization_id,
+ data.active,
+ data.sync_user_attributes,
+ data.allow_subdomains,
+ data.disable_additional_identifications,
+ data.created_at,
+ data.updated_at,
+ );
+ }
+}

packages/backend/src/api/resources/JSON.ts

@@ -27,6 +27,7 @@ export const ObjectType = {
  Cookies: 'cookies',
  Domain: 'domain',
  Email: 'email',
+ EnterpriseConnection: 'enterprise_connection',
  EmailAddress: 'email_address',
  ExternalAccount: 'external_account',
  FacebookAccount: 'facebook_account',
@@ -670,6 +671,44 @@ export interface PaginatedResponseJSON {
  total_count?: number;
 }
 
+export interface EnterpriseConnectionJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.EnterpriseConnection;
+ name: string;
+ domains: string[];
+ organization_id: string | null;
+ active: boolean;
+ sync_user_attributes: boolean;
+ allow_subdomains: boolean;
+ disable_additional_identifications: boolean;
+ created_at: number;
+ updated_at: number;
+ saml_connection?: Pick<
+ SamlConnectionJSON,
+ | 'id'
+ | 'name'
+ | 'idp_entity_id'
+ | 'idp_sso_url'
+ | 'idp_certificate'
+ | 'idp_metadata_url'
+ | 'idp_metadata'
+ | 'acs_url'
+ | 'sp_entity_id'
+ | 'sp_metadata_url'
+ | 'sync_user_attributes'
+ | 'allow_subdomains'
+ | 'allow_idp_initiated'
+ >;
+ oauth_config?: {
+ id: string;
+ name: string;
+ client_id: string;
+ discovery_url: string;
+ logo_public_url: string;
+ created_at: number;
+ updated_at: number;
+ };
+}
+
 export interface SamlConnectionJSON extends ClerkResourceJSON {
  object: typeof ObjectType.SamlConnection;
  name: string;

packages/backend/src/api/resources/SamlConnection.ts

@@ -2,6 +2,7 @@ import type { AttributeMappingJSON, SamlConnectionJSON } from './JSON';
 
 /**
  * The Backend `SamlConnection` object holds information about a SAML connection for an organization.
+ * @deprecated Use `EnterpriseConnection` instead.
  */
 export class SamlConnection {
  constructor(

packages/backend/src/api/resources/index.ts

@@ -26,6 +26,7 @@ export type { SignUpStatus } from '@clerk/shared/types';
 export * from './CommercePlan';
 export * from './CommerceSubscription';
 export * from './CommerceSubscriptionItem';
+export * from './EnterpriseConnection';
 export * from './ExternalAccount';
 export * from './Feature';
 export * from './IdentificationLink';

packages/backend/src/index.ts

@@ -66,6 +66,7 @@ export type {
  DomainJSON,
  EmailJSON,
  EmailAddressJSON,
+ EnterpriseConnectionJSON,
  ExternalAccountJSON,
  IdentificationLinkJSON,
  InstanceJSON,
@@ -121,6 +122,7 @@ export type {
  CnameTarget,
  Domain,
  EmailAddress,
+ EnterpriseConnection,
  ExternalAccount,
  Feature,
  Instance,

.changeset/slick-berries-tie.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add `EnterpriseConnection` resource, allowing to create both OIDC and SAML connections

packages/backend/src/api/endpoints/EnterpriseConnectionApi.ts

@@ -0,0 +1,106 @@
+import type { ClerkPaginationRequest } from '@clerk/shared/types';
+
+import { joinPaths } from '../../util/path';
+import type { EnterpriseConnection } from '../resources';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/enterprise_connections';
+
+type EnterpriseConnectionListParams = ClerkPaginationRequest<{
+ organizationId?: string;
+ active?: boolean;
+}>;
+
+export interface EnterpriseConnectionOidcParams {
+ authUrl?: string;
+ clientId?: string;
+ clientSecret?: string;
+ discoveryUrl?: string;
+ requiresPkce?: boolean;
+ tokenUrl?: string;
+ userInfoUrl?: string;
+}
+
+export interface EnterpriseConnectionSamlAttributeMappingParams {
+ userId?: string | null;
+ emailAddress?: string | null;
+ firstName?: string | null;
+ lastName?: string | null;
+}
+
+export interface EnterpriseConnectionSamlParams {
+ allowIdpInitiated?: boolean;
+ allowSubdomains?: boolean;
+ attributeMapping?: EnterpriseConnectionSamlAttributeMappingParams;
+ forceAuthn?: boolean;
+ idpCertificate?: string;
+ idpEntityId?: string;
+ idpMetadata?: string;
+ idpMetadataUrl?: string;
+ idpSsoUrl?: string;
+}
+
+type CreateEnterpriseConnectionParams = {
+ name?: string;
+ domains?: string[];
+ organizationId?: string;
+ active?: boolean;
+ syncUserAttributes?: boolean;
+ oidc?: EnterpriseConnectionOidcParams;
+ saml?: EnterpriseConnectionSamlParams;
+};
+
+type UpdateEnterpriseConnectionParams = {
+ name?: string;
+ domains?: string[];
+ organizationId?: string;
+ active?: boolean;
+ syncUserAttributes?: boolean;
+ provider?: string;
+ oidc?: EnterpriseConnectionOidcParams;
+ saml?: EnterpriseConnectionSamlParams;
+};
+
+export class EnterpriseConnectionAPI extends AbstractAPI {
+ public async createEnterpriseConnection(params: CreateEnterpriseConnectionParams) {
+ return this.request<EnterpriseConnection>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ public async updateEnterpriseConnection(enterpriseConnectionId: string, params: UpdateEnterpriseConnectionParams) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'PATCH',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ bodyParams: params,
+ });
+ }
+
+ public async getEnterpriseConnectionList(params: EnterpriseConnectionListParams = {}) {
+ return this.request<PaginatedResourceResponse<EnterpriseConnection[]>>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ });
+ }
+
+ public async getEnterpriseConnection(enterpriseConnectionId: string) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'GET',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ });
+ }
+
+ public async deleteEnterpriseConnection(enterpriseConnectionId: string) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'DELETE',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ });
+ }
+}

packages/backend/src/api/endpoints/index.ts

@@ -9,6 +9,7 @@ export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './EnterpriseConnectionApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';
 export * from './InvitationApi';

packages/backend/src/api/factory.ts

@@ -9,6 +9,7 @@ import {
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ EnterpriseConnectionAPI,
  IdPOAuthAccessTokenApi,
  InstanceAPI,
  InvitationAPI,
@@ -67,6 +68,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),
+ enterpriseConnections: new EnterpriseConnectionAPI(request),
  idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
  buildRequest({
  ...options,
@@ -96,13 +98,17 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  phoneNumbers: new PhoneNumberAPI(request),
  proxyChecks: new ProxyCheckAPI(request),
  redirectUrls: new RedirectUrlAPI(request),
- samlConnections: new SamlConnectionAPI(request),
  sessions: new SessionAPI(request),
  signInTokens: new SignInTokenAPI(request),
  signUps: new SignUpAPI(request),
  testingTokens: new TestingTokenAPI(request),
  users: new UserAPI(request),
  waitlistEntries: new WaitlistEntryAPI(request),
  webhooks: new WebhookAPI(request),
+
+ /**
+ * @deprecated Use `enterpriseConnections` instead.
+ */
+ samlConnections: new SamlConnectionAPI(request),
  };
 }

packages/backend/src/api/resources/Deserializer.ts

@@ -10,6 +10,7 @@ import {
  Domain,
  Email,
  EmailAddress,
+ EnterpriseConnection,
  IdPOAuthAccessToken,
  Instance,
  InstanceRestrictions,
@@ -193,6 +194,8 @@ function jsonToObject(item: any): any {
  return ProxyCheck.fromJSON(item);
  case ObjectType.RedirectUrl:
  return RedirectUrl.fromJSON(item);
+ case ObjectType.EnterpriseConnection:
+ return EnterpriseConnection.fromJSON(item);
  case ObjectType.SamlConnection:
  return SamlConnection.fromJSON(item);
  case ObjectType.SignInToken:

packages/backend/src/api/resources/EnterpriseConnection.ts

@@ -0,0 +1,64 @@
+import type { EnterpriseConnectionJSON } from './JSON';
+
+/**
+ * The Backend `EnterpriseConnection` object holds information about an enterprise connection (SAML or OAuth) for an instance or organization.
+ */
+export class EnterpriseConnection {
+ constructor(
+ /**
+ * The unique identifier for the connection.
+ */
+ readonly id: string,
+ /**
+ * The name to use as a label for the connection.
+ */
+ readonly name: string,
+ /**
+ * The domain of the enterprise. Sign-in flows using an email with this domain may use the connection.
+ */
+ readonly domains: Array<string>,
+ /**
+ * The Organization ID if the connection is scoped to an organization.
+ */
+ readonly organizationId: string | null,
+ /**
+ * Indicates whether the connection is active or not.
+ */
+ readonly active: boolean,
+ /**
+ * Indicates whether the connection syncs user attributes between the IdP and Clerk or not.
+ */
+ readonly syncUserAttributes: boolean,
+ /**
+ * Indicates whether users with an email address subdomain are allowed to use this connection or not.
+ */
+ readonly allowSubdomains: boolean,
+ /**
+ * Indicates whether additional identifications are disabled for this connection.
+ */
+ readonly disableAdditionalIdentifications: boolean,
+ /**
+ * The date when the connection was first created.
+ */
+ readonly createdAt: number,
+ /**
+ * The date when the connection was last updated.
+ */
+ readonly updatedAt: number,
+ ) {}
+
+ static fromJSON(data: EnterpriseConnectionJSON): EnterpriseConnection {
+ return new EnterpriseConnection(
+ data.id,
+ data.name,
+ data.domains,
+ data.organization_id,
+ data.active,
+ data.sync_user_attributes,
+ data.allow_subdomains,
+ data.disable_additional_identifications,
+ data.created_at,
+ data.updated_at,
+ );
+ }
+}

packages/backend/src/api/resources/JSON.ts

@@ -27,6 +27,7 @@ export const ObjectType = {
  Cookies: 'cookies',
  Domain: 'domain',
  Email: 'email',
+ EnterpriseConnection: 'enterprise_connection',
  EmailAddress: 'email_address',
  ExternalAccount: 'external_account',
  FacebookAccount: 'facebook_account',
@@ -670,6 +671,44 @@ export interface PaginatedResponseJSON {
  total_count?: number;
 }
 
+export interface EnterpriseConnectionJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.EnterpriseConnection;
+ name: string;
+ domains: string[];
+ organization_id: string | null;
+ active: boolean;
+ sync_user_attributes: boolean;
+ allow_subdomains: boolean;
+ disable_additional_identifications: boolean;
+ created_at: number;
+ updated_at: number;
+ saml_connection?: Pick<
+ SamlConnectionJSON,
+ | 'id'
+ | 'name'
+ | 'idp_entity_id'
+ | 'idp_sso_url'
+ | 'idp_certificate'
+ | 'idp_metadata_url'
+ | 'idp_metadata'
+ | 'acs_url'
+ | 'sp_entity_id'
+ | 'sp_metadata_url'
+ | 'sync_user_attributes'
+ | 'allow_subdomains'
+ | 'allow_idp_initiated'
+ >;
+ oauth_config?: {
+ id: string;
+ name: string;
+ client_id: string;
+ discovery_url: string;
+ logo_public_url: string;
+ created_at: number;
+ updated_at: number;
+ };
+}
+
 export interface SamlConnectionJSON extends ClerkResourceJSON {
  object: typeof ObjectType.SamlConnection;
  name: string;

packages/backend/src/api/resources/SamlConnection.ts

@@ -2,6 +2,7 @@ import type { AttributeMappingJSON, SamlConnectionJSON } from './JSON';
 
 /**
  * The Backend `SamlConnection` object holds information about a SAML connection for an organization.
+ * @deprecated Use `EnterpriseConnection` instead.
  */
 export class SamlConnection {
  constructor(

packages/backend/src/api/resources/index.ts

@@ -26,6 +26,7 @@ export type { SignUpStatus } from '@clerk/shared/types';
 export * from './CommercePlan';
 export * from './CommerceSubscription';
 export * from './CommerceSubscriptionItem';
+export * from './EnterpriseConnection';
 export * from './ExternalAccount';
 export * from './Feature';
 export * from './IdentificationLink';

packages/backend/src/index.ts

@@ -66,6 +66,7 @@ export type {
  DomainJSON,
  EmailJSON,
  EmailAddressJSON,
+ EnterpriseConnectionJSON,
  ExternalAccountJSON,
  IdentificationLinkJSON,
  InstanceJSON,
@@ -121,6 +122,7 @@ export type {
  CnameTarget,
  Domain,
  EmailAddress,
+ EnterpriseConnection,
  ExternalAccount,
  Feature,
  Instance,

.changeset/slick-berries-tie.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add `EnterpriseConnection` resource, allowing to create both OIDC and SAML connections

packages/backend/src/api/endpoints/EnterpriseConnectionApi.ts

@@ -0,0 +1,106 @@
+import type { ClerkPaginationRequest } from '@clerk/shared/types';
+
+import { joinPaths } from '../../util/path';
+import type { EnterpriseConnection } from '../resources';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/enterprise_connections';
+
+type EnterpriseConnectionListParams = ClerkPaginationRequest<{
+ organizationId?: string;
+ active?: boolean;
+}>;
+
+export interface EnterpriseConnectionOidcParams {
+ authUrl?: string;
+ clientId?: string;
+ clientSecret?: string;
+ discoveryUrl?: string;
+ requiresPkce?: boolean;
+ tokenUrl?: string;
+ userInfoUrl?: string;
+}
+
+export interface EnterpriseConnectionSamlAttributeMappingParams {
+ userId?: string | null;
+ emailAddress?: string | null;
+ firstName?: string | null;
+ lastName?: string | null;
+}
+
+export interface EnterpriseConnectionSamlParams {
+ allowIdpInitiated?: boolean;
+ allowSubdomains?: boolean;
+ attributeMapping?: EnterpriseConnectionSamlAttributeMappingParams;
+ forceAuthn?: boolean;
+ idpCertificate?: string;
+ idpEntityId?: string;
+ idpMetadata?: string;
+ idpMetadataUrl?: string;
+ idpSsoUrl?: string;
+}
+
+type CreateEnterpriseConnectionParams = {
+ name?: string;
+ domains?: string[];
+ organizationId?: string;
+ active?: boolean;
+ syncUserAttributes?: boolean;
+ oidc?: EnterpriseConnectionOidcParams;
+ saml?: EnterpriseConnectionSamlParams;
+};
+
+type UpdateEnterpriseConnectionParams = {
+ name?: string;
+ domains?: string[];
+ organizationId?: string;
+ active?: boolean;
+ syncUserAttributes?: boolean;
+ provider?: string;
+ oidc?: EnterpriseConnectionOidcParams;
+ saml?: EnterpriseConnectionSamlParams;
+};
+
+export class EnterpriseConnectionAPI extends AbstractAPI {
+ public async createEnterpriseConnection(params: CreateEnterpriseConnectionParams) {
+ return this.request<EnterpriseConnection>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ public async updateEnterpriseConnection(enterpriseConnectionId: string, params: UpdateEnterpriseConnectionParams) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'PATCH',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ bodyParams: params,
+ });
+ }
+
+ public async getEnterpriseConnectionList(params: EnterpriseConnectionListParams = {}) {
+ return this.request<PaginatedResourceResponse<EnterpriseConnection[]>>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ });
+ }
+
+ public async getEnterpriseConnection(enterpriseConnectionId: string) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'GET',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ });
+ }
+
+ public async deleteEnterpriseConnection(enterpriseConnectionId: string) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'DELETE',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ });
+ }
+}

packages/backend/src/api/endpoints/index.ts

@@ -9,6 +9,7 @@ export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './EnterpriseConnectionApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';
 export * from './InvitationApi';

packages/backend/src/api/factory.ts

@@ -9,6 +9,7 @@ import {
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ EnterpriseConnectionAPI,
  IdPOAuthAccessTokenApi,
  InstanceAPI,
  InvitationAPI,
@@ -67,6 +68,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),
+ enterpriseConnections: new EnterpriseConnectionAPI(request),
  idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
  buildRequest({
  ...options,
@@ -96,13 +98,17 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  phoneNumbers: new PhoneNumberAPI(request),
  proxyChecks: new ProxyCheckAPI(request),
  redirectUrls: new RedirectUrlAPI(request),
- samlConnections: new SamlConnectionAPI(request),
  sessions: new SessionAPI(request),
  signInTokens: new SignInTokenAPI(request),
  signUps: new SignUpAPI(request),
  testingTokens: new TestingTokenAPI(request),
  users: new UserAPI(request),
  waitlistEntries: new WaitlistEntryAPI(request),
  webhooks: new WebhookAPI(request),
+
+ /**
+ * @deprecated Use `enterpriseConnections` instead.
+ */
+ samlConnections: new SamlConnectionAPI(request),
  };
 }

packages/backend/src/api/resources/Deserializer.ts

@@ -10,6 +10,7 @@ import {
  Domain,
  Email,
  EmailAddress,
+ EnterpriseConnection,
  IdPOAuthAccessToken,
  Instance,
  InstanceRestrictions,
@@ -193,6 +194,8 @@ function jsonToObject(item: any): any {
  return ProxyCheck.fromJSON(item);
  case ObjectType.RedirectUrl:
  return RedirectUrl.fromJSON(item);
+ case ObjectType.EnterpriseConnection:
+ return EnterpriseConnection.fromJSON(item);
  case ObjectType.SamlConnection:
  return SamlConnection.fromJSON(item);
  case ObjectType.SignInToken:

packages/backend/src/api/resources/EnterpriseConnection.ts

@@ -0,0 +1,64 @@
+import type { EnterpriseConnectionJSON } from './JSON';
+
+/**
+ * The Backend `EnterpriseConnection` object holds information about an enterprise connection (SAML or OAuth) for an instance or organization.
+ */
+export class EnterpriseConnection {
+ constructor(
+ /**
+ * The unique identifier for the connection.
+ */
+ readonly id: string,
+ /**
+ * The name to use as a label for the connection.
+ */
+ readonly name: string,
+ /**
+ * The domain of the enterprise. Sign-in flows using an email with this domain may use the connection.
+ */
+ readonly domains: Array<string>,
+ /**
+ * The Organization ID if the connection is scoped to an organization.
+ */
+ readonly organizationId: string | null,
+ /**
+ * Indicates whether the connection is active or not.
+ */
+ readonly active: boolean,
+ /**
+ * Indicates whether the connection syncs user attributes between the IdP and Clerk or not.
+ */
+ readonly syncUserAttributes: boolean,
+ /**
+ * Indicates whether users with an email address subdomain are allowed to use this connection or not.
+ */
+ readonly allowSubdomains: boolean,
+ /**
+ * Indicates whether additional identifications are disabled for this connection.
+ */
+ readonly disableAdditionalIdentifications: boolean,
+ /**
+ * The date when the connection was first created.
+ */
+ readonly createdAt: number,
+ /**
+ * The date when the connection was last updated.
+ */
+ readonly updatedAt: number,
+ ) {}
+
+ static fromJSON(data: EnterpriseConnectionJSON): EnterpriseConnection {
+ return new EnterpriseConnection(
+ data.id,
+ data.name,
+ data.domains,
+ data.organization_id,
+ data.active,
+ data.sync_user_attributes,
+ data.allow_subdomains,
+ data.disable_additional_identifications,
+ data.created_at,
+ data.updated_at,
+ );
+ }
+}

packages/backend/src/api/resources/JSON.ts

@@ -27,6 +27,7 @@ export const ObjectType = {
  Cookies: 'cookies',
  Domain: 'domain',
  Email: 'email',
+ EnterpriseConnection: 'enterprise_connection',
  EmailAddress: 'email_address',
  ExternalAccount: 'external_account',
  FacebookAccount: 'facebook_account',
@@ -670,6 +671,44 @@ export interface PaginatedResponseJSON {
  total_count?: number;
 }
 
+export interface EnterpriseConnectionJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.EnterpriseConnection;
+ name: string;
+ domains: string[];
+ organization_id: string | null;
+ active: boolean;
+ sync_user_attributes: boolean;
+ allow_subdomains: boolean;
+ disable_additional_identifications: boolean;
+ created_at: number;
+ updated_at: number;
+ saml_connection?: Pick<
+ SamlConnectionJSON,
+ | 'id'
+ | 'name'
+ | 'idp_entity_id'
+ | 'idp_sso_url'
+ | 'idp_certificate'
+ | 'idp_metadata_url'
+ | 'idp_metadata'
+ | 'acs_url'
+ | 'sp_entity_id'
+ | 'sp_metadata_url'
+ | 'sync_user_attributes'
+ | 'allow_subdomains'
+ | 'allow_idp_initiated'
+ >;
+ oauth_config?: {
+ id: string;
+ name: string;
+ client_id: string;
+ discovery_url: string;
+ logo_public_url: string;
+ created_at: number;
+ updated_at: number;
+ };
+}
+
 export interface SamlConnectionJSON extends ClerkResourceJSON {
  object: typeof ObjectType.SamlConnection;
  name: string;

packages/backend/src/api/resources/SamlConnection.ts

@@ -2,6 +2,7 @@ import type { AttributeMappingJSON, SamlConnectionJSON } from './JSON';
 
 /**
  * The Backend `SamlConnection` object holds information about a SAML connection for an organization.
+ * @deprecated Use `EnterpriseConnection` instead.
  */
 export class SamlConnection {
  constructor(

packages/backend/src/api/resources/index.ts

@@ -26,6 +26,7 @@ export type { SignUpStatus } from '@clerk/shared/types';
 export * from './CommercePlan';
 export * from './CommerceSubscription';
 export * from './CommerceSubscriptionItem';
+export * from './EnterpriseConnection';
 export * from './ExternalAccount';
 export * from './Feature';
 export * from './IdentificationLink';

packages/backend/src/index.ts

@@ -66,6 +66,7 @@ export type {
  DomainJSON,
  EmailJSON,
  EmailAddressJSON,
+ EnterpriseConnectionJSON,
  ExternalAccountJSON,
  IdentificationLinkJSON,
  InstanceJSON,
@@ -121,6 +122,7 @@ export type {
  CnameTarget,
  Domain,
  EmailAddress,
+ EnterpriseConnection,
  ExternalAccount,
  Feature,
  Instance,

.changeset/slick-berries-tie.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add `EnterpriseConnection` resource, allowing to create both OIDC and SAML connections

packages/backend/src/api/endpoints/EnterpriseConnectionApi.ts

@@ -0,0 +1,106 @@
+import type { ClerkPaginationRequest } from '@clerk/shared/types';
+
+import { joinPaths } from '../../util/path';
+import type { EnterpriseConnection } from '../resources';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/enterprise_connections';
+
+type EnterpriseConnectionListParams = ClerkPaginationRequest<{
+ organizationId?: string;
+ active?: boolean;
+}>;
+
+export interface EnterpriseConnectionOidcParams {
+ authUrl?: string;
+ clientId?: string;
+ clientSecret?: string;
+ discoveryUrl?: string;
+ requiresPkce?: boolean;
+ tokenUrl?: string;
+ userInfoUrl?: string;
+}
+
+export interface EnterpriseConnectionSamlAttributeMappingParams {
+ userId?: string | null;
+ emailAddress?: string | null;
+ firstName?: string | null;
+ lastName?: string | null;
+}
+
+export interface EnterpriseConnectionSamlParams {
+ allowIdpInitiated?: boolean;
+ allowSubdomains?: boolean;
+ attributeMapping?: EnterpriseConnectionSamlAttributeMappingParams;
+ forceAuthn?: boolean;
+ idpCertificate?: string;
+ idpEntityId?: string;
+ idpMetadata?: string;
+ idpMetadataUrl?: string;
+ idpSsoUrl?: string;
+}
+
+type CreateEnterpriseConnectionParams = {
+ name?: string;
+ domains?: string[];
+ organizationId?: string;
+ active?: boolean;
+ syncUserAttributes?: boolean;
+ oidc?: EnterpriseConnectionOidcParams;
+ saml?: EnterpriseConnectionSamlParams;
+};
+
+type UpdateEnterpriseConnectionParams = {
+ name?: string;
+ domains?: string[];
+ organizationId?: string;
+ active?: boolean;
+ syncUserAttributes?: boolean;
+ provider?: string;
+ oidc?: EnterpriseConnectionOidcParams;
+ saml?: EnterpriseConnectionSamlParams;
+};
+
+export class EnterpriseConnectionAPI extends AbstractAPI {
+ public async createEnterpriseConnection(params: CreateEnterpriseConnectionParams) {
+ return this.request<EnterpriseConnection>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ public async updateEnterpriseConnection(enterpriseConnectionId: string, params: UpdateEnterpriseConnectionParams) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'PATCH',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ bodyParams: params,
+ });
+ }
+
+ public async getEnterpriseConnectionList(params: EnterpriseConnectionListParams = {}) {
+ return this.request<PaginatedResourceResponse<EnterpriseConnection[]>>({
+ method: 'GET',
+ path: basePath,
+ queryParams: params,
+ });
+ }
+
+ public async getEnterpriseConnection(enterpriseConnectionId: string) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'GET',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ });
+ }
+
+ public async deleteEnterpriseConnection(enterpriseConnectionId: string) {
+ this.requireId(enterpriseConnectionId);
+ return this.request<EnterpriseConnection>({
+ method: 'DELETE',
+ path: joinPaths(basePath, enterpriseConnectionId),
+ });
+ }
+}

packages/backend/src/api/endpoints/index.ts

@@ -9,6 +9,7 @@ export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './EnterpriseConnectionApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';
 export * from './InvitationApi';

packages/backend/src/api/factory.ts

@@ -9,6 +9,7 @@ import {
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ EnterpriseConnectionAPI,
  IdPOAuthAccessTokenApi,
  InstanceAPI,
  InvitationAPI,
@@ -67,6 +68,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),
+ enterpriseConnections: new EnterpriseConnectionAPI(request),
  idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
  buildRequest({
  ...options,
@@ -96,13 +98,17 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  phoneNumbers: new PhoneNumberAPI(request),
  proxyChecks: new ProxyCheckAPI(request),
  redirectUrls: new RedirectUrlAPI(request),
- samlConnections: new SamlConnectionAPI(request),
  sessions: new SessionAPI(request),
  signInTokens: new SignInTokenAPI(request),
  signUps: new SignUpAPI(request),
  testingTokens: new TestingTokenAPI(request),
  users: new UserAPI(request),
  waitlistEntries: new WaitlistEntryAPI(request),
  webhooks: new WebhookAPI(request),
+
+ /**
+ * @deprecated Use `enterpriseConnections` instead.
+ */
+ samlConnections: new SamlConnectionAPI(request),
  };
 }

packages/backend/src/api/resources/Deserializer.ts

@@ -10,6 +10,7 @@ import {
  Domain,
  Email,
  EmailAddress,
+ EnterpriseConnection,
  IdPOAuthAccessToken,
  Instance,
  InstanceRestrictions,
@@ -193,6 +194,8 @@ function jsonToObject(item: any): any {
  return ProxyCheck.fromJSON(item);
  case ObjectType.RedirectUrl:
  return RedirectUrl.fromJSON(item);
+ case ObjectType.EnterpriseConnection:
+ return EnterpriseConnection.fromJSON(item);
  case ObjectType.SamlConnection:
  return SamlConnection.fromJSON(item);
  case ObjectType.SignInToken:

packages/backend/src/api/resources/EnterpriseConnection.ts

@@ -0,0 +1,64 @@
+import type { EnterpriseConnectionJSON } from './JSON';
+
+/**
+ * The Backend `EnterpriseConnection` object holds information about an enterprise connection (SAML or OAuth) for an instance or organization.
+ */
+export class EnterpriseConnection {
+ constructor(
+ /**
+ * The unique identifier for the connection.
+ */
+ readonly id: string,
+ /**
+ * The name to use as a label for the connection.
+ */
+ readonly name: string,
+ /**
+ * The domain of the enterprise. Sign-in flows using an email with this domain may use the connection.
+ */
+ readonly domains: Array<string>,
+ /**
+ * The Organization ID if the connection is scoped to an organization.
+ */
+ readonly organizationId: string | null,
+ /**
+ * Indicates whether the connection is active or not.
+ */
+ readonly active: boolean,
+ /**
+ * Indicates whether the connection syncs user attributes between the IdP and Clerk or not.
+ */
+ readonly syncUserAttributes: boolean,
+ /**
+ * Indicates whether users with an email address subdomain are allowed to use this connection or not.
+ */
+ readonly allowSubdomains: boolean,
+ /**
+ * Indicates whether additional identifications are disabled for this connection.
+ */
+ readonly disableAdditionalIdentifications: boolean,
+ /**
+ * The date when the connection was first created.
+ */
+ readonly createdAt: number,
+ /**
+ * The date when the connection was last updated.
+ */
+ readonly updatedAt: number,
+ ) {}
+
+ static fromJSON(data: EnterpriseConnectionJSON): EnterpriseConnection {
+ return new EnterpriseConnection(
+ data.id,
+ data.name,
+ data.domains,
+ data.organization_id,
+ data.active,
+ data.sync_user_attributes,
+ data.allow_subdomains,
+ data.disable_additional_identifications,
+ data.created_at,
+ data.updated_at,
+ );
+ }
+}

packages/backend/src/api/resources/JSON.ts

@@ -27,6 +27,7 @@ export const ObjectType = {
  Cookies: 'cookies',
  Domain: 'domain',
  Email: 'email',
+ EnterpriseConnection: 'enterprise_connection',
  EmailAddress: 'email_address',
  ExternalAccount: 'external_account',
  FacebookAccount: 'facebook_account',
@@ -670,6 +671,44 @@ export interface PaginatedResponseJSON {
  total_count?: number;
 }
 
+export interface EnterpriseConnectionJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.EnterpriseConnection;
+ name: string;
+ domains: string[];
+ organization_id: string | null;
+ active: boolean;
+ sync_user_attributes: boolean;
+ allow_subdomains: boolean;
+ disable_additional_identifications: boolean;
+ created_at: number;
+ updated_at: number;
+ saml_connection?: Pick<
+ SamlConnectionJSON,
+ | 'id'
+ | 'name'
+ | 'idp_entity_id'
+ | 'idp_sso_url'
+ | 'idp_certificate'
+ | 'idp_metadata_url'
+ | 'idp_metadata'
+ | 'acs_url'
+ | 'sp_entity_id'
+ | 'sp_metadata_url'
+ | 'sync_user_attributes'
+ | 'allow_subdomains'
+ | 'allow_idp_initiated'
+ >;
+ oauth_config?: {
+ id: string;
+ name: string;
+ client_id: string;
+ discovery_url: string;
+ logo_public_url: string;
+ created_at: number;
+ updated_at: number;
+ };
+}
+
 export interface SamlConnectionJSON extends ClerkResourceJSON {
  object: typeof ObjectType.SamlConnection;
  name: string;

packages/backend/src/api/resources/SamlConnection.ts

@@ -2,6 +2,7 @@ import type { AttributeMappingJSON, SamlConnectionJSON } from './JSON';
 
 /**
  * The Backend `SamlConnection` object holds information about a SAML connection for an organization.
+ * @deprecated Use `EnterpriseConnection` instead.
  */
 export class SamlConnection {
  constructor(

packages/backend/src/api/resources/index.ts

@@ -26,6 +26,7 @@ export type { SignUpStatus } from '@clerk/shared/types';
 export * from './CommercePlan';
 export * from './CommerceSubscription';
 export * from './CommerceSubscriptionItem';
+export * from './EnterpriseConnection';
 export * from './ExternalAccount';
 export * from './Feature';
 export * from './IdentificationLink';

packages/backend/src/index.ts

@@ -66,6 +66,7 @@ export type {
  DomainJSON,
  EmailJSON,
  EmailAddressJSON,
+ EnterpriseConnectionJSON,
  ExternalAccountJSON,
  IdentificationLinkJSON,
  InstanceJSON,
@@ -121,6 +122,7 @@ export type {
  CnameTarget,
  Domain,
  EmailAddress,
+ EnterpriseConnection,
  ExternalAccount,
  Feature,
  Instance,