Osano Pulumi Provider

⚠️ Unofficial community provider

This repo is not affiliated with Osano or Pulumi. It is maintained by the community and provided "as is" under the MIT license. Use GitHub Issues/Discussions for support.

The provider lets you manage Osano Cookie Consent and Unified Consent workflows alongside the rest of your infrastructure-as-code. You can:

• Create Cookie Consent configurations and rules, publish them after all dependencies settle, and export the hosted CMP script URL and exact HTML tag.
• Submit consent decisions programmatically from Pulumi deployments.
• Query unified consent state for a subject using Pulumi invokes.
• Resolve anonymous vs. verified subject identifiers via the osano.getSubject invoke when stitching identity flows.
• Inspect UC configuration and privacy protocol collections with osano.getConfig, osano.getCollections, and osano.getCollection invokes.
• Check for existing consent state and hashed consent profiles with osano.checkConsent and osano.getConsentProfile.
• Start and verify subject-profile challenges via osano.sendSubjectCode and osano.verifySubjectCode (requires the Osano API key). Pulumi runs invokes on every preview, update, and refresh, so call these two from automation rather than declaring them in a long-lived stack; otherwise each run sends a new code.
• Wire Osano calls into your CI/CD pipelines with first-class Node.js, Python, Go, .NET, and Java SDKs.

Table of contents

1. Prerequisites
2. Installation
3. Quick start
4. Cookie Consent end to end
5. Authentication
6. Configuration
7. Examples
8. Development

Prerequisites

• Pulumi CLI v3+
• API access to an Osano tenant (a Customer REST API key for Cookie Consent, a Unified Consent API key for Unified Consent, or both for mixed workloads)
• Runtime for your preferred language (Node.js 18+, Python 3.9+, Go 1.24+, .NET 8, or Java 11)

Installation

The SDK declares its provider plugin, and Pulumi downloads the matching release from GitHub the first time you run pulumi preview or pulumi up. To install it manually, pin the version and point Pulumi at the GitHub releases:

pulumi plugin install resource osano <version> --server github://api.github.com/jflavan/pulumi-osano

To add the provider to a Pulumi program, reference the matching SDK:

• Node.js: npm install @jflavan/pulumi-osano
• Python: pip install pulumi-osano
• Go: go get github.com/jflavan/pulumi-osano/sdk/go/osano
• .NET: dotnet add package Community.Pulumi.Osano
• Java: implementation("io.github.jflavan.pulumi:pulumi-osano:<version>")

Quick start

The TypeScript snippet below assumes you created a standard Pulumi TypeScript project with pulumi new typescript and then installed the released SDK:

npm install @jflavan/pulumi-osano
pulumi config set osano:unifiedConsentApiKey --secret
pulumi config set subjectRef <subject-id> --secret
pulumi config set configId <config-id>
pulumi config set privacyProtocolId <protocol-id>
pulumi up

index.ts:

import * as pulumi from "@pulumi/pulumi";
import * as osano from "@jflavan/pulumi-osano";

const cfg = new pulumi.Config();
const subjectRef = cfg.requireSecret("subjectRef");
const configId = cfg.require("configId");
const privacyProtocolId = cfg.require("privacyProtocolId");
const subjectType = cfg.get("subjectType") ?? "verified";

const subject = subjectRef.apply((value) =>
  subjectType === "anonymous" ? { anonymousId: value } : { verifiedId: value }
);

const consent = new osano.Consent("example", {
  subject,
  actions: [
    { target: privacyProtocolId, vendor: configId, action: "ACCEPT" },
  ],
  attributes: { pulumiStack: pulumi.getStack() },
  origin: "api",
  tags: ["demo"],
});

export const consentId = consent.consentId;

Run pulumi up to submit the consent. Destroying the stack removes the logical Pulumi resource but does not delete historical events from Osano (they are immutable).

If you're working from a repository clone instead of published packages, the repo-local examples under examples/quickstart are aimed at contributors. Run mise exec -- make nodejs_sdk once before using the TypeScript example so the local Node.js package exists.

Cookie Consent end to end

The canonical C# Cookie Consent example creates a CMP configuration and its rules, then uses CookieConsentPublication to publish only after those resources settle. The companion TypeScript example implements the same lifecycle. Both compute a deterministic changeToken, declare explicit dependsOn relationships, and allow a twenty-minute customTimeouts window.

Cookie Consent resources require a Customer REST API key:

export OSANO_API_KEY="replace-with-a-customer-rest-api-key"

After publication succeeds, the resource exposes these exact public outputs:

var publication = new CookieConsentPublication(/* ... */);

return new Dictionary<string, object?>
{
    ["cookieConsentScriptSrc"] = publication.ScriptSrc, // scriptSrc
    ["cookieConsentScriptTag"] = publication.ScriptTag, // scriptTag
};

scriptSrc has the form https://cmp.osano.com/{customerId}/{configId}/osano.js; scriptTag is exactly <script src="{scriptSrc}"></script>. These installation values are deliberately non-secret. Put the returned tag first in the site <head> without async or defer, so the CMP loads before scripts it may control. Publication completion and CDN propagation are separate; the latest revision may take up to 15 minutes to reach every edge location.

See Osano's Consent JavaScript API and direct Customer REST API publishConfig operation for the upstream contracts.

Authentication

Two API keys exist:

Configure them with Pulumi config:

pulumi config set osano:unifiedConsentApiKey --secret
pulumi config set osano:osanoApiKey --secret   # required for Cookie Consent and subject verification

Or set environment variables for CI:

export OSANO_UC_API_KEY="..."
export OSANO_API_KEY="..."

Configuration

Provider-level settings (all optional unless noted):

The deprecated osano:ucApiKey and osano:ucBaseUrl keys are still read as fallbacks for unifiedConsentApiKey and apiBaseUrl.

Resource-level inputs are documented in the auto-generated SDK docs (see the GoDoc badge above).

Examples

• examples/quickstart/typescript
• examples/quickstart/python
• examples/quickstart/go
• examples/cookie-consent (canonical C# and companion TypeScript)

These repo-local examples contain Pulumi.yaml plus language-specific dependency files. The shared quickstart README documents the local SDK setup required when running them from a clone.

Development

1. Install toolchain dependencies: eval "$(mise activate zsh)" && mise install
2. Build the provider: make provider
3. Run tests: make test_provider
4. Regenerate schema + SDKs after editing Go code: make codegen

For the full lifecycle (install, deploy, day-2 changes, import, teardown, and the contributor loop) see the end-to-end workflow guide. See CONTRIBUTING.md and the docs for release instructions, troubleshooting tips, and workflows.