Skip to main content

Maintaining a Third-Party Authentication for the Maestro Web SDK

This guide outlines the process of integrating a custom authentication provider with your Maestro site using Maestro's Web Software Development Kit (SDK). Our discussion will pertain to users who have a working knowledge of JSON Web Tokens (JWT) and OAuth authentication concepts. Essentially, this document provides complementary information to the Web SDK usage instructions, especially catering to steps on storing provider details for authorization through the Web SDK.

tip

If you are unfamiliar with the Web SDK, we recommend starting with our guide on integrating Maestro into an existing website

Creating an Authentication Provider​

REST API Endpoint — api.maestro.io/providers/v1​

To enable authentication from the Maestro Web SDK into the Maestro Platform, you first need to establish a provider configuration. To do this, send a POST request to the aforementioned API endpoint. This aims to set up your Maestro provider configuration.

The API call should include the following headers:

{
  "x-maestro-client-id": "your-maestro-siteId", // This can be found under the 'developer ui' tab of the Maestro Admin CMS
  "x-maestro-developer-key": "maestro-dev-api-key" // Generate this key within the Maestro admin's 'developer settings'
}

Ensure that the request body includes the following properties:

{
  "applicationId": "semantic-or-unique-id",
  "service": "your-preferred-service-name",
  "siteId": "your-maestro-client-id", // This is the same as 'x-maestro-client-id' found in the 'developer ui' tab of Maestro Admin CMS
  "jwtPublicCertOrKey": "public-key-to-verify-jwt-signed-by-private-key"
}

Upon completion, the API will return a JSON representation of your provider configuration. To authenticate, you can then use the 'service' property from this response in the Maestro IFrameSDK login() method.

The return JSON has the following structure:

{
  "_id": "provider-config-id",
  "jwtPublicCertOrKey": "your-public-key-or-cert",
  "service": "your-service",
  "siteId": "maestro-site-id",
  "created": 123456789,
  "modified": 234567891
}

To modify your provider configuration in the future, perform a PUT request to the following route. The request should contain updates to what was provided in the original POST call, with the same headers attached.

Updating an Authentication Provider​

REST API Endpoint — api.maestro.io/providers/v1/:id​

The JSON body should resemble the following:

{
  "service": "your-preferred-service-name",
  "siteId": "your-maestro-site-id",
  "jwtPublicCertOrKey": "public-key-to-verify-jwt-signed-by-private-key"
}

Keep in mind that the 'siteId' value should match the Maestro site ID that you'd like to associate the authentication provider with.

Last updated on