Skip to main content
Version: NG-3.1

ADFS Integration

ADFS (Active Directory Federation Services) integration enables Single Sign-On (SSO) in vuSmartMaps. Instead of entering username and password directly in vuSmartMaps, users are redirected to an external identity provider (such as ADFS) for authentication. Once authenticated, users are securely redirected back to vuSmartMaps.

ADFS is useful when organizations want:

  • Single Sign-On (SSO) across applications.
  • Centralized identity management.
  • Secure, token-based authentication.
  • Integration with enterprise identity providers.

This improves user experience and strengthens security.

Configure ADFS​

A single sign-on experience is just a few steps away. You’re about to make logins effortless.

ADFS configuration can be performed using either the identity provider or vuSmartMaps. The vuSmartMaps ADFS configuration API wraps around the identity provider's API.

Step-by-Step Instructions​

ADFS Configuration Guide​

Follow these step-by-step instructions to configure OpenID Connect v1.0 using the Identify Providers section:

  1. Accessing the Configuration Page: Open the identity provider’s administration console and navigate to the "Identity Providers" section. Click on OpenID Connect v1.0 in the User-defined section to initiate the configuration process.

  2. Setting up the OpenID Provider: You'll be presented with a form similar to the one shown below:

    1. Alias: Choose a unique alias to identify your identity provider in the IDP.
    2. Display Name: Define the name that will be displayed to users in the login form. For example, if you use "Azure AD" as the display name, a corresponding button "Sign in with Azure AD" will appear in the login form.
    3. Display Order: If configuring multiple identity providers, set the display order to determine button rendering in the UI. Leave it blank for default ordering.
    4. Discovery Endpoint: Provide the OpenID configuration URL for the app registered with your identity provider. This URL enables the IDP to fetch necessary URLs like token URL, authentication URL, user info endpoint, etc.
    5. Client Authentication: Specify how the IDP will interact with the identity provider. Use the default value ("Client secret sent as post") unless instructed otherwise.
    6. Client ID and Client Secret: Obtain these values from the app registered with your identity provider.

  3. Complete the Configuration: Fill in the required fields based on your OpenID Connect setup. Once all the settings are configured, proceed to the next step.

  4. Save and Test Configuration: After entering the necessary information, save the configuration. The IDP will validate the setup by testing the connection to the OpenID provider.

  5. Verification and Activation: Once the configuration is saved and tested successfully, you can proceed to activate the OpenID Connect integration. This will enable users to log in using the configured OpenID provider.

Mappers​

Besides configuration, clients often create mappers to synchronize user roles and memberships. Our API exposes three mapper types:

  1. Advanced Claim to Group: Assigns users to specific groups based on claims.
  2. Attribute Importer: Imports declared claims from tokens into user properties.
  3. Hardcoded Attribute: Sets a predefined value to a specific user attribute.

Signing in with ADFS Provider​

Upon successful ADFS configuration, an additional login button will appear for the configured identity provider. Proper configuration prompts redirection to the provider's authentication form. Once logged in, you will be redirected to the IDP. If it's your first login, you must provide additional user information.

  1. Access the ADFS Login: Upon successful configuration, a new button will appear alongside the regular login options. Click on this button to initiate the ADFS login process.

  1. Authentication Form: If your configuration is correct, clicking the ADFS login button will take you to the authentication form of the configured identity provider. Below are screenshots illustrating this process using Azure AD as an example:

  1. Completing the Provider Login: Once redirected to the identity provider's authentication form, follow the provided instructions to log in using your identity provider credentials. After successfully logging in through the identity provider, you will be redirected back to the identity provider platform.
  2. Additional User Information: If this is your first time signing in with the configured identity provider, you may be prompted to provide additional user information. This step ensures seamless integration for the identity provider.

  1. Logged in to External User Account: Once you've filled in the required information, you will be logged into vuSmartMaps as an external user. Enjoy a smooth login experience without the need for additional credentials.
note

Depending on the mappers you've configured, users can be automatically assigned to groups based on the mapper logic. This streamlines access control and ensures that users are directed to the appropriate resources within the platform.

By successfully signing in with your ADFS provider, you enhance security and user experience by leveraging established authentication infrastructure and streamlined access to external systems.

What Happens After the Steps​

After successfully configuring the User Federation, the system begins operating based on the configured LDAP or ADFS integration. This impacts user creation, authentication, role assignment, and access control within vuSmartMaps.

LDAP​

After LDAP integration is configured and synchronization is performed, users from the LDAP directory are imported into vuSmartMaps and become visible in the User & Roles module. If filters such as Vunet-* are applied, only matching roles or groups are imported, helping restrict the scope of role mapping.

Role assignment depends on the integration scenario:

  • In Scenario 3, roles are derived directly from LDAP group mappings.
  • In Scenario 2, roles are assigned locally within vuSmartMaps.

Permissions are enforced using RBAC once roles are assigned.

Users log in using the standard login form with their LDAP credentials. Authentication is validated against the LDAP server, and access is granted based on mapped roles and permissions. After login, access to dashboards, alerts, reports, and other resources is controlled through roles, object-level permissions, and data access policies.

Synchronization ensures that changes in LDAP are reflected in vuSmartMaps:

  • Full sync updates all users.
  • Incremental sync updates only changed users.
  • Role and group changes are reflected based on configuration.

ADFS​

When ADFS integration is configured, users authenticate using Single Sign-On (SSO) instead of entering credentials directly into vuSmartMaps. During login, users click the SSO login option and are redirected to the ADFS identity provider. After successful authentication, ADFS returns a secure token to vuSmartMaps, which is used to log the user into the platform.

If the user is logging in for the first time, a user profile may be created in vuSmartMaps. Once authenticated, access is granted based on the roles and permissions configured within the platform. As with LDAP, access to dashboards, alerts, reports, and other resources is controlled through RBAC, object-level permissions, and data access policies.

Tips and Best Practices​

LDAP Configuration​

  • Always test connection and authentication before saving.
  • Use Subtree search scope for large organizations.
  • Use LDAP filters to limit unnecessary user imports.
  • Enable pagination for large datasets.

Mapper Configuration​

  • Always configure mappers before syncing users.
  • Use User Attribute Mapper for critical fields like email.
  • Use Group LDAP Mapper for role mapping.
  • Apply filters like Vunet-* to control role import.

Role Management​

  • Prefer group-based role mapping over manual assignment.
  • Keep role names consistent between LDAP and vuSmartMaps.
  • Regularly review permissions.

Sync Strategy​

  • Use incremental sync for performance.
  • Schedule periodic full sync for consistency.

Security​

  • Use StartTLS or secure connection wherever possible.
  • Avoid anonymous bind unless absolutely required.

Troubleshooting​

  1. Issue: LDAP connection cannot be established or “Test Connection” fails.

    • Possible Cause:

      • Incorrect Connection URL or port.
      • Network connectivity issues between vuSmartMaps and LDAP server.
      • Firewall restrictions blocking LDAP communication.
      • TLS/StartTLS configuration mismatch.

    • Solution:

      • Verify the Connection URL format (including protocol, host, and port).
      • Ensure network connectivity to the LDAP server.
      • Check firewall rules and open required ports.
      • Validate StartTLS configuration and certificates, if enabled.

  2. Issue: “Test Authentication” fails or users are unable to log in using LDAP credentials.

    • Possible Cause:

      • Incorrect Bind DN or Bind Password.
      • Invalid Bind Type configuration.
      • LDAP service account does not have sufficient permissions.

    • Solution:

      • Recheck Bind DN and password.
      • Ensure Bind Type is correctly set (typically “Simple”).
      • Validate that the service account has permission to query LDAP.

  3. Issue: Users are not imported or only partially imported during synchronization.

    • Possible Cause:

      • Incorrect Users Domain Name (DN).
      • Misconfigured LDAP User Filter.
      • Incorrect Search Scope (One Level instead of Subtree).
      • Pagination disabled for large directories.

    • Solution:

      • Validate the Users Domain Name (DN path).
      • Review and correct LDAP User Filter syntax.
      • Use Subtree search scope for deeper directory structures.
      • Enable pagination for large datasets.

  4. Issue: Users are imported but roles are missing or incorrectly assigned.

    • Possible Cause:

      • Group LDAP Mapper not configured.
      • Incorrect LDAP group filter.
      • LDAP groups not matching expected naming pattern.
      • Scenario mismatch (e.g., expecting LDAP roles but using Scenario 2).

    • Solution:

      • Configure Group LDAP Mapper correctly.
      • Verify LDAP group DN and filter configuration.
      • Ensure LDAP groups follow expected naming conventions (e.g., Vunet-*).
      • Confirm the correct LDAP integration scenario is being used.

  5. Issue: Unable to remove a role from an LDAP user.

    • Possible Cause: Role mapping is controlled by LDAP.

    • Solution:

      • Modify or remove the role assignment directly in LDAP.
      • Re-run synchronization to reflect changes in vuSmartMaps.
note

Role mappings originating from LDAP cannot be modified within vuSmartMaps.

  1. Issue: Users are unable to log in using LDAP credentials.

    • Possible Cause:

      • Invalid user credentials.
      • LDAP authentication failure.
      • User not synchronized into vuSmartMaps.

    • Solution:

      • Verify user credentials.
      • Ensure LDAP authentication is working correctly.
      • Confirm user exists in synchronized LDAP data.

  2. Issue: SSO login fails or users are not redirected correctly.

    • Possible Cause:

      • Incorrect Discovery Endpoint.
      • Invalid Client ID or Client Secret.
      • Identity provider configuration not activated.
      • Token validation failure.

    • Solution:

      • Verify OpenID Discovery Endpoint URL.
      • Recheck Client ID and Client Secret.
      • Ensure ADFS provider is enabled and active.
      • Validate identity provider configuration.

  3. Issue: SSO login option is not visible on the login page.

    • Possible Cause:

      • ADFS provider not configured or not activated.
      • Incorrect display configuration.

    • Solution

      • Verify ADFS configuration is saved and activated.
      • Check Display Name and Display Order settings.

  4. Issue: Recent changes in LDAP (users or roles) are not reflected in vuSmartMaps.

    • Possible Cause:

      • Synchronization not triggered.
      • Incorrect sync configuration.
      • Long sync intervals.

    • Solution:

      • Trigger manual synchronization.
      • Verify sync configuration (full vs incremental).
      • Adjust sync intervals based on requirements.

FAQs​

Can I use LDAP and local users together?

Yes. vuSmartMaps supports hybrid models where both LDAP and local users coexist.

Can I override LDAP roles in vuSmartMaps?

Yes. You can assign local roles in addition to LDAP roles, depending on the scenario.

Why can’t I remove a role from an LDAP user?

Because role mapping is controlled by LDAP. It must be removed from LDAP itself.

What happens if LDAP is down?

Users may not be able to authenticate. It is recommended to keep a fallback admin account.

Do I need Group LDAP Mapper always?

No. It is required only in Scenario 3 (when roles are pulled from LDAP).

How often should I sync users?
  • Use incremental sync frequently
  • Use full sync periodically
Can I restrict which roles are imported?

Yes. Use LDAP filters such as Vunet-*.