Creating an Organization and Configuring SSO
On this page
You set up SSO by converting an existing individual Ververica Cloud account into an organization, then configuring your identity provider. The account that starts the conversion becomes the Organization Owner.
Prerequisites
Before you start, make sure you have:
- Access to an individual Ververica Cloud account registered on the email domain you want the organization to use.
- Ownership of that domain, plus access to its DNS records or someone who can add a TXT record for you. You verify the domain before you can finish setting up the organization.
- An active marketplace subscription on that account.
- Administrative access to your identity provider, so you can create a client and read back its client ID and secret.
- User accounts provisioned in your identity provider on the same email domain.
Choose the domain carefully. Once the organization exists, every Ververica Cloud user who signs in with an email address on that domain belongs to it and signs in through your identity provider. You can't reverse the conversion.
You don't need to stop or delete your workspaces first. They keep running and move to the organization with the rest of your account.
If your company has more than one paying Ververica Cloud account with active workspaces, only one of them can be converted. Contact support before you start, because bringing the others into the organization takes a manual migration.
What happens when you convert
When you convert your individual account into an organization, Ververica Cloud migrates the following automatically:
- Your workspaces.
- Your subscriptions, payment information, and usage and credit history.
- Guests you've invited, and any pending invitations you've sent or received.
- Your registered agents.
Converting is permanent: you can't revert an organization back to an individual account.
Ververica Cloud also provides four permanent Organization Teams. As Organization Owner, you link each one to an SSO Group so the right people in your identity provider get administrative access.
Organization Creation
- From your individual account, start the "Convert to organization" flow. If you leave partway through, some fields become uneditable once you resume.
- Enter your organization name, slug, domain, and logo.
Have your identity provider details ready before you start, so you can complete the wizard in one pass. If you do restart it, check the callback URL again: the client name Ververica Cloud generates can differ from your first attempt, and your identity provider has to match the new value.
Domain Verification
Verify ownership of your organization's email domain, either with a DNS TXT record or by uploading an HTTPS file to your domain. Both domain and SSO verification show as in-progress steps until they clear.
- DNS TXT record: add a TXT record to your domain's DNS settings, using the hostname and key values Ververica Cloud generates for you.
- HTTPS file: download the generated verification file and upload it to the root of your domain.
In the DNS TXT record, the Hostname value is the record name and the Key value is the record content. Your DNS provider might label these two fields differently.
SSO Configuration
Choose an SSO protocol, OIDC or SAML, and enter your identity provider's connection details as part of the same wizard.
Choose a protocol
Ververica Cloud supports two SSO protocols:
- OpenID Connect (OIDC): Discovery URI, Client ID, Client Secret, Groups Claim.
- SAML: your identity provider's metadata XML file. Download it from your identity provider (most provide a button for this) and upload it here; Ververica Cloud reads everything else it needs from that file.
Pick whichever your identity provider uses. Most modern identity providers support OIDC; SAML remains common in some enterprise environments.
Your identity provider must send the user's email address in the authentication response. Ververica Cloud matches the person signing in to their account by email address, so if that claim is missing, sign-in fails even when the credentials are correct.
Configure your identity provider to include group membership in the authentication response, so Ververica Cloud can match users to the Organization Teams you set up.
- SAML: send group membership as a
groupsattribute. - OIDC: send group membership as a claim, then enter that claim's name in the Groups Claim field.
Once you choose a protocol, Ververica Cloud also shows you reference values to enter on your identity provider's side: a callback URL for OIDC, or an SP Entity ID and callback URL for SAML.
Your identity provider doesn't need to run on the organization's domain. It only needs to be reachable at the URL you provide.
When you save, Ververica Cloud checks that the discovery URL is reachable and returns valid content, but it doesn't test the whole sign-in flow. A wrong client ID or client secret only shows up the first time someone signs in with SSO. If that happens, the Organization Owner can still sign in with a username and password, which gives access to the organization profile and SSO settings, and correct the configuration from there.
Finishing Up
Once the organization setup is finished, you can start creating Teams to manage access to your workspaces.
Until you configure SSO, you and other administrators keep using password sign-in to finish setup.
People on your domain don't need a Ververica Cloud account beforehand. The first time someone signs in through your identity provider, Ververica Cloud creates their account from the details in the authentication response.
What you can change later
You can update the SSO connection details after the organization exists, including the client ID and client secret.
The organization's domain, the SSO protocol, and the client name in the callback URL are fixed once the organization is created. Transferring ownership of the organization goes through support.