Enterprise authentication for the NORG connector

One outbound HTTPS endpoint

The connector is a URL your users’ MCP client calls. Nothing is installed on your network, nothing listens there, and NORG opens no connection towards you.

OAuth 2.1, authorization code with PKCE

Every user authenticates individually. The only code-challenge method advertised or accepted is S256; a request without it is refused.

One API scope

Consent grants mcp:onboarding and nothing else. It is the only scope the discovery documents advertise, the only one the endpoint accepts, and the only one dynamic registration issues.

No identity token

openid is neither advertised nor granted, so the connector never receives an OpenID identity token. It is filtered at two independent layers.

Accounts are created on first use

There are no seats to buy, assign or pre-provision. A user who has never connected before is set up automatically when they first authenticate.

Its own workspace, always

The workspace the connector creates carries a provenance stamp, and the connector only ever operates on a workspace bearing it — never on a workspace created any other way.

https://<norg-host>/v2/mcp/express

Both /v2/mcp/express and /v2/mcp/express/ answer directly, so a trailing slash is not a mistake. The version sits in the path so the contract can change without breaking connectors already installed.

HTTP/1.1 401 Unauthorized, with a WWW-Authenticate: Bearer header carrying error="invalid_token" and a resource_metadata parameter pointing at the document in step 2. The body is the same error as JSON.

A 403 with insufficient_scope instead means the token was valid but did not carry mcp:onboarding. A 503 means that environment has no authorization server configured — the endpoint fails closed rather than answering unauthenticated calls.

The document in step 2 contains a resource field. It must equal, character for character, the URL you entered. If it does not, you are not looking at the connector you think you are. The same document lists scopes_supported, which must be exactly ["mcp:onboarding"], and resource_name, which reads NORG Express Onboarding.

NORG runs its own authorize, callback and token endpoints in front of its identity provider. That is not decoration. RFC 9207 requires a client to record the issuer it discovered and reject any authorization response whose iss does not match it by exact string comparison. Relaying the client-facing leg is what makes the advertised issuer the one the client is actually answered by.

The practical consequence for you: there is one origin to review, one origin to allow through egress filtering, and no second party for your users' browsers to be handed off to. Point tooling at the discovery documents above — never at the identity provider behind them.

PKCE passes through untouched. The client's code_challenge goes upstream and its code_verifier comes back through the token endpoint, so the relay never holds the verifier and cannot weaken the binding. An authorization request with no challenge, or with a method other than S256, is sent back to the client as error=invalid_request.

One API scope, mcp:onboarding. It is the only scope advertised, the only one the endpoint will accept, and the only one dynamic registration will issue — the registration code discards whatever a client asks for and returns that constant.

Alongside it the identity provider attaches its own standard identity scopes so the connector can read the subject, email and name claims it needs to know who is connecting. offline_access is available on request, which is what makes refresh tokens work. openid is filtered out at two independent layers, so no OpenID identity token is ever issued: such a token would carry the identity provider's own iss, which can never equal the issuer NORG advertises, and a conformant client is required to reject it.

A client POSTs to /v2/mcp/register with no pre-shared credential. That is deliberate: it is what lets a connector be added from the URL alone. It is not open registration.

The callback must already be allowlisted. Every entry in the request's redirect_uris must match a configured allowlist by exact string. Not a prefix, not a pattern, not a host — the whole URI. Anything else is refused with 400 invalid_redirect_uri, and the refusal records only the callback's hostname, never the URI itself.

An unconfigured allowlist refuses everyone. Where no allowlist is set the endpoint answers 503 registration_unavailable. It fails closed; there is no "allow all" state.

Registrations are rate-capped. A fixed window, keyed on the source address the server derives itself rather than anything the caller can claim. Only successful registrations consume budget; past the cap the answer is 429 rate_limited. The shipped default is 20 per hour per source, set per environment, and it is a per-instance count rather than a cluster-wide one.

The result is always a public client. The response says token_endpoint_auth_method: "none", grants authorization_code and refresh_token, scopes to mcp:onboarding, and carries no client_secret. A request asking for a confidential client does not get one — those fields are not read at all — and the response is marked no-store.

The mechanism introduced in the 2025-11-25 MCP authorization specification. The client's client_id is an https URL, and the JSON document served at that URL declares its own redirect URIs. Nothing is registered in advance and NORG issues no credential at all.

It is offered per environment. Read client_id_metadata_document_supported in the authorization-server metadata for the environment you are approving. It is off unless explicitly enabled, and where it is false, clients use dynamic registration instead. Do not hard-code an assumption either way.

The URL never reaches the identity provider as a URL: it is mapped to a derived identifier, one per document, so the same document always resolves to the same client. Documents are cached for ten minutes, refusals for one, and the number of distinct new documents accepted is capped both per source address and across all callers.

https only, and a real path

The client_id must be an https URL with a host and a genuine path — no bare origin, no fragment, no embedded credentials, no "." or ".." segments, and no longer than 2048 characters. Anything else is not treated as a CIMD identifier at all.

The host must be publicly routable

The name is resolved before the connection is made and every resolved address must be public. Private, loopback, link-local, reserved and carrier-grade-NAT ranges are refused, as are numeric and alternate-notation forms of them. The connection is then pinned to the address already checked, so the name cannot be re-pointed in between.

Redirects are not followed

A 3xx response is a refusal, not a hop. The document has to be served directly from the URL that is the client_id.

One three-second deadline

The whole fetch and read runs under a single wall-clock deadline, so a server that drip-feeds bytes cannot hold a request open.

JSON, and bounded

The Content-Type must be exactly application/json, and the body is capped at 65,536 bytes — refused on a declared length that exceeds it, and aborted mid-stream if the bytes do.

It must name itself

The document’s own client_id field has to equal the URL it was served from, exactly. A document that claims to be some other client is refused.

It must be a public client

token_endpoint_auth_method must be "none". If grant_types is present it must include authorization_code. There is no path here that produces a confidential client.

It must list its own redirect URIs

At least one, and the redirect presented at authorize time must match one of them. Matching is exact string equality, with a single exception: two loopback URIs may differ in port, as RFC 8252 requires.

The redirect must be https or loopback

An https URL, or a plain-http loopback URL for a client running on the user’s own machine. Nothing else is accepted, whatever the document says.

The user is told who is asking

The consent screen shows the document’s host and the hosts it redirects to — or, for a loopback-only client, that it is a local application on the user’s own device.

• A user record, from the token’s subject and email claims, with the display name taken from the name claim or the email’s local part.
• A workspace owned by that user, stamped with the connector’s own provenance marker.
• An owner membership linking the two.
• A starting token balance, so the first piece of work the user asks for is not refused for lack of quota.

The connector holds no session, so the same check runs on every authenticated call. It is idempotent: after the first request it finds what already exists and creates nothing. Concurrent first requests from the same user are serialised, so a burst cannot produce duplicates.

If a NORG account already exists for that email address, the connector adopts it rather than creating a second one — and refuses to do so when the identity provider reports the address as unverified, so an unverified sign-up cannot claim someone else's account.

The workspace it creates carries a provenance marker, and the lookup that finds an existing one keys on that marker. That is what confines the connector to workspaces it created itself: it has no route to a workspace made any other way.

• Buy, assign or reclaim seats — there are none.
• Synchronise users, groups or roles from your directory. The connector reads no group or role information, and authorisation is the single scope, nothing more.
• Create anything in advance. A user who has never connected is set up on the request that authenticates them.

No client secret is issued to a self-registered client

Both registration routes produce public clients using PKCE. The dynamic-registration response states an authentication method of "none" and carries no secret field, and a metadata document declaring anything other than "none" is refused.

No OpenID identity token is issued

openid is absent from the advertised scopes, stripped from whatever a client requests, and never granted at registration. The connector learns who the user is from the access token’s own claims, not from an identity token.

No credential is written to a log

A refused registration records the callback’s hostname and the client name, never the URI. Token verification logs the outcome and the resolved identifiers, never the token. The relay hands a client secret straight to the identity provider without inspecting or storing it.

No redirect is followed when fetching a client metadata document

A 3xx response is treated as a refusal. Combined with resolving the host and pinning the connection to an address already checked as publicly routable, there is no hop an attacker can insert to reach an internal address.

No caller-supplied address is trusted for rate limiting

The registration cap keys on the source address the server derives itself. A caller cannot rotate a header to mint fresh budget, and an address that cannot be derived is capped rather than exempted.

No unauthenticated request is answered with data

The connector answers 401 and nothing else. The only public documents are the two discovery documents, which exist so a client can find out how to authenticate, and both are excluded from search-engine crawling along with the endpoint itself.

No connection is made towards your network

The connector is an endpoint your users’ client calls. There is no agent, no appliance, no callback into your infrastructure, and no firewall rule to open inbound.