Environments will soon be migrated to Deployments
This topic covers configuration of the Maverics Environments model. If your account has already been migrated to Deployments, see the Deployments help.
Environments define cloud storage containers where you can deploy user flow configuration and the Orchestrators that will read that configuration for your applications. Create environments (e.g. dev, test, staging, and production), configure cloud storage containers, and assign orchestrators to those environments.
Production environments should ensure shared storage solutions are secure. Please review our production recommendations for shared storage solutions.
Create a new environment
From the sidebar, click Environments, and click the + icon next to the type of storage you would like to configure. If you are creating an evaluation environment, skip to Evaluation environment configuration.
The environment and orchestrator support the app you configure. If you are going to use the environment with a SAML app, you must include the SAML provider details in your environment configuration. If you are using the environment with an OIDC app, include the OIDC provider and, optionally, OIDC cache details in your environment configuration.
Refresh required
Making any updates to your environment requires a manual restart of your orchestrator to refresh the settings.
Settings are divided by section as follows.
General Settings
Name: A friendly name for your environment. For this example, let’s use AWS-staging.
Description: Additional description of the environment.
Production: This checkbox denotes that this will be used as a Production environment.
Orchestrator Settings
Max Lifetime Seconds: (Optional) This field represents the maximum number of seconds that can elapse post-authentication before the session’s authentication state becomes invalid.
Idle Timeout: (Optional) This field represents the number of seconds a session may remain idle before timing out. If no value is set, or IdleTimeout is set to 0, then the session idle timeout is disabled.
Cache Size: (Optional) This field limits the number of sessions maintained in memory. Defaults to 50,000 sessions.
Orchestrator URL: (Required) This field is required when configuring the orchestrator as an OIDC or SAML provider. The orchestrator URL is used to define additional OIDC endpoints and SAML endpoints.
Logout Endpoint: This optional field is the endpoint clients may call to trigger logout from all applications and IDPs. Maverics can automatically populate this based on the Orchestrator URL. Enter the value after the orchestrator URL only (for example,
slo
orlogout
).Post-Logout Redirect URL: This field is optional and represents the URL to redirect the client to after the single logout process is complete.Maverics can automatically populate this based on the Orchestrator URL.
Health check endpoint: Specify the endpoint that external services can poll to determine the health of the orchestrator. When a GET request is made to this endpoint, a live orchestrator should return an HTTP 200 response. If this field is not set, the default endpoint of /status is used. (Note: The orchestrator must be manually restarted in order for this change to take effect.)
Cookie Settings
Domain: (Optional) This field specifies the hosts to which the session cookie will be sent.
Name: A friendly name for the cookie.
HTTPOnly Attribute: (Optional) This field toggles the HTTPOnly cookie attribute for the session. If disabled, the session cookie will not have the
HttpOnly
attribute, allowing the cookie to be accessed via client side scriptsSecure Cookie Attribute: (Optional) This field toggles the Secure cookie attribute. If disabled, the session cookie will not have the
Secure
attribute, allowing the browser to send the cookie over an unencrypted HTTP request.
Logging settings
Time format: Select your preferred formatting of log timestamps.
Level: Select the verbosity of the Orchestrator logs. For example, selecting "Error" will only show error logs (when debug mode is off).
Session tracker: Enable or disable a session identifier in log messages. This setting is useful when filtering logs to isolate a problem with a particular session. (Note: The identifier printed in the logs corresponds to a particular session, but it is not the actual session ID itself and cannot be used to impersonate a user's session.)
Telemetry: When enabled, orchestrators send telemetry data to Maverics. You can view this on the Orchestrator Telemetry page. After you have started your Orchestrator, click Redeploy on a user flow to refresh. This option is turned on by default.
Container configuration details
Additional configuration details will depend on the cloud storage environment you have selected. This usually includes bucket names, access keys, tokens, and configuration file paths. For more information on configuration details, scroll down for best practices.
SAML Provider
Configure the following fields if you will be using this environment for a SAML provider (for use with a SAML application).
Issuer Override: Enter a SAML issuer here to override the default Orchestrator URL.
Signing Options: Select whether to sign only the response, only the assertion, or both.
Key Pairs: Select whether you want to upload a certificate, use a secret store, or generate a certificate and key pair.
Certificate: The x509 certificate used by clients to validate the signature of SAML assertions.
Private Key: The RSA256 private key used to sign SAML assertions.
For more information on configuring a SAML provider, see SAML app pattern.
OIDC Provider
Configure the following fields if you will be using this environment for a OIDC provider (for use with an OIDC application).
Key Pairs: Select whether you want to upload a certificate, use a secret store, or generate a certificate and key pair.
Certificate: The x509 certificate used by clients to validate the signature of OIDC assertions.
Private Key: The RSA256 private key used to sign OIDC assertions.
For more information on configuring an OIDC provider, see OIDC app pattern.
OIDC Cache
External caches may be defined and used with the orchestrator to enable high availability for OIDC providers/applications. Currently OIDC Cache only supports Redis 6.0 or greater. You will need to configure the following:
Addresses: Your Redis server addresses.
Username and password: (Optional) The username and password must be generated via access control list (ACL) in Redis.
CA Path: (Optional) The path to your certificate authority when using self signed certs.
Encryption Keys: List of 32 byte encryption keys from oldest to newest. Keys can be created with OpenSSL (for example: openssl rand -hex 32).
Click Create. The details of your environment will appear on the next page.
Environment details page
The environment details page appears after you've created the environment. You can also navigate to this page by selecting an environment on the Environments page.
The details page is divided into several categories.
Orchestrator or Orchestrator Evaluation Bundle
Download the installer based on your OS and follow our documentation to install and setup.
For evaluation environments, this section provides an evaluation bundle. This bundle contains everything you need to connect to this environment, including public keys and certificate files, an environment file, and an orchestrator. After downloading the file appropriate for your OS, you can then run the orchestrator included in the bundle.
Resources
From this section, you can download the public key for your environment. You can also download the Windows Client Authenticator.
Deployed User Flows
This table shows the user flows that have been deployed to this environment, including the revision number and the user. Click Download configuration to download a maverics.tar.gz bundle of the full configuration, including service extensions. Click Redeploy to refresh all user flows in the environment.
OIDC options
OIDC options appear on environments set up for use with an OIDC app.
SAML details
SAML options appear on environments set up for use with a SAML app.You can download the SAML signing certificate and SAML metadata in these sections to set up a SAML service provider.
Evaluation environment configuration
When you create an evaluation environment for testing, no additional configuration of the environment is necessary. The following steps occur behind the scenes:
An AWS storage bucket will be created.
The defaults for Orchestrator URL (https://localhost), logout URL (/logout), and other settings will be configured automatically. You can change these settings by clicking the Edit button in the top right hand side.
An empty maverics.tar.gz file is then pushed to the cloud storage bucket so the orchestrator will start up successfully in case there is no user flow published yet.
A downloadable bundle is created with a maverics.env file preconfigured to connect to this environment.
You can only have one eval environment at a time. After you create one it removes the option to create another from the Environments right side bar. This environment is provided for tesing purposes only and may be deleted after 90 days of inactivity.
Configuration Best Practices
To configure a storage container, use the following instructions:
Note that the details for each storage provider will be input when creating a new storage provider in Environments.
Configure user flows
User flows define the policy details for an application. This topic guides you through the four main steps of creating a user flow.
Select an application you've already configured.
Define the policy details (fields are dependent on the type of app).
Select the environment for the user flow.
Preview your changes and deploy the user flow.
Before creating a user flow, you must have at least one environment, one authentication provider, and one application configured.
Create or edit a user flow
From the dashboard, click Create user flow. Alternatively, from the sidebar, click User Flows, and click New. Enter a name for the user flow and select an application to use. Click Create.
To edit an existing user flow, click User Flows from the sidebar and click the name of the user flow you want to edit.
The fields available on the next page are dependent on the type of app being defined.
Proxy apps
The name of the user flow appears at the top of the screen and can be edited. The application appears under the name. You can click the application to edit the app configuration, but you cannot change the application tied to the user flow.
In the Attribute Providers section, use the Settings section to select an attribute provider, a username mapping provider, and a username mapping attribute. Click Add to save your attribute. Repeat this process to add multiple attributes.
(Optional) Under Service Extensions, select a service extension for use with the attribute provider. Click Add to select multiple service extensions.
Under Access Control Policies, you can select a resource that you've defined in the application configuration to apply fine-grain access controls and pass user information through HTTP headers. Click Add to define the access control.
On the Access Control page, select an authentication provider and the access policy you want to use.
Authentication: By default, users are denied access to the resource unless they are authenticated. You can select Allow unauthenticated users under Authentication if you want to allow access to unauthenticated users.
Authorization: By default, users are denied access to the resource unless granted access through an authorization rule.
You can select Allow all access if you want to allow all users access without an authorization rule.
If you wish to leave this option turned off, you can apply fine-grain access control and authorization by selecting Use rules to define access and using the boolean rule builder that appears on screen.
The rule builder allows you to add rules and conditions by provider. Additionally, you can add a rule or condition to restrict access based on HTTP request method. You can specify the HTTP method and create different access rules for reading a resource (using GET) versus modifying it (using POST or PUT).
Alternatively, you can select a service extension if you have any authorization service extensions already configured.
Service Extension Policy Decision Lifetime: Define the length of time when policies are re-evaluated by service extensions. If your user flow does not leverage a service extension for authorization or load attributes, you can skip this option.
Cached for the duration of the session: The policy decision will be cached for the lifetime of the session. For more information, see Max Lifetime.
Specify a duration: Set the duration of policy re-evaluation in seconds, minutes, or hours. The policy decision will be cached for the specified duration or until the session ends.
Continuous re-evaluation: The policy decision will not be cached and every request will be evaluated.
Define the headers in the Headers section by entering the header name, selecting the provider, and entering the attribute. Click Add to save the header, and repeat to add multiple headers.
If you've configured a Header Creation service extension, you can select it under Service Extensions. Click Add to save the service extension, and repeat to add multiple service extensions.
The Headers section allows you to define broad policies for the application. Define the headers in the Headers section by entering the header name, selecting the provider, and entering the attribute. Click Add to save the header, and repeat to add multiple headers.
If you've configured service extensions, you can select them under Service Extensions. Click Add to save the service extension, and repeat to add multiple service extensions.
To save the complete user flow, click Commit and Deploy at the top of the page and proceed to the next section.
SAML apps
The name of the user flow appears at the top of the screen and can be edited. The application appears under the name. You can click the application to edit the app configuration, but you cannot change the application tied to the user flow. However, you can add other configured SAML apps to the user flow.
Under Authentication Provider, select an IDP you've configured.
In the Attribute Providers section, select an attribute provider, a username mapping provider, and a username mapping attribute. Click Add to save your attribute. Repeat this process to add multiple attributes.
The Authorization section allows you to define your access policy. By default, users are allowed access unless granted access through an authorization rule.
Allow all access is selected by default, and allows all users access without an authorization rule.
Select Use rules to define access to apply fine-grain access control and authorization. The Boolean rule builder appears after selecting this option, and allows you to add rules and conditions by provider.
Alternatively, you can select a service extension if you have any authorization service extensions already configured.
The Claims section allows you to provide additional claims to this user. This maps claims to session attributes provided by the IDP(s) and any optionally defined AttributeProvider(s).
Use the SAML Attributes section to select an attribute provider, a username mapping provider, and a username mapping attribute. Click Add to save your claim. Repeat this process to add multiple claims.
Under NameID mapping, you can define custom NameID mappings in SAML responses. Select a provider and enter the attribute you want to define. Click Add to save the mapping.
If you've configured Build Claims or Build Relay State service extensions, you can select them under Service Extensions.
To save the complete user flow, click Commit and Deploy at the top of the page and proceed to the next section.
OIDC apps
The name of the user flow appears at the top of the screen and can be edited. The application appears under the name. You can click the application to edit the app configuration, but you cannot change the application tied to the user flow. However, you can add other configured OIDC apps to the user flow.
Under Authentication Provider, select an IDP you've configured.
In the Attribute Providers section, select an attribute provider, a username mapping provider, and a username mapping attribute. Click Add to save your attribute. Repeat this process to add multiple attributes.
The Claims section allows you to provide additional claims to this user. This maps claims to session attributes provided by the IDP(s) and any optionally defined AttributeProvider(s).
Use the OIDC Claims Mapping section to select an attribute provider, a username mapping provider, and a username mapping attribute. Click Add to save your claim. Repeat this process to add multiple claims.
If you've configured an Access Token or ID Token service extension, you can select it under Service Extensions. Click Add to save.
To save the complete user flow, click Commit and Deploy at the top of the page and proceed to the next section.
API
No additional configuration is needed for API apps.
Commit and Deploy
After clicking Commit and Deploy, the Commit revision modal appears. From here, you have several options:
- Select an environment and click Commit new revision and deploy to save your user flow changes, and deploy them to the selected environment.
- Select a previous revision and an environment and click Deploy
to deploy a previous configuration to the selected environment. The Deploy button only appears after choosing a previous revision from the dropdown. - Click Commit & close to save the changes to the user flow and close the window (This will not deploy the user flow to an environment).