Integrate Authentication API

Add an Authentication API application to integrate your application with the IDaaS authentication APIs. After you configure the application, users enter IDaaS challenge responses in your application interface, and your application sends those responses to IDaaS to authenticate users and grant access.

See the Identity as a Service Authentication API Guide for more information.

Step 1: Add an Authentication API and configure the General settings

To create an Authentication API application, complete the following steps.

1. Go to > Security > Applications. The Applications page appears.
2. Click +. The Select an Application Template page appears.
3. Do one of the following:
   • Select the IDaaS Integrations button and scroll to find the application you want to add to IDaaS.
   • In the Search bar, enter a search option to filter for the application you want to add to IDaaS.
4. Click Authentication API. The Add Authentication API page appears.
5. Configure the App Settings.
   1. In the Application Name field, type a name for your application.
   2. In the Application Description field, enter a description for your application.
   3. Copy and paste the Application ID into the IDaaS API calls being used by your application.
   4. Select the Source of Client IP Address for Resource Rule Risk Factors and Audits. The options are:
      • Not provided. The IP address is not provided and is not extracted from the connection.
      • Provided in the API. The IP address is provided in the request body of the API.
      • From the incoming HTTP connection. The IP address is extracted from the connection.
6. Click Show Advanced Settings to configure the advanced settings, and select the following optional settings:
   • Use Client IP Address Only for Audits to allow Authentication API requests to exclude the client IP address from resource rule risk factor evaluation while retaining it in authentication audits.
   • Require User Verification to require user verification through the Auth API for Identity Provider authentication.
   • Manage Client Values to allow the Auth API to call self-admin (internal) APIs that are used to manage client values.
7. Click Save.

Choose the client IP address source

The client IP address source determines which address IDaaS uses for resource rule risk factors and authentication audits. The following table shows the typical source for each integration pattern.

Integration pattern	Typical client IP address source	Request requirement
Browser calls IDaaS directly	From the incoming HTTP connection	Omit clientIp. IDaaS uses the source address of the connection.
Browser calls your backend, then IDaaS	Provided in the API	Collect the end user's IPv4 address in your backend and include it as clientIp in each Authentication API request. IDaaS rejects a provided value that is not a valid IPv4 address.
No client IP address is available	Not provided	Omit clientIp. Do not use this option when the resource rule contains IP-based risk factors. A missing IP address can cause those factors to fail and increase the evaluated risk.

The following diagram shows where the client IP address and machine data enter each request path and how IDaaS uses them:

When you select Provided in the API, IDaaS uses the clientIp value from the request body. When you select From the incoming HTTP connection, a clientIp value in the request body does not replace the connection address.

Backend and proxy connections

If your backend or a proxy calls IDaaS, From the incoming HTTP connection can identify that intermediary instead of the end user. Select Provided in the API when IDaaS must evaluate the end user's address, and accept forwarded addresses only from trusted infrastructure.

Browser applications that call the Authentication API directly must also have an allowed Authentication API CORS origin. See Manage Cross Origin Resource Sharing (CORS).

If you enable Use Client IP Address Only for Audits, include ignoreIPAddressForRBA with a value of true in each query, challenge, and challenge completion request where the IP address must be excluded from risk evaluation:

{
  "clientIp": "203.0.113.10",
  "ignoreIPAddressForRBA": true
}

If you omit ignoreIPAddressForRBA or set it to false, IDaaS uses the client IP address for configured resource rule risk factors. IDaaS always retains the address in the authentication audit.

Step 2: Configure a resource rule

1. Click the Resource Rules tab.

2. Click Add Resource Rule.

3. Configure the resource rule for your authentication policy. The following example uses location, machine, and transaction signals to require stronger authentication when IDaaS evaluates elevated risk.

   Resource rule setting	Example configuration
   Name	Authentication API RBA example
   Group access filter	Do not add this filter when the rule applies to all users. Add selected groups when the rule applies only to those users.
   ACR access filter	Optional. Select the knowledge ACR when clients send "requestAcrs": "knowledge". Omit this filter when ACR must not determine whether the rule applies.
   Risk factors	Add Geolocation, Location History, Travel Velocity, Machine Authentication, and Transaction when your policy uses all the corresponding signals.
   Risk weights	Assign weights based on the relative importance of each configured factor. Use Risk Simulation to confirm that the combined results produce the intended risk level.
   Low-risk outcome	Select an authentication flow that requires password authentication.
   Elevated-risk outcome	Select an authentication flow that requires password authentication and a second factor. Configure separate medium- and high-risk outcomes if your policy treats them differently.

4. Configure each added risk factor:

   • For Geolocation, select the allowed or denied countries.
   • Location History uses the tenant's risk-based authenticator settings.
   • Travel Velocity uses the configured travel velocity threshold.
   • For Machine Authentication, configure the fingerprint mismatch risk limit.
   • For Transaction, select the transaction rules and configure the risk limit. The request detail names must match the transaction items used by these rules.
   • Optional. Add External when the rule uses a configured external risk engine.

5. Configure the risk weights, risk-level thresholds, and authentication flows for low, medium, and high risk.

6. Use Risk Simulation to verify representative combinations of passed and failed factors.

7. Save and enable the resource rule.

For complete configuration instructions, see Create resource rules. For requests that supply the inputs used by this example, see Risk-based authentication.