Skip to content

SAML SSO and SCIM

Canopy Host supports team-scoped SAML single sign-on (SSO) and SCIM 2.0 user provisioning. The host.sso capability is generally available and enabled by default. Configuration and token management require the team owner; API requests are also subject to the account’s authorization.

Create the SSO connection with the identity provider’s entity ID, SSO URL, and signing certificate. Set allowed email domains before enabling the connection. Configuration and activation are separate so you can test the settings first.

Terminal window
canopy sso status --team <team-id>
canopy sso test --team <team-id>

The test command checks whether the connection has the required settings. Configure or update the connection through the Host API:

PUT /teams/{team_id}/sso
Content-Type: application/json
{
"provider": "okta",
"idp_entity_id": "https://idp.example.com/entity",
"idp_sso_url": "https://idp.example.com/sso",
"idp_certificate": "-----BEGIN CERTIFICATE-----...",
"allowed_email_domains": ["example.com"]
}

The API response supplies the service-provider metadata and assertion consumer URLs. Do not include the signing certificate in logs or commit it to source control. Only admin, developer, or viewer can be assigned by SSO; the owner role remains tied to the team’s owner. Group-to-role mappings use the same assignable roles.

Enable SSO after verifying the identity-provider configuration:

PUT /teams/{team_id}/sso/enabled
Content-Type: application/json
{"enabled": true}

Use {"enabled": false} to turn it off. Removing the SSO connection does not remove existing team members. See the Host API reference for complete request and response contracts.

Create a dedicated SCIM token and configure it as a bearer credential in your identity provider. The plaintext is returned only when created; save it in your secret manager. Rotating the token invalidates the previous one immediately.

Terminal window
canopy scim token rotate --team <team-id>
canopy scim token revoke --team <team-id>

SCIM requests use Authorization: Bearer <scim-token> and the SCIM 2.0 resource paths /scim/v2/Users and /scim/v2/Groups. This credential is separate from a Canopy user token and an API key. The current Users surface supports listing, reading, creating, patching and disabling users; Groups supports listing, reading and patching groups. Deleting a user disables sign-in rather than hard-deleting the Canopy account.

Only the Users userName eq "value" filter is recognized; unsupported filter expressions do not become broader server-side queries. See the Host API reference for SCIM response formats and supported operations.

The team owner manages the SSO connection and SCIM token. The server checks sso:manage and scim:manage permissions as well as the host.sso feature. A CLI command or MCP tool being available does not grant permission. Check with your Canopy administrator if the feature is unavailable for your team.