ETethiack
organizations

Point an organization at its Zitadel IdP template (admin)

Create the connection, or re-point an existing one.

Idempotent by organization: there is at most one connection per organization, so a repeat call points the existing row rather than inserting a duplicate. The branch is chosen from the caller's scoped read, so a caller who cannot see the existing row falls to the create arm and is refused there -- by their own lack of the verb, or by the conflict on the organization slot.

Through the workflow rather than the connection service: naming a template id means reading that template back from Zitadel to derive the EntityID stored alongside it, which an entity service may not do. See :meth:~phoenix.services.workflows.users.sso_idp_template.SsoIdpTemplateWorkflow.point_at_template for what a connection pointed at a SAML template without one does.

Args: organization_id (int): The parent organization. payload (SsoTemplateRequest): Slug and template id. db (AsyncSession): Request-scoped session. context (ActiveContext): Resolved caller.

Returns: SsoConnectionResponse: The connection as it now stands.

put/v1/organizations/{organization_id}/sso/template

Request

  • Base URL
    https://api.ethiack.com (the document declares no server; this is the origin it was published from)
  • Auth
    none declared

Path parameters

organization_idinteger required

Request body

login_slugstring required

Org-scoped entry token in the login URL: a lower-case DNS label, globally unique. It ends up in the customer's IdP configuration, so changing it invalidates entry links already handed out.

zitadel_idp_idstring nullable required

The Zitadel IdP template this organization's federated logins run against. Required rather than optional so omitting it cannot quietly unpoint a working connection; send an explicit null to unpoint one, which is refused while it is still enabled.

Response

Successful Response

login_slugstring required

Org-scoped entry token in the login URL.

zitadel_idp_idstring nullable

The Zitadel IdP template, or null if unpointed.

enabledboolean required

Whether federated login is served.

require_ssoboolean required

Whether members must authenticate through the IdP.

provision_on_first_loginboolean required

Whether a first federated login may mint an account. Armed only through the provisioning workflow, which requires a DNS-proven domain; not settable here.

provisioned_role'owner' | 'admin' | 'analyst' | 'viewer' required

Sub-role within a :data:ActorKind.ORGANIZATION context.

Snake_case wire values are used in the DB, in JWT claims synced from Zitadel, and as components of Cerbos role strings (e.g. "org_admin").

Attributes: OWNER: Full authority over the organization. ADMIN: Administrative authority below the owner. ANALYST: Read and write on engagements, findings, assets. VIEWER: Read-only.

verified_atstring date-time nullable

When a configuration test last passed against the template now in service, or null if none has. require_sso cannot be set true while this is null: mandating SSO on a connection nobody has proved works locks the organization out, since its members hold no password. Re-pointing the template clears it, so a verification never outlives the thing it verified.

protocol'saml' | 'unknown' nullable

Which protocol family the template configures, as far as Phoenix can tell. Null when the connection points at no template. saml when expected_issuer is stored -- the mint workflow refuses to record a SAML template without one, so its presence is a positive signal, and it is the same discriminator the login path keys on (sso_jit_login._issuer_verdict). unknown for a connection that is pointed but stores no issuer: that is an OIDC template, or a SAML one pointed at by PUT .../sso/template alone, which records no issuer -- and nothing on the row separates the two. Answering oidc there would be a guess, and the guess would hide the ACS and metadata URLs a SAML customer cannot finish onboarding without.

acs_urlstring nullable

SAML only. The Assertion Consumer Service URL the customer must configure in their IdP. Unique to this template, which is what keeps one customer's assertions off another's connection.

sp_metadata_urlstring nullable

SAML only. Zitadel's SP metadata for this template, for customers who prefer importing it over manual entry. Named for the direction: the request bodies' metadata_url is the opposite one, the customer's IdP metadata that Zitadel fetches.

certificate_urlstring nullable

SAML only. Zitadel's signing certificate for this template.

slo_urlstring nullable

SAML only. Single-logout endpoint for this template.

Changes

No recorded changes to this operation across all 1 revision of this API.