Skip to main content

Create pass-through authenticator definitions

Pass-through authenticator definitions specify what information IDaaS sends to an external service through an HTTP connector. The external service checks that information when a user tries to complete second-factor authentication with a pass-through authenticator. If the user provides the expected information, the connector returns a success response code and IDaaS allows authentication.

Placeholders​

Pass-through authenticator definitions support placeholders. Use a placeholder to mark where connector data belongs when you configure the request but do not yet have the actual value. IDaaS inserts the value when it sends the connector call.

You can use placeholders in the following locations:

  • URL path (not in hostname/domain section)
  • Authorization header (not name)  
  • Request Body

Placeholder restrictions​

The following are placeholder restrictions:

  • Placeholders are marked by {{}}
  • Placeholder must start with any of these prefixes:
    • REQ.—The placeholder's value comes from the Request body.
    • USER.—The placeholder value comes from a user attribute.
    • ENV.—The placeholder value comes from environment data. Only clientIp is supported.
    • AUTH—The placeholder value comes from authentication information configured in the connector.
  • Placeholders prefixed by REQ., USER., or ENV. include dynamic data. The name after the prefix must match a valid source field. AUTH is a special placeholder type.
  • Domain and subdomain in the URL are static—no placeholders are allowed.
  • Placeholders cannot use delimiter symbols. The placeholders and resultItems used in the same HTTP Connector must be unique.
  • A configured placeholder must resolve to a value from one of the following sources:
    • AUTH—HTTP Connector configuration
    • REQ.
    • ENV.
    • UI input
    • USER.—User attribute configuration
  • All placeholder values are required. If any placeholder cannot resolve a matching value, the connector call fails.

Create a pass-through authenticator definition​

  1. Click > Configuration > Pass-through Authenticator Definitions. The Pass-through Authenticator Definitions page appears.

  2. Click . The Add Pass-through Authenticator Definition page appears.

  3. Enter a Name for the pass-through authenticator definition.

  4. Optional. Complete the Challenge Connector Details to create the HTTP Connector used to retrieve a challenge for authentication.

    1. Click Add next to Challenge HTTP Connector. The Add HTTP Connector page appears.

    2. Enter a Name for the request.

    3. From the Method drop-down list, select the HTTP request method used to make the request to the external service.

    4. In the URL field, enter the URL of the login endpoint of the external service. If applicable, add required parameters to the URL that are used to make the request to the external service.

      note

      The Domain part of the URL must be an external host name or an IP address. Internal hostnames are not allowed.

    5. From the Authorization Type, drop-down list, select the authentication method passed to the external resource to obtain the authentication token. Depending on the selection you make, you are prompted for additional information as follows:

      • Basic. Enter the User Name and Password for the external service.
      • BEARER_TOKEN. Enter the token value used by the external service.
      • API_Key. Select the API Key Type and enter the API Key Value.

    6. If required, click Add to add authorization Headers to the HTTP request, and then enter the Header Name and Header Value. You can add as many headers as required to make the request.

    7. If required, In the Results Items section, set the values used to return the risk assessment as follows:

      1. Enter the Key that is used to assess the risk.
      2. Select the Value Type, which can be either a String or a Numeric value, and enter the JsonPath for the results item.
      3. Click Add to define additional Keys used to return the results of the risk assessment.
      note

      For more information on Query expressions for JSON, see RFC 9535, JSONPath: Query Expressions for JSON

    8. Optional. In the Request Body, add additional content, as required.

  5. If you configured a challenge connector, click Add to save the HTTP Connector and return to the Pass-through Authenticator Definition.

  6. If you configured a challenge connector, select the Success Criteria used to determine whether the request was successful:

    • 2xx Response Code. The request was successful and the expected response was returned to the external service.
    • Response Body. Includes the data requested by IDaaS in the GET request.

  7. Complete the Authenticate Connector Details to create the HTTP Connector used to authenticate a user from an Authentication API application.

    1. Click Add next to Authenticate HTTP Connector. The Add HTTP Connector page appears.

    2. Enter a Name for the request.

    3. From the Method drop-down list, select the HTTP request method used to make the request to the external service.

    4. In the URL field, enter the URL of the login endpoint of the external service. If applicable, add required parameters to the URL that are used to make the request to the external service.

      note

      The Domain part of the URL must be an external host name or an IP address. Internal hostnames are not allowed.

    5. From the Authorization Type, drop-down list, select the authentication method passed to the external service to obtain the authentication token. Depending on the selection you make, you are prompted for additional information as follows:

      • Basic. Enter the User Name and Password for the external service.
      • BEARER_TOKEN. Enter the token value used by the external service.
      • API_Key. Select the API Key Type and enter the API Key Value.

    6. If required, click Add to add authorization Headers to the HTTP request, and then enter the Header Name and Header Value. You can add as many headers as required to make the request.

    7. If required, In the Results Items section, set the values used to return the risk assessment, as follows:

      1. Enter the Key that is used to assess the risk.
      2. Select the Value Type, which can be either a String or a Numeric value, and enter the JsonPath for the results item.
      3. Click Add to define additional Keys used to return the results of the risk assessment.
      note

      For more information on Query expressions for JSON, see RFC 9535, JSONPath: Query Expressions for JSON.

    8. Optional. In the Request Body, add additional content, as required.

  8. Click Add to save the HTTP Connector and return to the Pass-through Authenticator Definition.

  9. Select the Success Criteria that is used to determine whether the request was successful:

    • 2xx Response Code. The request was successful and the expected response was returned to the external service.
    • Response Body. Includes the data requested by IDaaS in the GET request.

  10. Click Save to save the pass-through authenticator definition and return to the Pass-through Authenticator Definitions page.

Validate your changes​

After you save, verify the following:

  1. The new definition appears in the Pass-through Authenticator Definitions list.
  2. The configured placeholders resolve correctly during test authentication.
  3. The connector returns the expected success criteria for valid requests.
  4. Invalid requests return a non-success result and block authentication.