Quick start guide
Maverics is Strata's SaaS solution for Identity Orchestration. In this guide, we’ll walk you through creating your identity fabric configuration and identity orchestrator instance and deploying the configuration to a local environment for the orchestrator instance to consume and run.
An Orchestration Recipe is provided when you first sign up for Maverics. This Recipe, available when you click Upload Identity Orchestration Recipe on the dashboard, configures an identity fabric, application, and user flow automatically. The recipe is provided for evaluation purposes only, but will help you better understand how to implement Maverics with your own IdP and apps.
The instructions provided are for Mac OSX and Windows 10/11. These operating systems are not supported for a production environment, and these instructions are provided for evaluation or testing purposes only.
Before you begin this evaluation, you will need the following:
- Our evaluation.zip package, which can be downloaded below. This .zip file contains:
- docker-compose.yaml: the Docker Compose file, required if you want to run our sample apps locally
- hosted-maverics-recipe.json: the Orchestration Recipe required if you want to use Strata-hosted apps
- maverics.env: the Mac OSX environment file for running Maverics
- maverics-windows.env: the Windows 10/11 environment file for running Maverics
- Self-signed certs: A PEM-encoded key pair is provided for inbound TLS to the orchestrator's HTTP server:
- localhost.crt: the local TLS certificate
- localhost.key: the local TLS key
Unzip this file to a working directory where you can keep all quick start files. This will ensure that the file paths in the code do not need to be changed.
This guide provides two configuration paths for Maverics. The default path configures the Docker-containerized versions of the Sonar app and Keycloak IDP. The second, optional path configures versions of Sonar and Keycloak that are hosted by Strata.
- 2.Sign up using your HYPR, Google, or Microsoft credentials.
- This is a no-obligation trial and no payment information will be collected.
- 3.Once you've signed up, the dashboard appears.
When we combine identity services to build end-to-end user journeys, we call them Orchestration Recipes. Using the example Recipe provided in Maverics, we will deploy a user flow for a non-standard header-based demo application called Sonar.
Currently, Sonar relies on a legacy identity provider (IdP) called SiteMinder and an on-premises LDAP database for user attributes. We will show you how to replace SiteMinder with Keycloak, an open-source identity provider, and leverage the existing LDAP database for user attributes. Maverics is flexible, and this process works with a modern app or identity system migration as well.
Our Orchestration Recipe automatically configures Keycloak as an OIDC identity provider, calls an LDAP database for user attributes, and connects it to Sonar.
To use this recipe:
- 2.From the Import screen, enter "Sonar" for the user flow.
- 3.The Configuration text box is pre-populated with the recipe for local apps. Click Create.
You have the option of using the demo app and IDP hosted and provided by Strata, or running the app and IdP locally using a Docker container. The default recipe configures Maverics with local instances of Sonar and Keycloak, which will need to be launched with Docker using the instructions in Launch containers of sample apps and IDPs. To use our hosted assets instead of running Sonar and Keycloak locally, you will need to replace the default Recipe with the code in the file,
To use this recipe:
- 2.From the Import screen, enter "Sonar" for the user flow.
- 3.The Configuration text box is pre-populated with the recipe for local apps. If you would like to use Strata-hosted instances of Sonar and Keycloak instead, replace the entire configuration in the file,
- 4.Click Create.
Now that you've created a configuration with the default Recipe, the configuration details will appear in Maverics. Go to the dashboard from the left navigation and confirm the following:
- Identity fabric: Keycloak and an LDAP attribute provider appear under identity fabric. Keycloak is an open-source identity provider and has been preconfigured with test users for authentication and as a source for user attributes.
- Applications: Sonar appears under Applications. Sonar is a non-standards-based app that relies on headers for personalization and authorization decisions. We will proxy this application to modernize it. Each resource will be used to build access policies for this application.
- User Flows: Sonar Flow appears under User Flows. The user flow defines the experience users will have when they go to access it.
- Select Sonar Flow and go to the Add access control policy section. Click Resource location: / to view the details. This access policy requires authentication by Keycloak, and Maverics builds the headers Sonar needs for authorization from claims in the session.
- Click any of these items to view the configuration details (such as URLs and login IDs) provided by the recipe. Both Keycloak and Sonar are configured with local URLs, and Sonar Flow connects Keycloak as the authentication provider for Sonar.
Environments enable Maverics to deliver configuration to orchestrators without being connected directly. Orchestrators operate independently and check the environment periodically for updated configuration.
With Maverics as your control plane, you publish configuration bundles to a cloud storage provider, and deploy orchestrators in your environment which read that configuration. This allows for a variety of deployment styles with different storage providers and network topologies. This guide will use the simplest mechanism: locally downloaded configuration bundles.
Maverics architecture model
Maverics publishes securely signed configuration bundles that are unique to each environment. Orchestrators validate these bundles with the environment's public key to ensure the configuration has not been tampered with. If validation fails, the orchestrator will not load the configuration.
In this section we will create a local environment, get the public key, download the configuration bundle, and configure an orchestrator. This will enable us to publish the Sonar user flow to an orchestrator, and test it against local instances of Sonar, Keycloak, and LDAP running in containers.
The following steps only apply if you are using self-hosted versions of Sonar and Keycloak from Docker container. If you'd like to use the Strata-hosted versions of Sonar and Keycloak, skip to Optional: Use apps hosted by Strata.
All asset information to complete the evaluation locally is stored in various Docker containers. To use these containers:
- 3.Open your Terminal application and navigate to your working directory of quick start assets, including the docker-compose.yaml file. (On Windows, open the Command Prompt by pressing the Windows Key + R, and typing
cmdand Enter. Use the
cdcommand to navigate to your working directory.)
- 4.Enter the following command: This will take a few minutesdocker compose up -dThis will start all the services needed for your evaluation environment.
Notes for Windows users It will take several minutes to install Docker Desktop and run the Docker compose file. You may receive an ldap error when running the Docker compose file, but the task is successfully completed when the command prompt has reappeared. Additionally, the Keycloak container may require several minutes to initialize. To check the status of the Keycloack container, view the logs in Docker Dekstop. When you've received the following log message, you can continue:
WARN [org.keycloak.quarkus.runtime.KeycloakMain] (main) Running the server in development mode. DO NOT use this configuration in production.
To verify that the environment is running correctly:
- 3.Optionally, query the LDAP database with the following command:docker exec ldap /bin/bash -c "ldapsearch -h 127.0.0.1 -p 389 -D "cn=admin,dc=sonar-systems,dc=com" -b "ou=People,dc=sonar-systems,dc=com" -w password -x"You should see output showing the two users in the database.
- 2.From the sidebar, go to Environments and click the + icon next to Local.
- 3.Configure the following:
- Name: A friendly name for your environment. For this example, let’s use local-environment.
- Description: Additional description of the environment.
- Production: This checkbox denotes that this will be used as a Production environment. For this exercise, leave the box blank.
- Cookie Domain: This field is optional and specifies the hosts to which the session cookie will be sent. For this evaluation, this can be left blank.
- Max Lifetime Seconds: This field is optional and represents the maximum number of seconds that can elapse post-authentication before the session’s authentication state becomes invalid. For this evaluation, this can be left blank.
- 4.Click Create.
- 5.The details of your environment appear on the next page.
- 1.Download the orchestrator appropriate for your operating system from the Download Orchestrator section. Save this file to your local working directory.
- 2.Download the public key .pem file for your local environment from the section labeled Download Public Key. Save this to your local working directory.
- 3.Open your OS-specific environment .env file from the assets package in a text editor:
- 1.Mac users: update the
MAVERICS_BUNDLE_PUBLIC_KEY_FILE=value to the file name of the .pem file you downloaded. Save the .env file. The example above uses relative paths (in your working directory) but absolute paths also work.
- 2.Windows users: update the
MAVERICS_CONFIG=values to the correct paths. Save the .env file.
- 1.From the sidebar, click User Flows, and select Sonar Flow.
- 2.Click Save Revision. This will update your user flow to a revision that can be published and will advance the numbering to the next revision.
- 3.After the revision is saved, click Publish to deploy your flow to your local environment.
- 4.On the Publish screen, select the local environment you created and click Publish. A confirmation message will appear in the lower right corner, but you will stay on the Publish page. At the top of the screen, the Environments list will reflect that your configuration has been deployed.
- 5.From this list click Download under the Deployed Bundle column. Save the
maverics.tar.gzfile to your working directory. Please note that if you navigate away from this page, you can go to the Environments section, select your local environment, and click the Download Configuration button.
From the terminal window, start the orchestrator with the commands below:
sourcepath to the maverics.env file you edited
configpath to the maverics.tar.gz
./maverics_darwin_amd64 -config ./maverics.tar.gz
sudocommand may be necessary to run
mavericson a privileged port (
sudo -E ./maverics_darwin_amd64 -v -config maverics.tar.gz
Before starting the orchestrator instance, you will need to edit your registry with the values saved in the
maverics-windows.envfile. To do this, first install Maverics by double-clicking the .msi file you've downloaded from Maverics. The
maverics.exebinary will be installed in the
C:\Program Files\Strata Identity\Mavericsdirectory.
Next, open the Registry Editor and navigate to
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\mavericsSvc. Create a multi-string value (REG_MULTI_SZ) called
Environmentif it does not already exist.
Copy and paste the Windows code block from the
maverics-windows.envfile, inserting line breaks between each value. The code block in the text box should look like this:
By default, the orchestrator MSI installer adds a
MAVERICS_CONFIGenvironment variable at the System level pointing to a different location. Delete this instance of the environment variable (System Properties > Advanced > Environment Variables... > System variables) to avoid configuration conflicts.
The Maverics service needs to be restarted to read these new environment variables. To restart it, from the Computer Management console or the Windows Search field, launch Services (
services.msc). Find the Maverics service in the list, right-click and select "Restart."
The "Startup type" for the Maverics service is set to "Auto", which means the service will be started each time Windows starts.
Testing your user flow ensures that Maverics is working as expected and has passed through the correct headers. You can test your user flow by logging into the Sonar app.
To stop the services defined in the Compose file, you can run the following command:
This will stop and remove all the containers created by the Compose file.