Skip to main content
This guide builds custom_acme, a target connector for an app called Acme that speaks SCIM 2.0. By the end, it reads Acme’s users, creates and updates them, and passes Klef’s conformance tests and journey against your Acme test tenant.

Before You Begin

You need the .NET 10 SDK.

Install the Klef CLI

The CLI is a .NET tool on NuGet:
Update it later with dotnet tool update --global Klef.Cli.

Scaffold a Connector

The id is snake_case and starts with custom_, which marks a connector your workspace owns. Klef never ships an id with that prefix. A connector declares an account object by default, which Klef writes into; pass --object worker for an HR system Klef reads workers from. What Klef uses a connector for follows from the objects its manifest declares. A source keeps the rules in What a Source Returns. The command makes:
Names come from the id without its prefix, so custom_acme makes AcmeConnector. Building the project generates more from the manifest:

Write the Manifest

connector.yaml tells Klef what the connector is before any code runs. Replace the scaffold’s with this one:
connector.yaml
What each part does: An account that holds a password or a pass lists it under credentials, beside fields. Each credential has a key, a label, the operations it supports, and its own fields. A secret is a field with secret: true: mutability: write_only when Klef supplies it, such as a password Klef makes to the field’s min_length and max_length, or read_only when the vendor returns it, such as a pass. Klef never stores either in plain text.
A policy issues a credential with a block named for it inside a target, and revokes it with status = removed where its operations include delete. Klef sends it in DesiredPrincipal.Credentials on a create or an update, and the connector answers what it issued, with any returned secret, in WriteOutcome.Done.Credentials. A connector whose accounts hold credentials also implements ISupportsSignInUrl, and returns the tenant’s password rules, when it has any, in its connection check’s PasswordRules. Check it as you go. This needs no tenant:
It reports what the schema refuses and what does not add up across keys, such as a disabled_when field on an account that cannot disable.

Write the Connector

A target implements ITargetConnector to read, and ISupportsPrincipalWrites to create and update accounts. The SDK’s ScimClient speaks SCIM, so the connector only maps Acme’s users to the manifest’s fields. A list call reads one page of the vendor’s own, at most the size Klef asks for, and returns the vendor’s next cursor, or the end after its last page. Klef keeps the cursor and asks again until the list ends:
AcmeConnector.cs
A few things the SDK does for you:
  • context.Http applies the manifest. It signs each request, refuses hosts outside egress, and applies limits and retries. Send every request through it.
  • Failures are typed. A refused call throws ConnectorException with a FailureKind, such as AuthRejected or ObjectGone, which Klef shows and acts on the same way as for its own connectors. A gone or existing object is named, as in ConnectorException.ObjectGone(AcmeObjects.User, id). Klef counts a removal done only when the gone object is the account it removes.
  • The connection check names problems. CheckConnectionAsync returns a ConnectionProblem for each thing that stops Klef using the connection, such as a missing permission, worded as one of the manifest’s messages. A problem that does not block is a warning. Acme’s check passes once the list call works.
  • Writes are idempotent. CreatePrincipalAsync returns an account that already exists with Adopted set, rather than making a second, so a retried plan never duplicates anyone. Klef does not take that account on by itself: the plan reports it for a person to adopt.
Delete AcmeUserMapper.cs if, as here, the connector maps in one place. Every type is in the Reference.

Test It

The kit tests a connector against a real tenant, not a mock: conformance checks each method on its own, and the journey runs a worker through hire, changes and leaving.
1

Describe your test tenant

AcmeLiveTenant tells the kit about your tenant: an existing member to read, how to name and make a new account, and how to inspect and remove one.
tests/AcmeLiveTenant.cs
2

Sign in to the tenant

It asks for each value the manifest declares, here baseUrl, token, memberUserName and emailDomain, and saves them in connection.local.yaml, which the scaffold’s .gitignore keeps out of git. In CI, set them as environment variables instead, such as E2E__Acme__token.
3

Run the tests

It runs conformance, then the journey, and removes every account they made. Run one part with klef connectors test conformance or klef connectors test journey, and list every test with klef connectors test --list.
The tests use a budget of accounts per run, and every account they make carries a prefix, so a run that stops halfway is swept up by the next one.

Run It in Klef

Once the tests pass:
1

Push a draft

Create an API key with the Manage connections permission, then:
acme is your workspace’s subdomain. The revision appears as a draft under Connections > Custom connectors.
2

Serve the connector

On a machine on your network with the .NET SDK, in the connector’s directory:
It builds the connector and serves its calls over HTTP on 127.0.0.1:7001. Set CONNECTOR_LISTEN to serve on another loopback port, or on a unix socket such as unix:/run/acme.sock. The connector reads its connection values the same way the tests do, from E2E__Acme__* environment variables or connection.local.yaml, so give it your production values there. It knows nothing of Klef and holds no Klef key.
3

Start the relay

Under Connections > Custom connectors, select New key under the connector’s Runner keys, and copy the key it shows. On the same machine:
The relay reads the manifest from the connector, registers it with Klef, and forwards each of Klef’s calls to the connector. Pass --connector when the connector does not listen on 127.0.0.1:7001. The relay calls out to Klef over HTTPS; nothing calls in. It reaches the connector over plain HTTP, which is why the connector listens only on loopback or a unix socket: run the two on one machine, or in one pod.
4

Activate

An Owner opens the revision and selects Activate. Plans use the connector from then on.
To change the connector later, push a new revision, start the new build on another port with its own relay, have an Owner activate it, then stop the old connector and its relay.