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:dotnet tool update --global Klef.Cli.
Scaffold a Connector
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:
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
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.
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:
disabled_when field on an account that cannot disable.
Write the Connector
A target implementsITargetConnector 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
context.Httpapplies the manifest. It signs each request, refuses hosts outsideegress, and applies limits and retries. Send every request through it.- Failures are typed. A refused call throws
ConnectorExceptionwith aFailureKind, such asAuthRejectedorObjectGone, which Klef shows and acts on the same way as for its own connectors. A gone or existing object is named, as inConnectorException.ObjectGone(AcmeObjects.User, id). Klef counts a removal done only when the gone object is the account it removes. - The connection check names problems.
CheckConnectionAsyncreturns aConnectionProblemfor each thing that stops Klef using the connection, such as a missing permission, worded as one of the manifest’smessages. A problem that does not block is a warning. Acme’s check passes once the list call works. - Writes are idempotent.
CreatePrincipalAsyncreturns an account that already exists withAdoptedset, 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.
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
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
klef connectors test conformance or klef connectors test journey, and list every test with klef connectors test --list.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.