Skip to content

Setting Up SAML

SAML single sign-on lets your users authenticate through your organisation's identity provider (IdP) instead of a separate ChannelX password. This guide assumes you already have a working IdP in place.

Before you start

A few things to be aware of:

  • Once SAML is enabled, users can no longer sign in with a password. Disabling SAML reverts that behaviour.
  • If a user belongs to multiple accounts and any one of them has SAML configured, that user must sign in through the SAML IdP. For that reason it is best to keep users confined to your own domain.

Warning

Plan the rollout. Make sure every user who needs access is provisioned in your IdP before you switch SAML on, or they will be locked out.

Configuring SAML

SAML settings live under Settings → Security. You will provide three values from your IdP:

  • SSO URL — the HTTPS endpoint on your IdP where a SAML login begins. ChannelX redirects users here to authenticate; it is the IdP's login endpoint that accepts SAML AuthnRequests and starts the SSO flow.
  • Identity Provider Entity ID — a globally unique identifier (usually a URI-style string) that names your IdP in SAML metadata. ChannelX uses it to select the right IdP configuration and to confirm that inbound SAML messages really come from that IdP.
  • Signing Certificate — the IdP's X.509 public certificate used to sign SAML responses and assertions. ChannelX stores it and verifies signatures against it, ensuring messages weren't tampered with and genuinely originated from your IdP.

Registering ChannelX as a Service Provider

After saving, ChannelX gives you the details needed to register it as a Service Provider (SP) in your IdP:

  • ACS URL — the Assertion Consumer Service endpoint that receives the SAML Response. After the user authenticates, the IdP posts the signed assertion here, where ChannelX validates it and creates a session.
  • SP Entity ID — the unique identifier for ChannelX as a Service Provider in SAML metadata. The IdP uses it to make sure it is responding to the correct application and selecting the right ACS URL and settings.

If you need these values ahead of time, they follow this format, where the installation address is your self-hosted ChannelX URL:

ACS URL:      <your-channelx-installation>/omniauth/saml/callback?account_id=<your-account-id>
SP Entity ID: <your-channelx-installation>/saml/sp/<your-account-id>

Mapping attributes

Configure the following attribute mappings in your IdP:

  • email
  • first_name
  • last_name

The first time a user signs in, these attributes are used to create their account in ChannelX.

Note

This data is used at first login to create the user. It is not re-synced afterwards, so later changes in your IdP won't automatically update an existing ChannelX user's details.

Signing in with SAML

Direct users to the SSO login form at /app/login/sso on your ChannelX installation. They enter their email address, and ChannelX redirects them to your configured SAML provider to complete authentication.

Common questions

A user changed their name in our IdP but it didn't update in ChannelX — why? Attribute mapping only applies at first login. Existing users are not updated automatically; their profile would need to be adjusted in ChannelX directly.

What happens if I disable SAML? Password-based sign-in is restored, reverting the change SAML introduced.