Developer Guide: Custom Providers

Identix IDP Broker's pluggable architecture allows you to easily extend the system by adding new integration providers. Whether you need a new SMS gateway, a specialized email service, or a custom security verification provider, this guide will walk you through the process.

1. Implement the Interface

All providers must implement the IntegrationProvider interface. Depending on the type of provider, you may also implement a more specialized interface like EmailProvider, SmsProvider, or SecurityProvider.

interface IntegrationProvider {
    val providerType: String
    val capabilities: Set<ProviderCapability>
    fun initialize(config: Map<String, Any>)
    fun test(): TestResult
    fun getMetadata(): ProviderMetadata
}

Example: A New SMS Provider

@Component
class MyCustomSmsProvider : SmsProvider {
    override val providerType = "MY_CUSTOM_SMS"
    override val capabilities = setOf(ProviderCapability.SEND_OTP)

    private var apiKey: String = ""

    override fun initialize(config: Map<String, Any>) {
        this.apiKey = config["apiKey"] as? String ?: ""
    }

    override fun sendSms(request: SmsRequest): SmsResult {
        // Implement the actual sending logic using your custom gateway
        return SmsResult(true)
    }

    override fun test(): TestResult {
        // Implement a health check for the provider
        return TestResult(true)
    }

    override fun getMetadata() = ProviderMetadata(
        name = "My Custom SMS",
        description = "Send SMS via MyCustomGateway",
        icon = "💬",
        category = IntegrationType.SMS,
        schema = ConfigSchema(listOf(
            ConfigField("apiKey", "API Key", "password", true)
        ))
    )
}

2. Register with the ProviderFactory

Once you've implemented your provider, you must register it in the ProviderFactory. This is typically done by injecting your component and adding it to the registry map.

// In ProviderFactory.kt
private val registry: Map<String, IntegrationProvider> by lazy {
    mapOf(
        // ... existing providers
        "MY_CUSTOM_SMS" to myCustomSmsProvider
    )
}

3. Define the Configuration Schema

The getMetadata() method is crucial as it defines how the configuration UI will be rendered in the Admin Dashboard. Use the ConfigSchema and ConfigField classes to specify the required inputs:

• Type: text, password, number, boolean, select.
• Validation: Required status and other constraints.

4. Frontend Integration

If your provider requires a specialized form that doesn't fit the generic schema-based generator, you can add a custom form in the React frontend:

1. Navigate to src/main/idx-react/src/app/pages/admin/integrations/providers/.
2. Create a new form component (e.g., my-custom-sms-form.tsx).
3. Register the new route in src/main/idx-react/src/AppRouter.tsx.

5. Testing Your Provider

1. Start the Identix application.
2. Navigate to Integrations in the Admin Dashboard.
3. Click New Integration and select your provider from the list.
4. Fill in the configuration and use the Test Integration button to verify that your test() method works correctly.