Skip to main content

Authentication chains: OIDC MFA (fedidp_oidcauth)

The fedidp_oidcauth authentication-chain module adds multi-factor authentication (MFA) to the Bravura Security Fabric login process. It uses the OpenID Connect (OIDC) protocol to hand users to an external identity provider for a second factor, then returns them to the chain to finish logging in.

In this release, the module supports Cisco Duo through the Duo Universal Prompt. Users complete their second factor in Duo's hosted prompt, which offers methods such as Verified Push, WebAuthn, and passkeys. Because the prompt is hosted by Duo, new Duo authentication methods become available without a change to Bravura Security Fabric.

Note

The fedidp_oidcauth module handles end-user MFA at login. It is separate from the agtduo connector, which creates and manages Duo users and groups as a target system. For connector details, see DUO Authentication.

The following topics describe how to set up and run OIDC MFA with Duo:

Overview

The fedidp_oidcauth module runs as a step in an authentication chain. When a user reaches that step, Bravura Security Fabric redirects them to Duo to complete a second factor, then continues the chain based on the result.

The sign-in flow is:

  1. Bravura Security Fabric redirects the user's browser to the Duo /authorize endpoint, including a signed request and a one-time state value that guards against cross-site request forgery.

  2. The user completes their second factor in the Duo Universal Prompt (for example, Verified Push, WebAuthn, or a passkey).

  3. Duo redirects the browser back to the registered redirect URI with a duo_code and the original state.

  4. Bravura Security Fabric verifies that state matches, exchanges duo_code for tokens at the Duo /oauth/v1/token endpoint, and verifies the returned id_token.

  5. On success, the chain continues. On failure, the module returns a failure result and the user does not complete login.

Chain placement modes

You can add the module to a chain in one of two modes:

  • MFA-only (default) - the module supplies the second factor only. Another step in the chain identifies the user.

  • Combined identification and authentication - the module both identifies and authenticates the user. This mode requires a preceding user_ident step. The chain editor warns you if that step is missing.

Health-check behavior

Before it redirects a user, the module can check that Duo is reachable at the /oauth/v1/health_check endpoint. By default the module fails open: if the health check cannot be completed, login is allowed to proceed. To require a successful health check instead, set Fail closed on health check error. For parameter details, see Bravura Security Fabric chain parameters.

What to register in the Duo Admin Panel

Before you configure the module, create an application in the Duo Admin Panel and capture the values that Bravura Security Fabric needs. You register the application once per Duo tenant.

  1. In the Duo Admin Panel, create a Web SDK application. This application type issues the client ID, client secret, and API hostname used for the OIDC flow.

  2. Record the following values from the application's details page:

    • Client ID - the public identifier for the application.

    • Client secret - the shared secret used to sign requests and verify tokens. Handle it like a password and do not share it.

    • API hostname - the Duo endpoint for the tenant, in the form api-XXXXXXXX.duosecurity.com.

  3. Register the Bravura Security Fabric redirect URI with the Duo application. This value must match the module's fedidp_oidcauth_redirect_uri exactly. If you leave that parameter empty, Bravura Security Fabric computes it and displays the value in the chain editor so you can copy it into Duo. For details, see Fabric chain parameters.

Note

If you run more than one Bravura Security Fabric instance, each instance has its own redirect URI. Register every instance's redirect URI with the Duo application.

Bravura Security Fabric chain parameters

The fedidp_oidcauth module adds a custom authentication chain with the following:

  • ID: OIDCAUTH

  • Description: OIDC Auth module (Duo Universal Prompt)

The parameters noted below are for the "OIDC Authentication (Duo Universal Prompt)" (fedicd_oidcauth) authentication chain module.

Table 1. Generic OIDC parameters

Parameter

Description

Signing algorithm

Default: HS512

Drop-down options: HS512, HS256

Application name shown to the user by Duo

The default is a blank value, which defaults to using the module description. This name is what is shown on the mobile device for the authentication from Duo.

Client ID

The Client ID from the Duo application. Required; cannot be empty.

Client secret

The client secret from the Duo application. Bravura Security Fabric uses it to authenticate to Duo and to verify the returned id_token. Required; cannot be empty.

Redirect URI

The URI Duo redirects back to after the prompt. Must use HTTPS, be no longer than 1024 characters, and use a valid hostname. It must match the redirect URI registered in the Duo application.

Username source  

Determines how the authenticated user is matched to a Bravura Security Fabric profile. When set to “Profile attribute”, User profile attribute is required. “Profile name” is the default value for this field. See Username-mapping options.

User profile attribute

The profile attribute matched against the username Duo returns. Used only when Username source is “Profile attribute” See Username-mapping options.

Fail closed on health check error

When set, login fails if the Duo health check cannot be completed. When not set (the default), the module fails open and login proceeds. See Overview.



Table 2. Duo-specific parameters

Parameter

Description

DUO API hostname

The Duo API hostname for your tenant, in the form api-XXXXXXXX.duosecurity.com. Required. Bravura Security Fabric validates the value against the Duo hostname format and rejects a plain hostname that does not match.



The chain editor includes a Test connection button that checks the configured credentials against the Duo health-check endpoint and reports whether the connection succeeds. Use it to confirm the API hostname, client ID, and client secret before you save.

Username-mapping options

After a user completes the Duo prompt, Bravura Security Fabric maps the username Duo returns to a Bravura Security Fabric profile. The Username source parameter controls how that mapping happens.

When you map by profile attribute, set Username source to "Profile attribute" and name the attribute in User profile attribute. Bravura Security Fabric then matches the username Duo returns against that attribute. If you set User profile attribute without a valid attribute name, the save is rejected with a validation error.

Note

If the attribute value matches more than one profile, the match is ambiguous and authentication fails. Choose an attribute whose value is unique per profile.

The mapping applies in both chain placement modes. In combined identification and authentication mode, the mapped user is also the identified user, so a preceding user_ident step is required. See Overview.

Troubleshooting

Use the following table to resolve common problems with the fedidp_oidcauth module. Many issues come from a mismatch between the values registered in Duo and the values set on the module, so confirm those first with the Test connection button.

Table 3. OIDC MFA troubleshooting

Symptom

Likely cause

Resolution

Duo rejects the request and the prompt does not open.

The redirect URI does not match the one registered in the Duo application.

Make sure Redirect URI matches the redirect URI registered in Duo exactly, including scheme, host, and path. If you use the auto-computed value, copy it from the chain editor into Duo.

The user completes the prompt, but login fails with a token or id_token error.

The client secret is wrong or was truncated when copied.

Re-copy the client secret from the Duo application into Client secret, then use Test connection to confirm.

Login fails because the id_token is reported as expired or not yet valid.

The server clock differs too much from Duo's (clock skew).

Synchronize the Bravura Security Fabric server clock with a reliable time source, such as NTP.

Login fails with a state-mismatch error.

The returned state did not match the value Bravura Security Fabric sent. The login session may have been lost, or the callback returned in a different browser session.

Have the user retry in the same browser session with cookies allowed. Persistent failures can indicate a cross-site request forgery attempt and are recorded in the audit log.

Login is blocked when Duo is unreachable.

The health check failed and the module is set to fail closed.

Restore network connectivity to the Duo API hostname. To allow login to proceed when the health check cannot be completed, clear Fail closed on health check errorso the module fails open.

The module will not save because of the API hostname value.

The hostname does not match the Duo format.

Set DUO API hostname to the tenant hostname in the form api-XXXXXXXX.duosecurity.com.

MFA works on one Bravura Security Fabric instance but fails on another.

The redirect URI for the failing instance is not registered in Duo.

Register each instance's redirect URI with the Duo application. Every instance has its own redirect URI.



In this section: