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 Risk Conditions.
  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.

Available authenticators​

The Authentication API supports these authenticator values:

  1. MACHINE
  2. PASSWORD
  3. EXTERNAL
  4. KBA
  5. TEMP_ACCESS_CODE
  6. OTP
  7. GRID
  8. TOKEN
  9. TOKENPUSH
  10. FIDO
  11. SMARTCREDENTIALPUSH
  12. PASSWORD_AND_SECONDFACTOR
  13. PASSTHROUGH

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.