SSO Configuration

Overview

The SSO configuration API allows you to programmatically manage Single Sign-On (SSO) settings, enabling users to authenticate with Remote using their company's Identity Provider (IdP). By using these endpoints, you can automate the exchange of SAML metadata, activate SSO for specific email domains, and receive asynchronous updates via webhooks when configuration state changes.

Prerequisites

To manage SSO configurations, you can use

Customer OAuth Token: Suitable for customers automating SSO for their own organization.
Partner Client Credentials: Suitable for multi-tenant integrations managing SSO across multiple companies.

Implementation Workflow

Retrieve Remote Metadata

Before configuring your IdP (e.g., Okta, Azure AD), you need to fetch the service provider metadata from Remote. This ensures your IdP knows where to send SAML assertions.

Call the Show the SSO Configuration Details endpoint to retrieve:

sso_url: the Assertion Customer Service (ACS) URL.
audience_uri: the unique identifier for Remote as the service provider.

Configure Identity Provider

Next, create a new app integration in your IdP using the sso_url and audience_uri retrieved previously. Remote supports any IdP that utilizes standard SAML 2.0 inputs (URL and X.509 certificate).

Enable SSO in Remote

Once the IdP is configured, provide the IdP metadata to Remote to complete the handshake through the Create the SSO Configuration endpoint.

Request fields:

Field	Type	Required	Description	Notes
`domain`	`string`	Yes	Comma-separated list of email domains	Example: `example.io`, `example.com`
`identity_provider_url`	`string`	Yes	The SSO URL provided by your IdP.
`certificate`	`string`	Yes	Public X.509 certificate	Usually a base64-encoded PEM file

The response of this request returns an audience_uri which is the application-defined unique identifier that serves as the expected audience URL for SAML assertions.

When an SSO configuration is created, Remote replaces any defaults or dummy configurations. These placeholder configs are generated initially using the company slug in the URL and help avoid duplicate triggers during setup.

Verify Configuration Activation

Since SSO activation involves asynchronous processing, you can listen for the sso_configuration.enabled event to confirm the setup is live.

Retrieve Current Configuration

To audit your current settings or check if a configuration exists, use the Show the current SSO Configuration endpoint. If no configuration is active for the company, the API returns a 404 Not Found status code.

Update SSO Configuration

Currently, updating an existing SSO configuration through Remote API is not supported. But when changes are made to the configuration, Remote triggers the sso_configuration.updated webhook. Similarly, if the configuration is disabled, the system fires sso_configuration.disabled event.

Next Steps

Explore the Working with Webhooks section to set up your event listeners.
Review the SSO Configuration reference for full field specifications.