Set up an OIDC app

Welcome to the comprehensive guide on setting up Maverics for use with an OIDC application. By using Maverics as an OIDC 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 OIDC 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 an OIDC auth provider
• Configuring Dynamic Client Registration
  • Prerequisites
  • Configuration
  • Testing
• Define your identity fabric
• Configure your OIDC application
• Create a service extension (optional)
• Configure your user flow

Deploy an orchestrator and set it up as an OIDC auth provider

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.

Note that you must provide a URL for your orchestrator, which Maverics can use to automatically define several endpoints. The endpoints are shown in the configuration example below.

    issuer: https://maverics.sonarsystems.com
    endpoints:
      wellKnown: https://maverics.sonarsystems.com/.well-known/openid-config
      jwks: https://maverics.sonarsystems.com/.well-known/jwks.json
      auth: https://maverics.sonarsystems.com/oauth2/auth
      token: https://maverics.sonarsystems.com/oauth2/token
      userinfo: https://maverics.sonarsystems.com/userinfo
      introspect: https://maverics.sonarsystems.com/introspect
      revoke: https://maverics.sonarsystems.com/revoke
      endSession: https://maverics.sonarsystems.com/oidc/logout

Additionally, you will need to provide your OIDC provider certificate and private key when creating your environment.

Optionally, you can turn on Dynamic Client Registration, and configure OIDC cache.

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.

Configuring Dynamic Client Registration

Dynamic client registration (DCR) enables OIDC clients to provision themselves to an OIDC provider by sending metadata (client name, redirect URLs, etc.) to the provider, and receiving the required information to complete an authentication request for its users (client_id, client_secret, etc.).

Prerequisites

Prior to enabling Dynamic Client Registration, you will need to complete the following steps:

• Configure an OIDC auth provider
• Publish an OIDC app type user flow to an environment that defines the IDP for authentication, attribute provider (optional, depending on where claims are sourced), and claims needed by the app

Configuration

To configure DCR when creating an environment:

1. On the Environment configuration page, scroll down to OIDC Provider.
2. Click the toggle switch to enable Dynamic Client Registration.
3. Click OK on the confirmation message.
4. Copy the client registration endpoint: https://maverics.strata.io/register

Testing

To test DCR, you will need to have an environment and OIDC app configured and deployed before completing the following steps. You will also need to have a web app or API manager to send a POST request.

1. Go to the environment configured with an OIDC provider, and under OIDC options, click New to create an API key.

2. Copy the API key ID.

3. Use an API manager or web application to send a POST request to https://maverics.strata.io/register with the following information:

   • an Authorization header with the bearer token set to your API key ID
   • OIDC app metadata in the body of the request per the OAuth 2.0 spec. redirect_uris is required, but all other fields are optional

4. Check the result to ensure the authorization is inherited.

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 an OIDC 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 OIDC application

From the Applications page, create an OIDC app by selecting OIDC-based 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.
• Grant Types: You can select one or more grant types.
  • Client Credentials
  • Authorization Code
  • Refresh Token
  • Password

• Client ID: The client ID OIDC clients will need to connect.
• Client Secret: The client secret OIDC clients will need to connect. You can use a secret provider with the <SECRET_KEY> syntax.
• Redirect URL: The allow list of URLs to redirect to your clients.
• Access Token Settings: This section defines the configuration for the OAuth access token.
  • Type: The type can be set to either jwt (default) or opaque.
  • Length: If the type is set to opaque, the length can be set to between 22 and 256 characters. If jwt, the default length is 28 characters.
  • Lifetime Seconds: By default, access tokens have a lifetime of one hour. You can configure each client’s Access Token lifetime, by setting the lifetimeSeconds tag under accessToken section, to a valid seconds (integer) value.
• Refresh Token Settings
  • Allow Offline Access: Defines whether a client can request refresh tokens.
  • Length: Can be set to between 22 and 256 characters to define the length of a refresh token.

Click Create to save the configuration.

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.

Three service extensions are available for use with OIDC app flows:

• Authentication: isAuthenticatedSE and authenticateSE service extensions are available to determine if a user is already authenticated and to control the authentication behavior.
• Access Token: accessToken defines the configuration for the OAuth access token.
• ID Token: The buildIDTokenClaimsSE is an optional service extension that can customize how claims in the ID token are built. buildAccessTokenClaimsSE can customize how claims in the access token are built.

Configure your user flow

Next, you’ll create a user flow selecting the OIDC 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. However, you can add other configured OIDC apps to the user flow.

1. Under Authentication Provider, select an IDP you’ve configured.
2. 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.
3. 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).
   1. 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.
   2. If you’ve configured an Access Token or ID Token service extension, you can select it under Service Extensions. Click Add to save.
4. To save the complete user flow, click Deploy… at the top of the page.
5. The Choose revision and environment modal appears. The Revision field reflects the latest number. Select an environment to deploy to and click Preview.
6. 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).
7. To save the complete user flow, clickCommit and Deploy, at the top of the page.
8. 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 an OIDC 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 OIDC 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.