Skip to main content

Getting Started

IDaaS provides an Authentication API that lets you authenticate users programmatically with supported authenticators. Use this guide to create an Authentication API application, review the authentication flow, initialize a client, and make your first authentication request.

Start here​

Start with the resource that matches your task:

  • Use the Authentication API reference when you need endpoint details, request and response schemas, or interactive testing. Before sending test requests from the API Explorer, enter your IDaaS tenant URL and add this site's origin to your IDaaS CORS origins.
  • Use Client setup when you want to install a generated client for your preferred programming language.

Download the OpenAPI file​

Download the raw OpenAPI JSON file when you want to import the schema into Postman, generate a client, or validate requests locally.

Prerequisites​

Before you run the examples in this guide, make sure you have:

Create an Authentication API application in IDaaS​

  1. Go to your IDaaS Admin portal and navigate to Security > Applications.
  2. Click +, and then select Authentication API from the list of available applications.
  3. In the General tab, enter the name and description of your application.
  4. Click Next.
  5. In the Setup tab, set the Source of Client IP Address for Resource Rule Risk Factors and Audits.
  6. In the Complete tab, click Copy to copy the applicationID to your clipboard. You need the applicationID to initialize the Authentication API. Example: 9aaf0071-3f79-4663-9782-932c7d53c3da.
  7. Add a resource rule to your Authentication API application.
Required setup

A resource rule must be added to your Authentication API application.

Authentication flow​

IDaaS uses three API calls to complete an authentication challenge:

  1. Get User's Authenticators.
  2. Select Authenticator.
  3. Complete Authentication Challenge.

Make these API calls sequentially. Each response contains information that is required to complete the next call.

Select an available authenticator​

Use an authenticator returned in authenticationTypes or availableSecondFactor by Get User's Authenticators. The available values depend on the user's registered authenticators and the resource rule selected for the request. Do not construct the value from a fixed list.

MACHINE is used internally for Machine Authentication risk evaluation. It cannot be selected for an Authentication API challenge. Send machine data in machineAuthenticator instead.

Initialize the Authentication API client​

To call the API, initialize the Authentication API client using the applicationID you copied when you created the application.

import com.entrustdatacard.intellitrust.auth.ApiClient;
import com.entrustdatacard.intellitrust.auth.api.AuthenticationApi;
import com.entrustdatacard.intellitrust.auth.model.AuthenticatedResponse;
import com.entrustdatacard.intellitrust.auth.model.UserAuthenticateParameters;
import com.entrustdatacard.intellitrust.auth.model.UserChallengeParameters;

public class Main {
  private static final String APPLICATION_ID = "YOUR_APPLICATION_ID";
  private static final String HOST_NAME = "YOUR_HOST_NAME";

  public static void main(String args[]) throws Exception {
      // initialize the API client with the IDaaS hostname
      ApiClient apiClient = new ApiClient();
      apiClient.setBasePath(HOST_NAME);
  }
}

Try API requests​

After you initialize the client, you can make calls to the Authentication API. The following example authenticates a user who is registered in IDaaS and assigned the selected authenticator.

String authType = args[0];
String userId = args[1];

UserChallengeParameters challengeParms = new UserChallengeParameters();
challengeParms.setApplicationId(APPLICATION_ID);
challengeParms.setUserId(userId);

AuthenticatedResponse challengeResponse = authApi.userChallengeUsingPOST(authType, challengeParms);

String response = System.console().readLine("Enter response: ");
UserAuthenticateParameters authParms = new UserAuthenticateParameters()
    .setApplicationId(APPLICATION_ID)
    .setResponse(response);
authApi.userAuthenticateUsingPOST(authType, authParms, challengeResponse.getToken());

Full example snippet​

package com.entrust.idaas.userAuthenticate;

import com.entrustdatacard.intellitrust.auth.ApiClient;
import com.entrustdatacard.intellitrust.auth.api.AuthenticationApi;
import com.entrustdatacard.intellitrust.auth.model.*;

public class UserAuthenticate {
    private static final String APPLICATION_ID = "YOUR_APPLICATION_ID";
    private static final String HOST_NAME = "YOUR_HOST_NAME";

    public static void main(String args[]) throws Exception {
        ApiClient apiClient = new ApiClient();
        apiClient.setBasePath(HOST_NAME);
        AuthenticationApi authApi = new AuthenticationApi(apiClient);

        if (args.length != 2) {
            System.err.println("userAuthenticate <authType> <userId>");
            System.exit(-1);
        }
        String authType = args[0];
        String userId = args[1];

        UserChallengeParameters challengeParms = new UserChallengeParameters();
        challengeParms.setApplicationId(APPLICATION_ID);
        challengeParms.setUserId(userId);

        AuthenticatedResponse challengeResponse = authApi.userChallengeUsingPOST(authType, challengeParms);

        String response = System.console().readLine("Enter response: ");
        UserAuthenticateParameters authParms = new UserAuthenticateParameters()
            .setApplicationId(APPLICATION_ID)
            .setResponse(response);
        authApi.userAuthenticateUsingPOST(authType, authParms, challengeResponse.getToken());
    }
}
Sample code only

The sample code above is for demonstration purposes only. It is not intended to be used in production. Validate input parameters, handle exceptions, and use a secure method to set the application ID and host name.