Set up a proxy app

Welcome to the comprehensive guide on setting up Maverics for use with non-standard/legacy applications. By using Maverics as a proxy auth provider, you can extend your modern app to any identity provider.

This guide is structured to provide both overview and detailed instructions, making it suitable for IT professionals and administrators who are tasked with setting up and managing digital identities. Whether you are new to proxying legacy applications or looking to enhance your existing setup with Maverics, this tutorial is your gateway to a seamless integration process. We’ll cover the following steps:

• Deploy an orchestrator and set it up as a proxy app
• Define your identity fabric
• Configure your proxy application
• Create a service extension (optional)
• Configure your user flow

Deploy an orchestrator and set it up as a proxy app

Before downloading and deploying an orchestrator, you must create an environment. Environments define cloud storage containers where you can deploy user flow configuration and the Orchestrators that will read that configuration for your applications.

For detailed information on how to set up an environment with different cloud storage services, see Configure environments.

After you’ve created your environment, you can download and install the orchestrator. See Install an orchestrator.

As a best practice, Strata recommends also creating a second environment for your app configurations.

Define your identity fabric

The Maverics identity fabric includes an identity provider and optional attribute providers. Maverics identity providers integrate with several OIDC and SAML legacy and cloud identity providers and leverage them as either authentication providers or attribute providers. Some identity systems act as both authentication and attribute providers.

Go to Identity Fabric and make a selection in the Identity Services panel on the right. You can select any service for use with a proxy app.

On the next page, enter your identity service’s information in the corresponding fields. The required information varies depending on the service and protocol you’ve selected. The example below is a generic SAML IDP.

For more information on setting up an identity fabric, see Configure identity fabric.

Configure your proxy application

From the Applications page, create a proxy app by selecting Proxied App under Application Types.

Define the following:

• Name: The friendly name of your application.
• App icon: Upload an image for your application to display in Maverics. Maverics supports JPEG, PNG, or SVG, up to 2MB maximum.
• Upstream URL: The URL to determine where to send traffic after doing its work, like evaluating policies or sending users to a provider for authentication.
  • Route Patterns: The list of patterns that will be used to map a request to the appropriate app. Either a hostname, path, or combination of the two can be used.
• CA Path: (Optional) The path to your certificate authority when using self signed certs.
• Skip TLS Verification: This should only be used for testing. When enabled, the HTTP client will not validate the server’s certificate chain and host name. This should always be used with extreme caution.
• Unauthorized Page: (Optional) The URL your users are redirected to when a policy evaluation prevents access to the application. (example.com/unauthorized, example.com/403)
• Preserve Host: Used to determine if the host header should be preserved on outbound requests. By default, the orchestrator will set the host header to match the upstream’s host. This field is often used when the orchestrator is forwarding traffic to another reverse proxy such as Apache.
• Logout
  • Logout Callback URL: The endpoint that will be exposed to facilitate a logout for application users. (https://app.sonarsystems.com/logout)
  • Post Logout Redirect URL: The address where a user will be redirected after a successful logout. (https://app.sonarsystems.com)

Click Create to save the configuration.

After you’ve created the app configuration, you can specify resources by selecting the proxy app in the Applications list. Resources are locations in your app for which you will map to in your user flows when defining access policies and headers. Examples include a path to a resource such as /, or /example. You can also specify regular expressions.

To apply regular expression matching to resource path, add “~ " (note the space) at the front of the resource location.

Create a service extension (optional)

Service Extensions are short Golang programs that hook into extension points within an orchestrator to modify or extend features. They give administrators the ability to customize the behavior of the orchestrator to suit the particular needs of their integration. This step is optional, and you can view documentation on service extensions below. After creating a service extension, you can select it for use when creating your user flow.

Several service extensions are available for use with proxy app flows:

• Authentication: isAuthenticatedSE and authenticateSE service extensions are available to determine if a user is already authenticated and to control the authentication behavior.
• Upstream Login: upstreamLogin is an optional configuration used to determine if a request to an upstream application is authenticated and to be able to log in to an upstream app. Such situations are common when an app manages its own sessions or directly authenticates against a backing data store like LDAP or a relational database.
• Load Attributes: loadAttrsSE is an optional service extension used to customize how the loading of attributes is done. This extension is often used to load attributes from proprietary data sources such as enterprise APIs.
• Header Creation: createHeaderSE is an optional service extension used to create a custom HTTP header. This extension is often used when an attribute needs to be enriched or concatenated with additional data.
• Authorization: isAuthorizedSE is an optional service extension that can be used to override the default behavior that determines if a user is authorized.
• Handle Unauthorized: handleUnauthorizedSE is an optional service extension that can be used to override the default behavior when a policy evaluation denies access to the app.
• Modify Request: modifyRequestSE is an optional service extension that can be used to modify every request that passes through the app.
• Modify Response: modifyResponseSE is an optional service extension that can be used to modify every response that passes through the app.

Configure your user flow

Next, you’ll create a user flow selecting the proxy app you’ve created.

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 name of the user flow appears at the top of the next 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.

1. 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.
2. (Optional) Under Service Extensions, select a service extension for use with the attribute provider. Click Add to select multiple service extensions.
3. 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.
   1. 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.
   2. 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.
   3. 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.
4. 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.
5. 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.
6. To save the complete user flow, click Deploy… at the top of the page.
7. The Choose revision and environment modal appears. The Revision field reflects the latest number. Select an environment to deploy to and click Preview.
8. On the Deployment Preview screen, you can view the revision history and a diff view of the current user flow against the new user flow (if you’re editing an existing user flow).
9. To save the complete user flow, clickCommit and Deploy, at the top of the page.
10. The Commit revision modal appears, and 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).

By following the steps outlined in this guide, you have successfully set up Maverics for use with a proxy application, laying the groundwork for a robust and secure identity management system. As you proceed, remember that each component plays a crucial role in enhancing the security and efficiency of your proxy application integration, ensuring that your organization’s identity management framework is both resilient and adaptable. With Maverics, you’re now equipped to navigate the complexities of digital identity management, fostering a secure and user-friendly environment for your users.