User authentication in MC

The MC provides authentication options that integrate the MC with your existing corporate authentication workflows. By default, the MC provides local authentication, which stores all user information in the MC. The MC integrates with Keycloak so you can configure federated or identity provider (IDP) authentication with the MC SUPER administrator account.

Local authentication

Local user authentication is the default authentication method and does not require additional steps after you install and configure the MC. Local user information is stored on an internal database on the MC web server.

You can edit or reset local user passwords in the following locations:

  • Email Gateway.
  • MC Settings > Change Password.
  • In the user account menu in the toolbar, select Change Password.

Configure multi-factor authentication (MFA) for local and LDAP users

For local and LDAP-authenticated users, Keycloak performs authentication against either its internal user store or an external LDAP/Active Directory directory. To strengthen account security, Keycloak can enforce a second authentication factor by using time-based one-time passwords (TOTP). This section describes how you can configure MFA policies and enforce MFA for individual users or groups.

Configure the realm OTP policy

Before you enable MFA for users, configure the realm-level OTP policy.

  1. In the Keycloak Admin Console, go to Authentication > Policies or OTP Policy, depending on your Keycloak version.
  2. Configure the OTP settings. The recommended values are:
  • OTP Type: Time Based (TOTP)
  • OTP Algorithm: Select the required algorithm.
  • Digits: 6
  • Look Ahead Window: 1 A look-ahead window of 1 provides a 30-second synchronization buffer to accommodate minor clock differences between user devices and the Keycloak server.
  1. Click Save.

Enforcement Option 1: MFA for individual users

Use this method to enforce MFA for specific users during onboarding, testing, or compliance verification. To configure MFA for a user:

  1. In the Keycloak Admin Console, go to Users.
  2. Select the target local or LDAP user account.
  3. Open the Details tab.
  4. In Required User Actions, select Configure OTP.
  5. Click Save. At the next sign-in, Keycloak requires the user to register an authenticator application before granting access.

Enforcement Option 2: MFA for groups

For production environments, group-based enforcement is the recommended approach. Instead of configuring users individually, you can enable MFA for entire departments or teams by managing group membership.

Create an MFA enforced group

  1. In the Keycloak Admin Console, go to Groups.
  2. Click Create group.
  3. Enter MC_2FA_ENFORCED as the group name.
  4. Open the group and select the Attributes tab.
  5. Add the following attribute: 
    Key: mfaenabled
Value: true
  6. Click Save.

Create a conditional browser authentication flow

  1. Duplicate the default browser flow
  2. Configure the conditional OTP subflow
  3. Bind the authentication flow

Duplicate the default browser flow

  1. Go to Authentication.
  2. Locate the default browser flow.
  3. Open the flow actions menu and select Duplicate.
  4. Enter 2fa_browser as the flow name.

Configure the conditional OTP subflow

  1. Open the 2fa_browser flow.
  2. Locate the Browser - Conditional OTP subflow.
  3. Set the execution requirement to CONDITIONAL.
  4. Within the subflow, click Add execution or Add condition.
  5. Select Condition - User Attribute.
  6. Open the condition settings and configure the following values: 
    Alias: <any name>

User Attribute Name: mfaenabled

User Attribute Expected Value: true

Include Group Attributes: ON
  7. Click Save.
  8. Verify that OTP Form appears immediately after the user attribute condition.
  9. Set OTP Form to REQUIRED.
  10. Save the authentication flow.

Bind the authentication flow

  1. In Authentication, select the 2fa_browser flow.
  2. Open the flow actions menu.
  3. Select Bind Flow.
  4. Choose Browser Flow as the binding type.
  5. Save the configuration.

Manage MFA through group membership

After configuring the conditional authentication flow, administrators can enable MFA for multiple users by adding them to the MC_2FA_ENFORCED group. To add users to the MFA enforced group:

  1. Go to Groups.
  2. Select MC_2FA_ENFORCED.
  3. Open the Members tab.
  4. Click Add Members.
  5. Select one or more local or synchronized LDAP users.
  6. Click Add. Users who belong to the MC_2FA_ENFORCED group are required to enroll in MFA and complete OTP verification during authentication.

User enrollment experience

The enrollment experience is the same regardless of whether MFA is enforced through an individual user setting or group membership.

  1. Sign in to MC and enter your local or LDAP credentials.
  2. After validating the user's password, Keycloak determines whether MFA enrollment is required. If MFA is required, Keycloak pauses the sign-in process and displays an enrollment page containing a unique QR code.
  3. Register an authenticator application. Open a supported authenticator application, such as:
    • Microsoft Authenticator
    • Google Authenticator
    • Okta Verify
  4. Verify the OTP configuration. Scan the QR code. The authenticator application begins generating one-time passcodes. Enter the current passcode in the Keycloak verification page to confirm successful registration.
  5. Complete the authentication.
    After OTP verification succeeds, Keycloak completes the authentication process and establishes the MFA relationship for future sign-ins. You are granted access to MC and can access resources according to your assigned permissions and roles.

Federated server authentication

Federated servers store your organization's user credentials in a single location so you can authenticate user identities across one or more applications. The MC integrates with Keycloak to support LDAP and LDAPS federated server configurations.

MC can access only usernames in federated servers for authentication purposes—it cannot modify any other federated user information. To edit or reset a user password, contact your organization's federated server administrator.

For additional details about how LDAP and LDAPS federated services work with Vertica and MC, see LDAP authentication.

For additional details about configuring MFA for local and LDAP users, see Configure multi-factor authentication (MFA) for local and LDAP users.

Add SSL/TLS certificate

If you authenticate users with LDAPS or StartTLS, you must upload a certificate to the MC to encrypt communications between the MC and the server. If you do not upload a valid certificate, the MC cannot verify the connection:

  1. Log in to the Management Console, then go to MC Settings > SSL/TLS Certificates.
  2. In the Manage Authentication Certificates section, select Add New Certificate.
  3. Browse your filesystem and upload your certificate.
  4. Restart the MC.

After the MC restarts, the new certificate takes effect.

Set up a federated server

This section provides guidance about how to connect the MC to a federated server for MC user authentication. Only the MC SUPER administrator can configure an MC and federated server integration.

The steps to configure a federated server for MC user authentication vary by organization. Refer to the following sources for comprehensive documentation about integrating federated servers:

The following steps connect the MC and an OpenLDAP federated server:

  1. Log in to the Management Console, then go to MC Settings > User Federation. You are prompted to add an SSL/TLS certificate. OpenLDAP does not requie a certificate, so ignore the prompt and continue.

    The User Federation screen opens in a new tab.

  2. On the User Federation screen, select ldap from the Add provider... dropdown list.

    The Add user federation provider screen displays.

  3. In Required Settings, enter or select information for the following fields:

    • Console Display Name: Enter a name for the federated server. This value is listed in the grid on the User Federation screen.

    • Priority: Enter 0 to indicate the highest priority.

    • Edit Mode: Select READ_ONLY.

    • Vendor: Active Directory is populated in this field.

    • Username LDAP attribute: Enter cn=inetOrgPerson.

    • RDN LDAP attribute: Enter cn=inetOrgPerson.

    • UUID LDAP attribute: Enter cn=inetOrgPerson.

    • User Object Classes: Enter inetOrgPerson.

    • Connection URL: For LDAP, use port 389. For example, ldap://10.20.30.40:389.

    • Users DN: A distinguished name (DN) consists of two DC components. For example, dc=example,dc=com.

    • Bind Type: If the LDAP server supports anonymous binding, select none.

      Otherwise, select simple. This setting makes the Bind DN field available. In Bind DN, enter the administrator's DN and password.

  4. Select Save.

The federated server is listed in the grid on the User Federation screen. When you add a new user in MC, the new user is authenticated to each MC session with credentials stored in the federated server.

For details on adding a federated user, see User administration in MC.

Identity provider (IDP) authentication

You can authenticate users with an IDP service. The MC integrates with Keycloak to configure IDP services and supports the following identity protocols and social IDPs:

  • SAML v2.0
  • OpenID Connect v1.0
  • Keycloak OpenID Connect
  • Various social providers, including GitHub, Facebook, and Google.

The MC can access only usernames from IDP servers for authentication purposes—it cannot modify any IDP user information. To edit or reset a user password, you must log into your IDP server and edit the information.

The steps to configure an IDP for MC user authentication vary depending on the IDP service. Refer to the Keycloak IDP documentation for comprehensive details about integrating identity providers.

Integrate MC and Azure AD IDP

The following sections explain how to configure IDP authentication with Microsoft Azure AD OpenID Connect (OIDC). This requires that you register an application in Azure, and then add that application as an IDP in the MC. For comprehensive documentation about creating an app in Azure, see the Microsoft Azure documentation.

Register the app

First, you must create your application in Microsoft Azure:

  1. Log in to the Azure portal.

  2. In the search bar, enter Azure Active Directory and open it.

  3. In the + Add menu at the top, select App registration from the dropdown list.

  4. Complete the fields on Register an application. For details about each field, see the Microsoft Azure documentation.

  5. Select Register.

    Your new application's Overview page displays.

Next, create the client secret. This secret authenticates your Azure app to the MC:

  1. In the menu on the left, select Certificates & secrets.

  2. On the Client secrets tab, select + New client secret.

  3. In Add a client secret, enter a description, and choose an expiration date.

  4. Select Add.

    The new secret is listed in the Client secrets tab.

  5. Copy the secret listed in the Value column, and store it in a secure location for later use.

Next, add optional claims to your token configuration:

  1. In the left-hand menu, select Token configuration.

  2. Select + Add optional claim to open the Add optional claim pane to the right.

  3. In the Add optional claim pane, select ID as the Token type, and then select the following boxes:

    • email
    • given_name
    • family_name
    • upn

  4. Select Add.

    A pop-up displays and asks you about API permissions.

  5. In the pop-up, select the checkbox and select Add. The claims are listed on the Token configuration page.

Next, retrieve the client ID and application endpoint:

  1. Select Overview from the left-hand menu.

  2. In the Essentials section, copy the Application (client) ID.

    Save the Application (client) ID in a secure location for later use.

  3. At the top of the screen, select the Endpoints tab to display the application's available endpoints.

  4. Copy the value in OpenID Connect metadata document.

    Save this endpoint in a secure location.

Add Azure AD IDP to the MC

This section requires the following information from the Azure AD app:

  • Client secret Value
  • Application (client) ID
  • OpenID Connect metadata document endpoint

Only the MC SUPER administrator can add Azure AD as an IDP in the MC:

  1. Log in to the Management Console, then go to MC Settings > Identity Providers.

    The Identity Providers screen opens in a new tab.

  2. Select OpenID Connect v1.0 from the Add provider... list.

    The Add identity provider screen displays.

  3. In the top section, add or select the following:

    • Alias: (Optional) Edit this field to distinguish this IDP from others that you might integrate with the MC.
    • Display Name: Enter Azure AD. This is the name that displays on the IDP login button after you complete configuration.
    • Trust Email: Toggle to On.
    • First Login Flow: Select auto_detect so that the MC can detect the new user in the IDP during the first user login.

  4. In the OpenID Connect Config section, select or add the following:

    • Client Authentication: Select Client secret sent as post.
    • Client ID: Add the Azure AD Application (client) ID that you saved from the previous section.
    • Client Secret: Add the Azure AD Client secret Value that you saved from the previous section.
    • In Default Scopes, enter openid profile email.

  5. Go to the Import External IDP Config section. In Import from URL, add the OpenID Connect metadata document endpoint that you saved from the previous section.

  6. Select Import.

    MC imports the Azure application configuration and populates the URL fields.

  7. Select Save.

  8. Copy the value in Redirect URI and store it in a secure location for later use. You must add this URI in Azure.

Complete configuration

This section requires the Redirect URI value from Add the IDP to MC. Return to Azure, and complete the MC registration:

  1. Log in to the Azure portal.

  2. In the search bar, enter App registrations and go to your application's overview page.

  3. Select Authentication in the left menu.

  4. In Platform configurations, select Add a platform.

  5. Select Web, then add the Redirect URI value from the MC.

    For details about additional Redirect URI options and your Azure AD application, see the Microsoft Azure documentation.

  6. Select Configure.

After you complete the configuration, the MC SUPER administrator can add MC user accounts with user identities from Azure AD. Before each user can log in to the MC, they must accept the Microsoft Azure app permissions request.

Accept permissions request

After the MC SUPER administrator adds an Azure AD IDP user to the MC, the user must accept the Microsoft Azure permissions request to view the MC and access its data before they can log in to the MC:

  1. On the MC login screen, select the Azure AD option at the bottom of the Sign in to your account section.
  2. Enter your Azure credentials for your organization's Azure AD.
  3. When Microsoft requests permissions, select Accept to grant Azure AD access to the MC.

After you accept the permissions request, the user is authenticated to each MC session with Azure AD credentials.

OKTA SAML integration

SAML is an open, XML-based standard that allows secure web domains to exchange user authentication and authorization data. It is the core technology behind Single Sign-On (SSO), allowing you to log in just once using a single set of credentials and access multiple applications without needing to re-enter your password.

In an enterprise environment that uses a centralized identity provider (IdP), MC delegates authentication to Okta. When an administrator signs in to MC, the session is securely redirected from the console to the Okta gateway. Okta validates the administrator's credentials and enforces corporate multi-factor authentication (MFA) requirements, such as Okta Verify or TOTP tokens. After successful authentication, Okta returns a signed cryptographic assertion to Keycloak, which grants the administrator access to MC.

  1. Provision the OKTA SAML application.
  2. Configure the Keycloak execution flor.
  3. Configure Okta as a SAML identity provider in Keycloak.
  4. Pre-register an identity provider user in MC.

Provision the OKTA SAML application

  1. Sign in to your organization's Okta Administration console.
  2. Go to Applications > Applications and then select Create App Integration. Choose SAML 2.0.
  3. In General Settings, provide the application details. Then configure the following SAML settings:
    • Single Sign-On URL (ACS URL): Enter the Assertion Consumer Service (ACS) endpoint pointing for your Keycloak broker. https://<mc-keycloak-server>:<port>/auth/realms/vertica/broker/<okta-mfa>/endpoint. Okta sends the SAML assertion to this endpoint after successful authentication.
    • Audience Restriction (Audience URI): Enter the Keycloak realm URL. https://<mc-keycloak-server>:<port>/auth/realms/vertica.
      Keycloak validates this value to ensure that the SAML assertion is intended for the correct realm.
    • Name ID Format: Select EmailAddress. This setting uses the user's email address as the unique identifier across Okta and Keycloak.
  4. Assign the appropriate users or groups to the SAML application.

Configure the Keycloak execution flow

To reduce onboarding friction and prevent user registration issues during the initial federation setup, configure a streamlined identity-linking workflow.

  1. In the Keycloak Administration Console, select Authentication.

  2. Select Create flow. Enter AutoLink IDP Flow as the flow name.

  3. Configure the flow to use OR logic by creating only the following two execution steps and removing any default executions:

    • Create User If Unique - Set Requirement to ALTERNATIVE.
    • Automatically Set Existing User - Set Requirement to ALTERNATIVE. With both executions set to ALTERNATIVE, the flow succeeds if either condition is met.

  4. Save the flow.

Configure Okta as a SAML identity provider in Keycloak

  1. In the Vertica realm in Keycloak, go to Identity Providers.
  2. Add a new SAML v2.0 identity provider and specify as the alias.
  3. In your Okta application metadata, locate the required SAML endpoints and identifiers.
  4. Copy the Single Sign-On Service URL from the Okta application metadata and paste it into the corresponding field in Keycloak.

Example

https://org.okta.com/<app-id>/integrator-2996422_oktasaml_1/exk13m4trsnyt73kQ698/sso/saml

Keycloak redirects users to this Okta endpoint when they select Sign in with Okta. Keycloak also uses this endpoint to initiate the SAML authentication request.

  1. Copy the Identity Provider ID from the Okta application metadata and configure it in the corresponding Keycloak field.

Example

http://www.okta.com/exk13m4trsnyt73kQ698

The Identity Provider ID uniquely identifies the Okta application. Keycloak uses this value to verify that incoming SAML assertions originate from the correct Okta application and trusted identity provider.

  1. Configure the following security settings:
    • SAML HTTP-POST Binding: Enable this option to use HTTP POST for SAML message exchange.
    • Force Authentication: Set this option to ON. When enabled, Okta ignores existing browser sessions and prompts users to authenticate each time. This setting enforces password and MFA verification for every sign-in request.
  2. Expand Advanced Settings.
  3. In First Login Flow Override, select AutoLink IDP Flow.
  4. Click Save.

Pre-register an identity provider user in MC

Before a user can sign in through Okta, you must create the user account in MC and assign the appropriate role. MC uses its local user repository for role mapping and authorization.

Add an Identity Provider User

  1. Sign in to MC using an account with administrative privileges.
  2. Go to MC Settings > User Management.
  3. Click Add.
  4. In the Authentication list, select IDP.
  5. In the User Name field, enter the username or email address configured in Okta.

Example

sampleuser@gmail.com
  1. Assign the appropriate MC role, such as MC_ADMINISTRATOR or Db_Admin.
  2. Click Save.

Authentication Flow

The following sequence describes the authentication process when a user signs in to MC through Okta and Keycloak.

  1. User initiates sign-in.

The user opens MC and selects Sign in with Okta. MC forwards the authentication request to Keycloak.

  1. Keycloak redirects the user to Okta.

Keycloak processes the request and sends the browser to the Okta single sign-on service URL. As Force Authentication is enabled, Keycloak includes the ForceAuthn="true" parameter in the SAML authentication request.

  1. Okta authenticates the user.

Okta receives the authentication request and ignores any existing browser session.

As a result:

  • Users must enter their credentials for each sign-in request.
  • MFA verification is required.
  • First time users may be prompted to enroll in Okta Verify, by scanning a QR code.
  1. Okta Sends a SAML assertion to Keycloak

After the user successfully authenticates, Okta generates a signed SAML assertion and sends it to Keycloak through the configured Assertion Consumer Service (ACS) endpoint. Keycloak validates the assertion to ensure that it originated from the trusted Okta identity provider.

  1. Keycloak links the identity.

After validating the SAML assertion, Keycloak runs the configured AutoLink IDP Flow. Depending on the user state, Keycloak either creates a new identity provider link for the user, or associates the incoming identity with an existing user account.

  1. MC authorizes the user.

After successful authentication, the browser returns to MC.MC checks its local user repository for a matching IDP user account. If the user was pre-registered and assigned an MC role, MC maps the appropriate permissions and grants access. After successful authentication and authorization, the user is signed in to MC and can access resources based on the assigned MC role.