SSO is used to allow your users to login to Clove through your own product's authentication. Clove uses your product's authentication so that users don't need a separate account to access your hub. We've created an SSO process that's both secure and easy to add to your product. Here's an overview of what this article will cover:

• Overview of Clove's SSO process

• Defining an SSO endpoint in Clove

• Adding an SSO endpoint into your product

• Complete JWT Format

We have examples of SSO for various programming languages.

SSO Overview

Clove uses a JWT-based SSO process. The security foundation of our SSO is a shared secret between Clove and your product. This allows our applications to exchange information about the user without worrying about it being tampered with.

This next section is technical, but is useful to share with your product team. Here's the complete flow of Clove's SSO:

1. Your customer clicks a link to https://your-hub.example.com/login
   • If they are logged into Clove already, they are taken to your home page.
   • Otherwise, they proceed through the flow.

2. Clove loads your most recent SSO configuration. The user is redirected to the URL you've set.
   • Query parameters are included in the redirection, for example: https://app.example.com/sso/clove/login?hub_domain=your-hub.example.com&hub_id=123

3. Your product determines if the user is logged in or not (using your existing authentication mechanism, such as cookie auth).
   • If logged out, your product takes the user through your auth flow. It must remember that the user came from Clove, so the user can be redirected back at the end.

4. Once the user is logged in, your product signs a JWT (HS256) using a shared secret. The JWT includes information about the user and their organization.

5. Your product redirects the user to https://your-hub.example.com/sso/jwt?jwt={SIGNED_JWT}. You can use the hub_domain provided in step 2 to redirect back to your hub. However, you should validate that the domain is on your domain.

6. Clove verifies the JWT (present in the jwt query parameter) using the shared secret.
   • If valid, the user and organization are saved in Clove. The user is redirected to the home page, or a return_to link.
   • If invalid, the user is redirected to the home page with an error included in the URL bar.

The rest of this article will cover the various steps in the flow. The first step is to define an SSO configuration and receive your shared secret.

Define an SSO Configuration

In Clove, visit Integrations > SSO. You can see existing definitions here, but you'll start with a blank slate. When you hit configure, you'll need to provide a provider URL.

Your product team can choose the URL that they want Clove to redirect to. We recommend the format https://app.example.com/sso/clove.

Once you enter your URL and create the configuration, you'll be presented with a confirmation and shared secret. This secret should never be shared with anyone outside of your SSO implementing team. You would never want to embed it into the frontend code of your application, for example, because it could be retrieved by a user.

You can define multiple SSO configurations. This is useful if you are doing a provider URL or shared secret rotation without downtime. Only the most recent SSO configuration will be used in the login redirection flow.

Now that you have your configuration, your product team can define the endpoint that serves SSO.

Create Your Product Endpoint

As listed above, Clove will redirect to the "Provider URL" defined in the configuration with additional parameters: hub_domain, hub_id. These parameters are useful if you don't want to hardcode information about your hub into your product, or if you have multiple hubs that are served from the same SSO endpoint.

Your product's endpoint must respond to a GET request at the given provider URL. It must do the following things:

• Verify that the user is logged in. If not logged in, guide the user through the standard login flow.

• Generate a JWT that includes information about the user (format below). The JWT should be signed with the HS256 algorithm using your shared secret. JWT is a standard technology with implementations in every major language.

• Redirect the user back to https://your-hub.example.com/sso/jwt?jwt={SIGNED_JWT}

This login flow lets you use whatever login mechanism you want for your users. Email/password login, Okta SSO, OAuth through a third party. All of these flows are supported because Clove doesn't change your login flow.

You can do several things with the JWT token. The next section covers the minimum claims format, as well as all options that are supported.

JWT Claims Format

The JWT claim must have a top-level "user" property that contains the below properties.

Your user payload must minimally include an "id" property—the user's external ID. If an ID is provided, it will be uniquely associated with that user. If you provide conflicting data for the same ID, the most recent data will be written. So, it is very important that you never allow two different users to have the same id.

Another important field is the "organization" property. This property is a map (minimally consisting of an id) that defines the organization that the user belongs to. A user can only belong to a single organization.

Both the user and organization have standard properties as well as supporting "custom_data". The "custom_data" property is a map that is completely free-form. Custom data is useful when you want to change the features or display of your hub based on an application-specific property of the user.

Here is the complete schema of Clove's SSO format:

View Code Snippet

Post-Login Redirect

The user has to be redirected somewhere once the login flow is completed. It would be a bit jarring for the user to be taken to the home page if they expected to view a specific ticket.

Clove will route the user based on the context that they came from. If the user directly accesses a page that requires login, but they aren't logged in, then they will be redirected back to the page once they are logged in.

You can force this behavior by specifying a return_to parameter on the /login link. For security reasons, the parameter must be a path that starts with / and redirects to a page in your hub. You cannot, for example, redirect to an external site after login.

Preview Mode

Clove provides a preview mode so your themes can be tested before they go live. A login through preview mode will specify a hub_domain value of preview.cloveapp.io. If you receive this for the hub_domain, then the login flow should redirect to the preview.cloveapp.io domain instead of your hub's domain.