Installation and Configuration

Installation

TypeScript/JavaScript

Install the provider using npm:

npm install @kotaicode/pulumi-dex

Go

Install the provider using go get (fetches the Go module at sdk/go; the package import path is .../sdk/go/dex):

go get github.com/kotaicode/pulumi-dex/sdk/go

Python

Install the provider using pip:

pip install pulumi-dex

Provider Binary

The provider binary is automatically downloaded by Pulumi when you use the provider. If you need to install it manually:

pulumi plugin install resource dex v0.1.0

Or download from GitHub Releases.

Configuration

The provider requires configuration to connect to your Dex gRPC API.

Required Configuration

• host (string): Dex gRPC host and port (e.g., dex.example.com:5557)

Optional Configuration

• caCert (string, secret): PEM-encoded CA certificate for validating Dex’s TLS certificate
• clientCert (string, secret): PEM-encoded client certificate for mTLS authentication
• clientKey (string, secret): PEM-encoded private key for the client certificate
• insecureSkipVerify (boolean): Skip TLS verification (development only, default: false)
• timeoutSeconds (number): Per-RPC timeout in seconds (default: 5)

Configuration Examples

TypeScript

import * as dex from "@kotaicode/pulumi-dex";
import * as fs from "fs";

// Production configuration with mTLS
const provider = new dex.Provider("dex", {
    host: "dex.example.com:5557",
    caCert: fs.readFileSync("certs/ca.crt", "utf-8"),
    clientCert: fs.readFileSync("certs/client.crt", "utf-8"),
    clientKey: fs.readFileSync("certs/client.key", "utf-8"),
    timeoutSeconds: 10,
});

// Development configuration (insecure)
const devProvider = new dex.Provider("dex-dev", {
    host: "localhost:5557",
    insecureSkipVerify: true,
});

Go

import (
    "github.com/kotaicode/pulumi-dex/sdk/go/dex"
    "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
    "os"
)

func main() {
    pulumi.Run(func(ctx *pulumi.Context) error {
        caCert, _ := os.ReadFile("certs/ca.crt")
        clientCert, _ := os.ReadFile("certs/client.crt")
        clientKey, _ := os.ReadFile("certs/client.key")
        
        provider, err := dex.NewProvider(ctx, "dex", &dex.ProviderArgs{
            Host:       pulumi.String("dex.example.com:5557"),
            CaCert:     pulumi.String(string(caCert)),
            ClientCert: pulumi.String(string(clientCert)),
            ClientKey:  pulumi.String(string(clientKey)),
            TimeoutSeconds: pulumi.Int(10),
        })
        if err != nil {
            return err
        }
        
        // Use provider...
        return nil
    })
}

Python

import pulumi_dex as dex

# Production configuration
provider = dex.Provider("dex",
    host="dex.example.com:5557",
    ca_cert=open("certs/ca.crt").read(),
    client_cert=open("certs/client.crt").read(),
    client_key=open("certs/client.key").read(),
    timeout_seconds=10
)

# Development configuration
dev_provider = dex.Provider("dex-dev",
    host="localhost:5557",
    insecure_skip_verify=True
)

Environment Variables

You can also configure the provider using environment variables, though you’ll still need to create a provider instance in your Pulumi program:

export DEX_HOST="dex.example.com:5557"
export DEX_CA_CERT="$(cat certs/ca.crt)"
export DEX_CLIENT_CERT="$(cat certs/client.crt)"
export DEX_CLIENT_KEY="$(cat certs/client.key)"
export DEX_TIMEOUT_SECONDS="10"

Then reference them in your code:

const provider = new dex.Provider("dex", {
    host: process.env.DEX_HOST!,
    caCert: process.env.DEX_CA_CERT,
    clientCert: process.env.DEX_CLIENT_CERT,
    clientKey: process.env.DEX_CLIENT_KEY,
    timeoutSeconds: parseInt(process.env.DEX_TIMEOUT_SECONDS || "5"),
});

Dex Setup Requirements

Enable gRPC API

Ensure your Dex instance has the gRPC API enabled. In your Dex configuration:

grpc:
  addr: 0.0.0.0:5557
  tlsCert: /etc/dex/tls/grpc-server.crt
  tlsKey: /etc/dex/tls/grpc-server.key
  tlsClientCA: /etc/dex/tls/grpc-client-ca.crt

Enable Connector CRUD (for connector management)

For managing connectors via the API, Dex must be started with:

DEX_API_CONNECTORS_CRUD=true dex serve config.yaml

Or in your deployment:

env:
  - name: DEX_API_CONNECTORS_CRUD
    value: "true"

Network Access

Ensure your Pulumi program can reach Dex’s gRPC endpoint:

• Default port: 5557
• Protocol: gRPC (HTTP/2)
• For production: Use TLS/mTLS

Local development and testing

To build, generate SDKs, and test against a local Dex instance:

1. Build the provider and generate schema/SDKs (from repo root):

   make build
   make generate-schema   # writes schema.json from the built binary (needs Pulumi CLI)
   make generate-sdks     # generates TypeScript, Go, and Python SDKs from schema.json
   

2. Install the provider so Pulumi can find it:

   make install
   

   Or manually: pulumi plugin install resource dex v0.1.0 --file bin/pulumi-resource-dex

3. Start local Dex (Docker required):

   make dex-up
   

4. Run the TypeScript example:

   cd examples/typescript
   npm install
   pulumi stack init dev   # or pulumi stack select dev
   pulumi preview
   pulumi up               # confirm with yes
   

   See examples/typescript/TESTING.md for more detail and troubleshooting.

5. Test the Go SDK (optional). In a separate Go project:

   go mod init myapp
   go get github.com/kotaicode/pulumi-dex/sdk/go
   

   Then use import "github.com/kotaicode/pulumi-dex/sdk/go/dex" in your Pulumi program. To test against the provider repo before publishing, use a replace in your go.mod:

   replace github.com/kotaicode/pulumi-dex/sdk/go => /path/to/pulumi-provider-dex/sdk/go
   

6. Stop Dex when done: make dex-down (from repo root).

Security Best Practices

1. Use TLS/mTLS in Production: Never use insecureSkipVerify: true in production
2. Protect Secrets: Use Pulumi secrets for sensitive configuration:

   const provider = new dex.Provider("dex", {
       host: "dex.example.com:5557",
       clientKey: pulumi.secret(fs.readFileSync("certs/client.key", "utf-8")),
   });
   

3. Restrict Network Access: Limit access to Dex’s gRPC API to trusted networks/IPs
4. Rotate Certificates: Regularly rotate mTLS certificates
5. Monitor Access: Monitor Dex logs for unauthorized access attempts

Troubleshooting

Connection Errors

Error: failed to connect to Dex

• Verify Dex is running and gRPC API is enabled
• Check network connectivity to Dex host:port
• Verify firewall rules allow gRPC traffic

Error: certificate verify failed

• Ensure CA certificate matches Dex’s certificate chain
• Check certificate expiration dates
• For development, use insecureSkipVerify: true (not recommended for production)

Authentication Errors

Error: authentication failed

• Verify client certificate and key are correct
• Ensure client certificate is signed by Dex’s trusted CA
• Check that mTLS is properly configured on both sides

Timeout Errors

Error: context deadline exceeded

• Increase timeoutSeconds if operations are slow
• Check network latency to Dex
• Verify Dex is not overloaded

Next Steps

• See Resource Documentation for available resources
• Check Examples for complete working examples
• Review Dex Documentation for Dex-specific configuration