FlowPrime

FlowPrime SDKs and API clients

Alkeyon.Sdk (0.16.0)

Published 2026-11-17 16:29:04 +13:00 by ci-platform

Installation

dotnet nuget add source --name flowprime --username your_username --password your_token https://git.fastflow.tech/api/packages/flowprime/nuget/index.json
dotnet add package --source flowprime --version 0.16.0 Alkeyon.Sdk

About this package

ALKEYON authentication and tenant resolution SDK for FastFlowTech products

OAuth recipients and customer delegation (FB-117)

This contract is opt-in. An inactive integration keeps its existing token behavior. Enabling recipient policy changes the OAuth grant and requires a fresh authorization using an existing registration. This document describes the implementation contract; it does not assert that a live tenant or production is activated.

Trust boundaries

The browser connector requests one canonical HTTPS MCP resource URI. ALKEYON authorizes that resource using deployment-owned policy. The resulting access token has that URI as its sole aud, typ=at+jwt, the originating client_id, scope, recipient_grant, customer subject/account and tenant claims, iat, nbf, exp, jti, and an RS256 signature. An ID token remains an OIDC login credential with the client ID as audience. It cannot be used as an API bearer token.

An MCP resource server validates signature, issuer, lifetime, token type, exact audience, tenant and client policy before running a tool. Its approved confidential backend client can exchange the customer's token for a separate token intended for the downstream API. The downstream validates independently and rejects the original MCP token. Public DCR clients cannot be exchange actors. A signed client_id records the authorization grant; it does not authenticate the software holding a public client's ID.

Delegated tokens retain the customer subject/account and have the API URI as their sole audience. Their client_id and act.sub identify the authenticated MCP backend; origin_client_id identifies the original connector. There is one delegation hop, no refresh token and no token cache. Lifetime is at most five minutes and at most the subject token's remaining lifetime. Revoked consent, inactive clients/resources, a changed policy version, removed seats and attempted scope expansion refuse exchange. Existing short-lived bearer tokens remain usable until expiry unless the resource server separately checks revocation.

Server-owned configuration

OAuth:Resources is an array. Each row contains Uri, Name, OrgId, OrgSlug, Version, Enabled, Clients, AllowDcr and Scopes. An MCP row additionally contains ExchangeClientId and Downstream. The destination must have its own enabled row in the same tenant. OrgId is the silo organization's ID, not the platform directory ID. The URI is exact: HTTPS, canonical spelling, no credentials, query or fragment. No URL is fetched to decide whether it is authorized. Duplicate URI rows fail closed.

Clients explicitly admits ordinary registered clients. AllowDcr explicitly admits customer-surface DCR clients for that resource; DCR metadata cannot change the admission policy, destination or actor. The client's registered scopes and the resource's scopes both bound a grant. A client eligible for any enabled resource must name a resource when starting authorization. Unknown targets or disallowed clients are rejected, never mapped to the shared audience.

Example shape, with synthetic identities only:

{
  "OAuth": {
    "Resources": [
      {
        "Uri": "https://alpha.mcp.example/", "Name": "Alpha connector",
        "OrgId": "alpha-silo-id", "OrgSlug": "alpha", "Version": "1", "Enabled": true,
        "AllowDcr": true, "Clients": ["browser-client"], "Scopes": ["openid", "profile", "email", "org"],
        "ExchangeClientId": "alpha-backend", "Downstream": "https://alpha.api.example/"
      },
      {
        "Uri": "https://alpha.api.example/", "Name": "Alpha API",
        "OrgId": "alpha-silo-id", "OrgSlug": "alpha", "Version": "1", "Enabled": true,
        "Scopes": ["openid", "profile", "email", "org"]
      }
    ]
  }
}

Requests and persistence

  1. GET /Connect/Authorize includes one resource along with the normal OIDC code/PKCE parameters. Login and account-selection continuations retain it. Bound grants always show consent, including first-party clients. The protected, expiring consent form binds the resource, scopes, client, redirect, nonce, PKCE, state, user, tenant and account selection; modifying those fields is refused. The code and its dedicated consent row record an immutable JSON grant.
  2. POST /v1/connect/token with grant_type=authorization_code includes the same resource. Missing or substituted resources fail. The code binds the original scopes; a separate scope parameter on this bound exchange is rejected. Client authentication, PKCE, resource policy and projection checks precede single-use code consumption. The refresh session retains the grant and issuer.
  3. A refresh includes grant_type=refresh_token, the bound client and credential. An omitted resource inherits the stored grant; a supplied resource must match. Optional scope can narrow the access token but cannot widen the original grant. Original authorized scopes, not later registration changes, determine the refreshed token. A removed policy permission or consent refuses before rotation. Refresh rotation uses a database concurrency check.
  4. /v1/auth/switch-account retains the same recipient/client/scope grant while checking the selected live seat. The legacy hosted refresh endpoint cannot accept a client-bound session. Customer machine grants, platform identities and MFA challenges cannot enter recipient delegation.
  5. Exchange uses the existing token endpoint with grant_type=urn:ietf:params:oauth:grant-type:token-exchange, subject_token_type=urn:ietf:params:oauth:token-type:access_token, subject_token, and one destination resource. Authenticate the approved backend client with its secret. Optional requested_token_type must name an access token. Optional scope is constrained by the input and destination. Caller-supplied actor tokens, arbitrary audiences and chained exchanges are refused. The response includes access_token, token_type=Bearer, issued_token_type, expires_in, and scope.

Malformed, duplicate, missing-required or unknown resources return 400 invalid_target; denied admission returns 400 unauthorized_client; scope escalation returns 400 invalid_scope; recipient-policy stale or mismatched grants return 400 invalid_grant; identity/seat refusals return 400 access_denied; failed client authentication returns 401 invalid_client. Before recipient-policy validation, the existing refresh-session guard returns 401 invalid_grant when the session is missing or its client or tenant does not match. That guard applies to both legacy and recipient-bound refresh sessions. Other existing legacy endpoint errors retain their prior behavior. No token or secret belongs in a log or evidence attachment.

Alkeyon.Sdk 0.14.0

Set FFAuth:Resource for an OIDC client requesting a bound grant. Set FFAuth:Recipient on the bearer consumer: Audience, OrgId, OrgSlug, AllowedClients, AllowedDelegates, and optionally AcceptAuthorizedClients=true when the resource explicitly delegates originating-client admission to ALKEYON policy (including DCR). Otherwise an explicit originating-client list is required. These options describe one tenant/resource per bearer scheme; separate schemes/instances are required for distinct strict recipients. They must come from trusted configuration, never token fields or arbitrary request headers.

The SDK applies strict validation on the bearer scheme, browser access-token callback, refresh and account switching, while validating ID tokens separately. Old cookies lacking bound claims are rejected by revalidation. Internal JWKS and token endpoint routing stay configured, and the 0.13.1 key-refresh behavior is retained. RecipientTokenExchange.ExchangeAsync sends the constrained exchange request with an approved backend credential. The consuming API remains responsible for route, account and operation authorization.

ff-mcp's strict instance sets FFAuth:Recipient to its MCP resource and configures Delegation:ClientId, Delegation:ClientSecret, and Delegation:Resources:<service> for approved token-forwarding tools. No target configuration means no delegated call. The initially integrated tools are the auth-user and router caller-identity paths. A single source policy has one downstream target; do not configure multiple destinations and assume they are authorized. Other platform API-key integrations retain their existing behavior.

Go and Python consumers use the same form-encoded protocol: send resource on authorization/code exchange, validate RS256 against the configured JWKS, require at+jwt, exact audience and tenant, and enforce the client/actor contract above. JWT decoding without verification is never an authorization decision. Browser OIDC ID-token validators must continue using the OIDC client audience.

Migration, verification and rollback

Publish the additive SDK and install/configure consumers before enabling a resource. Inventory existing registrations and downstream routes. Supply resource policy and backend credentials through the owning environment's approved configuration process. Enable only the isolated staging fixture first. Require a fresh browser grant after strict activation; never fill missing recipient evidence into old codes, consent or refresh sessions. Resource policy is independent of tenant-issuer rollout: do not change either issuer flags or cutoffs as part of recipient activation.

Unactivated integrations remain legacy and are not claimed to have recipient isolation. A strict endpoint never accepts shared-audience legacy credentials. Any separately retained legacy endpoint needs its own explicit expiry and must not route into a strict API or exchange. This version does not implement a permissive grace window on strict endpoints.

The isolated synthetic staging journey passed eight tests with zero skips or failures on 17 September 2026. It used auth and reference images built from d63faa914f8d2d42488a040b70a56850ac57dc36, separate database/signing keys, actual browser login and HTTP requests through MCP and app SDK middleware. The checks covered both issuer modes, code and refresh replay/concurrency, resource/client/scope binding, account switching, actual consent revocation and constrained downstream exchange. Thirty-five signed HTTP vectors included valid controls and rejection of expired, premature, wrong-recipient, wrong-tenant, non-customer and forged-delegation tokens. The dedicated test source is fastflowtech/integration-tests at fd0e6f37c8edda65ab77a7adb2c8d40d9d09c0ec; this result does not claim the broader integration suites passed or full MCP protocol conformance for the minimal reference handler. Primary staging checks were limited to safe contract/negative requests. SDK publication and isolated fixture success do not establish live product recipient activation or a live ComexAI recipient-bound journey. Production activation requires a separate release approval.

Rollback retains the additive grant columns. Disable affected strict routes and use the last compatible binaries/configuration; do not reopen a legacy route into a strict API. Existing bound sessions require reauthorization if their policy is removed or version changed. Never drop binding data to make legacy sessions work. No production release, live registration or customer-data migration is implied by SDK publication.

Opt-in recipient validation and customer token exchange (FB-117). Requires configured ALKEYON resource policy and a fresh grant. Existing integrations remain unchanged until activated; production activation is separate.

Dependencies

ID Version Target Framework
Microsoft.AspNetCore.Authentication.JwtBearer 10.0.3 net10.0
Microsoft.IdentityModel.Tokens 8.7.0 net10.0
System.IdentityModel.Tokens.Jwt 8.7.0 net10.0
Details
NuGet
2026-11-17 16:29:04 +13:00
5
FastFlowTech
73 KiB
Assets (2)
Versions (1) View all
0.16.0 2026-11-17