OpenID Connect Provider (OIDC) Connector Guide

The OpenID Connect Provider connector lets Tealfabric workflows authenticate users and retrieve identity claims from any standards-compliant OIDC provider. It is designed for integrations that need secure sign-in, token exchange, and profile enrichment inside automation flows.

Configure your OIDC provider

Set issuer_url, client_id, and client_secret from your identity provider registration. The connector uses the issuer to discover authorization, token, and userinfo endpoints from /.well-known/openid-configuration, which keeps endpoint setup consistent across providers.

Set redirect_uri and scope according to your login requirements, and include openid in every scope set. Run test after configuration to verify discovery and connectivity before connecting the flow to production sign-in traffic.

Start user authorization with authorize

Use authorize to generate the provider authorization URL for the browser redirect step. Include state and nonce values to protect against CSRF and token replay attacks.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

async function createAuthorizationUrl(integrationId: string) {
  const response = await fetch(`${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operation: "authorize",
      redirect_uri: "https://app.example.com/oidc/callback",
      scope: "openid profile email",
      state: "<ENTITY_ID>",
      nonce: "<ENTITY_ID>"
    }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "authorize",
    "redirect_uri": "https://app.example.com/oidc/callback",
    "scope": "openid profile email",
    "state": "<ENTITY_ID>",
    "nonce": "<ENTITY_ID>"
  }'

{
  "success": true,
  "data": {
    "message": "OIDC authorization URL generated",
    "authorization_url": "https://auth.example.com/authorize?client_id=<ENTITY_ID>&response_type=code&scope=openid+profile+email",
    "state": "<ENTITY_ID>",
    "nonce": "<ENTITY_ID>"
  }
}

Exchange code and read identity claims

After the user returns with an authorization code, call token to exchange the code for access and ID tokens. Then call userinfo with the access token to retrieve profile claims for workflow decisions.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

async function exchangeCodeAndFetchUserinfo(integrationId: string, code: string) {
  const tokenResponse = await fetch(`${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operation: "token",
      code,
      redirect_uri: "https://app.example.com/oidc/callback"
    }),
  });
  if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
  const tokenPayload = await tokenResponse.json();

  const userinfoResponse = await fetch(`${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operation: "userinfo",
      access_token: tokenPayload.data.tokens.access_token
    }),
  });
  if (!userinfoResponse.ok) throw new Error(`Userinfo request failed: ${userinfoResponse.status}`);
  return userinfoResponse.json();
}

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "token",
    "code": "<ENTITY_ID>",
    "redirect_uri": "https://app.example.com/oidc/callback"
  }'

{
  "success": true,
  "data": {
    "message": "OIDC tokens obtained successfully",
    "tokens": {
      "access_token": "<ENTITY_ID>",
      "id_token": "<ENTITY_ID>",
      "refresh_token": "<ENTITY_ID>",
      "token_type": "Bearer",
      "expires_in": 3600
    }
  }
}

Production guidance

Treat token handling as sensitive identity infrastructure: store tokens securely, rotate client credentials, and always validate state, nonce, and ID token claims (iss, aud, exp) before trusting authentication results. This prevents common OIDC misuse and replay risks.

Plan for operational failures such as invalid grants, temporary provider outages, and refresh token rotation. Reliable workflows include retry/backoff for transient failures and immediate re-authentication paths when refresh tokens are revoked.

Related resources

Use the OpenID Connect Core 1.0 specification, OpenID Connect Discovery 1.0, and your provider's documentation for endpoint-specific behavior.