Skip to main content

Configuring an Identity Enterprise Agent

The Identity Enterprise Agent (IDE Agent) is a software application that is bundled into a Gateway Instance in Identity as a Service (IDaaS).

The IDE Agent allows Entrust Identity Enterprise (IDE) client applications to continue authenticating users during migration from IDE to IDaaS. By acting as a proxy, the IDE Agent determines the correct authentication source—IDaaS or IDE—without requiring changes to existing IDE client applications.

Understanding how a Gateway and an IDE Agent work together​

A Gateway is a logical grouping of Gateway Instances that share the same configuration. Each Gateway Instance is deployed as a virtual appliance in your environment. After deployment, you must register Gateway Instances with the Gateway so they receive shared configuration data and updates.

All Gateway Instances within the same Gateway operate in an active‑active mode. IDE client applications can send authentication requests to any available Gateway Instance. As all instances share the same configuration, including the IDE Agent, authentication behavior is consistent across all Gateway Instances.

The IDE Agent performs the following actions within each Gateway Instance:

  • Intercepts authentication requests from IDE client applications.
  • Checks whether the user exists in IDaaS.
  • Routes the request to the appropriate platform based on the result (for example, “user not found”).
  • Handles challenge and response messages for both IDaaS and IDE.
  • Returns normalized exceptions in IDE format.

These behaviors ensure that authentication continues working throughout the migration period.

For information about Gateway and Gateway Instances, see: Gateways.

Interacting with IDE Server instances​

The IDE Agent can communicate with any available IDE Server instance. Environments typically include a primary IDE Server and one or more replica servers for high availability. If the primary IDE Server becomes unavailable, authentication requests are automatically routed to a replica. This failover occurs without requiring changes to IDE client applications.

If an IDE load balancer is deployed, the IDE Agent sends IDE‑bound authentication requests to the load balancer. The load balancer routes each request to an available IDE Server instance and manages server‑level failover.

Interacting with IDaaS​

All Gateway Instances communicate directly with IDaaS to authenticate users who have already been migrated. As Gateway Instances share the same configuration, authentication behavior remains consistent across the deployment.

Handling authentication requests​

The IDE Agent determines how each authentication request should be processed. This behavior is automatic and does not require your configuration.

Authenticating users in IDaaS

  • The IDE Agent acts as a transparent proxy between IDE client applications and IDaaS. It automatically converts authentication requests and responses between the IDE format and the IDaaS format, without requiring IDE client applications to change their integration or request format.

Authenticating users in IDE

  • If IDaaS returns “user not found,” the IDE Agent forwards the original SOAP request to IDE without making any changes.

Processing challenge‑response flows

  • The IDE Agent relays challenges and responses between the IDE client application and the appropriate platform (IDaaS or IDE).

  • The IDE Agent only changes the message format when sending SOAP‑based authentication requests to IDaaS.

  • The IDE Agent maintains the session information so multi‑step authentication continues without interruption.

Returning normalized exceptions

  • IDaaS and IDE return errors in different formats.

  • The IDE Agent converts all errors into IDE‑compatible exception formats before returning them to the IDE client application.

Supported authentication types​

The IDE Agent supports these authentication types:

  • Grid authentication
  • Knowledge-based authentication (KBA)
  • One-time password (OTP) authentication
  • Machine authentication
  • Password authentication (IDE or IDaaS passwords)
  • Token authentication
    • push authentication with mobile soft tokens
note

Other authentication types, including Passkey authentication and RADIUS authentication, are not supported.

Responsibilities of an IDE Agent​

The IDE Agent is responsible for:

  • Authenticating users against IDaaS

    Handles authentication for users who have already been migrated from IDE to IDaaS.

  • Routing authentication requests to the Entrust Identity Enterprise

    Forwards requests to the appropriate IDE Server instance when users have not yet been migrated to IDaaS.

  • Managing retry and failover operations

    Improves reliability by automatically retrying failed authentication requests under defined conditions and redirecting requests to alternate IDE or IDaaS endpoints when a service becomes unavailable.

  • Maintaining session continuity across systems

    Preserves a consistent session experience regardless of whether authentication occurs in IDaaS or IDE.

Limitations of the IDE Agent​

The following limitations apply when the IDE Agent is used as a proxy between IDaaS and IDE.

Duplicate user IDs across IDaaS and IDE are not supported​

If a duplicate user ID exists in both IDaaS and IDE, authentication issues can occur. For example, when an IDE user attempts to authenticate, the IDE Agent first checks IDaaS. If the user ID exists in IDaaS, IDaaS returns an authentication challenge for the IDaaS user. The IDE user may respond incorrectly to this challenge, which can result in the IDaaS user account being locked.

To prevent this issue, you must ensure that duplicate user IDs do not exist across IDaaS and IDE.

Differences in group handling between IDaaS and IDE​

IDaaS and IDE handle user groups differently:

  • In IDE, users with the same user ID can exist in different groups. For example, admin/bob and banking/bob are treated as separate users.

  • In IDaaS, a user ID is unique. A user can belong to multiple groups (for example, admin and office-sports), but the user ID itself cannot be duplicated.

Due to this difference, you must ensure that:

  • IDE users are mapped to the appropriate IDaaS groups during migration.

  • Group-based access and permissions are maintained correctly after migration.

Risk‑Based Authentication may treat migrated IP addresses as high risk​

When IDE users are migrated to IDaaS, their existing location history data is also migrated. When these users authenticate through the IDE Agent proxy, the following behavior can occur:

If a migrated user authenticates through the IDE Agent proxy from an IP address that already exists in the user’s location history, IDaaS can still evaluate the authentication as high risk and require step‑up authentication.

Example behavior​

  1. A user is migrated from IDE to IDaaS with existing IP addresses in the user’s location history.
  2. Location history checks are enabled for the user in IDaaS.
  3. The user authenticates through an IDE client via the IDE Agent proxy and supplies an IP address that exists in the migrated location history.
  4. IDaaS evaluates the authentication as high risk and can reject the challenge based on resource rules (for example, returning AUTH_TYPE_NOT_ALLOWED).

As a result, authentication can require step‑up verification even when the IP address exists in the migrated location history.

Cause of behavior​

This behavior occurs because risk evaluation for IP addresses can differ between IDaaS and IDE after migration. As a result:

  • The same IP address may be evaluated with a different risk score in IDaaS than in IDE due to differences in the latitude and longitude values used during risk evaluation.
  • Location history entries that were migrated from IDE may not be treated as low risk during authentication through the IDE Agent proxy.
  • Authentication events processed by IDaaS can create new location history entries instead of updating the migrated entries.

Impact​

  • Migrated users may be required to perform step‑up authentication when authenticating through the IDE Agent proxy, even when using IP addresses that exist in their location history.
  • This behavior is expected when Risk‑Based Authentication policies are evaluated by IDaaS after user migration.

Authentication response details are limited in IDaaS​

When authentication occurs through the IDE Agent proxy, IDaaS does not return certain authentication response details that IDE returns.

Specifically, IDaaS does not return:

  • Shared secrets
  • Historical authentication metadata, such as:
    • The time of the last successful authentication.
    • The time of the last failed authentication.
    • The authentication method used in previous events.

As a result, authentication responses returned by IDaaS contain fewer details than responses returned by IDE, even though authentication in both cases occurs through the IDE Agent proxy.

Legacy authentication behaviors may differ after migration​

Not all authentication behaviors from legacy IDE environments carry over identically after migration to IDaaS. Differences in challenge selection, response detail, and evaluation behavior are expected when authentication is processed by IDaaS through the IDE Agent proxy.

The following observable differences may occur after migration and are expected behavior:

  • Authentication challenges returned by IDaaS after migration may differ slightly from those returned by IDE prior to migration.
  • If a client requests a specific authenticator that is not available, IDaaS may automatically select an alternative challenge.
  • Authentication results remain valid, but IDE and IDaaS may return different response details.

For example, when a user submits an invalid response to an authentication challenge:

  • IDaaS returns an exception containing only the error code (for example, INVALID_RESPONSE).
  • IDE returns a more detailed response (for example, INVALID_RESPONSE: User <userid> has entered an invalid response to a challenge).

These differences in challenge selection and response detail are expected behavior and do not indicate a defect.

Configuring an IDE Agent​

Configuring an IDE Agent enables correct routing of authentication requests between IDaaS and IDE and ensures failover and session continuity. Complete the procedure below to configure an IDE Agent.

Prerequisites​

Before you begin, make sure you have created and configured a Gateway Instance. For information about creating and configuring a Gateway Instance, see: Create and configure a Gateway Instance.

To configure an IDE Agent​

  1. Log in to your IDaaS account.

  2. Click > Resources > Gateways. The Gateways page appears.

  3. In the gateway section, select the Gateway Instance to add the IDE Agent.

  4. Click the more icon at the end of the Gateway Instance. A menu appears.

  5. Select Advanced Settings. The Advanced Agent Settings page appears.

  6. In the IDE Instances section, click Add. The IDE Instance page appears.

  7. In the IDE Instance page, complete the following steps:

    a. For Hostname, enter the hostname of your IDE Server instance.

    b. For Port, enter the port your IDE Server instance uses.

    note

    Complete steps 7.c to 7.e below if you need to use SSL. If you do not need to use SSL, skip to Step 8.f.

    c. (Optional) Select Use SSL based on your requirements.

    d. (Optional) Click Import SSL certificate (Required). The Open File page appears.

    e. (Optional) Select the required SSL certificate and click Select. The system returns to the IDE Instance page.

    f. Click Add. The system returns to the Advanced Agent Settings page.

    g. Repeat steps 7.a. to 7.f. if you need to add multiple IDE Server instances.

    note

    When you add or update configuration settings for a Gateway Instance, the settings are automatically applied to all Gateway Instances within the same Gateway.

    note

    If the IDE Instances section lists several IDE Server instances, you can drag them into the order you want the system to use during failover.

  8. In the Advanced Agent Settings page, enter a value for the following fields:

    FieldDescription
    Failover Delay ValueSpecifies the wait time between attempts to reconnect to the current IDE Server instance.
    Valid wait time units:
    -
    Milliseconds (ms)
    - Seconds (sec)
    - Minutes (min)
    - Hours (hr)
    - Days (day)
    Default: 500 ms
    Failover Retries ValueSpecifies the number of times to retry to connect before failing over to the next IDE Server instance in the list. Default: 1
    Failover Restore ValueSpecifies the wait time before attempting to reconnect to the primary IDE Server instance.
    Valid wait time units:
    -
    Milliseconds (ms)
    - Seconds (sec)
    - Minutes (min)
    - Hours (hr)
    - Days (day)
    Default: 3600 sec
    note

    Although users can select different time units (for example, minutes or hours), the IDE Agent converts all values to seconds before sending them to the backend. For example:

    • 1 hour is stored as 3600 seconds
    • 10 minutes is stored as 600 seconds

  9. Click Save.