Connecting To DirectID

Authentication

Due to the high level of security we maintain, we use the OAuth framework for authentication rather than rely on usernames and passwords.  If you want to learn more about OAuth please look at these resources

Who else uses a variant of OAuth?

  • Facebook
  • Twitter
  • Amazon
  • eBay

Generating an OAuth token

You need a valid access token in order to initialize the DirectID Widget and also while accessing the RESTful API. Fetching an access token is the first thing you will need to do if you want to setup the Widget or download any transactional data from Direct ID. All endpoints of the DirectID RESTful API require you to authenticate via OAuth and include your OAuth token in the Authorisation header of your API request. We recommend that you download one of our sample apps as these contain best practice methods for generating OAuth tokens with our authentication servers.

In order to generate an OAuth token, your web server must make a request to our authorisation server containing your Client ID and Secret Key provided to you by DirectID. The server will authenticate and respond with a JSON message containing an OAuth token for your server to access DirectID.

If you want to receive a client ID and secret key, send an email to support@directid.co

OAuth tokens generated for DirectID have a lifetime of 1 hour, after this period you will need to request a new token.

The client ID and secret key belong to our customers. It is important that you keep your secret key strictly confidential and do not expose it to your users by making OAuth requests from client side code.

/**
 * Our sample applications on GitHub contain Java, PHP and C# code that you can use to fetch OAuth tokens.
 * An example method named AcquireOAuthAccessToken(), which is taken from dotnet_sample_web_app, one of our sample .NET applications. 
 * This method uses two classes from Microsoft.IdentityModel.Clients.ActiveDirectory namespace to fetch an OAuth token from an Azure Active Directory service. 
 * A class named ClientCredential holds client ID and secret that we supplied to you.
 *  Another class AuthenticationContext retrieves authentication tokens from the actve directory service.
 */

/// <summary>
/// Obtains an OAuth access token which can then be used to make authorized calls
/// to the Direct ID API.
/// </summary>
/// <remarks>
/// <para>The returned value is expected to be included in the authentication header
/// of subsequent API requests.</para>
/// <para>As the returned value authenticates the application, API calls made using
/// this value should only be made using server-side code.</para>
/// </remarks>
private static string AcquireOAuthAccessToken(CredentialsModel credentials)
{
   var context = new Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext(
   credentials.Authority);
var accessToken = context.AcquireToken(
credentials.ResourceID,
new Microsoft.IdentityModel.Clients.ActiveDirectory.ClientCredential(
credentials.ClientID,
credentials.SecretKey));


if (accessToken == null)
{
throw new InvalidOperationException(
"Unable to acquire access token from resource: " + credentials.ResourceID +
".  Please check your settings from Direct ID.");
}


return accessToken.AccessToken;
}

 

/**
 * Following is another code segment taken from java_sample_web_app, one of our sample Java applications on GitHub. 
 * This code shows how acquireOAuthAccessToken() method uses Java client for Azure AD Authentication Library (ADAL) in order to fetch an OAuth token.
 */

/**
 * Obtains an OAuth access token which can then be used to make authorized calls
 *	to the Direct ID API.
 * @param clientId
 * @param clientSecret
 * @param resourceId
 * @param authority
 * @return The returned value is expected to be included in the authentication header of subsequent API requests
 * As the returned value authenticates the application, API calls made using
 * this value should only be made using server-side code
 * @throws MalformedURLException
 * @throws InterruptedException 
 */
public String acquireOAuthAccessToken(String clientId, String clientSecret, String resourceId, String authority) throws MalformedURLException, InterruptedException {
    DefaultAuthenticationCallbackHandler callback = new DefaultAuthenticationCallbackHandler();
    ExecutorService service = Executors.newFixedThreadPool(1);
    AuthenticationContext context = new AuthenticationContext(authority, true, service);
    context.acquireToken(resourceId, new ClientCredential(clientId, clientSecret), callback);
    waitForResultFor30Seconds(callback);
    return callback.getToken();
}

 

/**
 * This code segment is from our PHP sample web application that uses cURL to send a request for OAuth token. 
 * The PHP also    processes the JSON response from our authentication server and retrieves the required OAuth token.
 */

$oAuthCurlInstance = buildOAuthCurlRequest(); //The cURL request is constructed using the OAuth Details provided by Direct ID
$oAuthCurlResponse = curl_exec($oAuthCurlInstance);
curl_close($oAuthCurlInstance);      

//Handle cURL Response
if($oAuthCurlResponse != false){         
    
    $jsonResponse = json_decode($oAuthCurlResponse);  //Decode
    if(json_last_error() == JSON_ERROR_NONE) { //Validate       
        if (property_exists($jsonResponse, 'access_token')){                                     
            //Build and return OAuth token
            $token = new OAuthToken();                
            $token->token = $jsonResponse->{'access_token'};
            $token->expires = calcOAuthExpiryDate($jsonResponse->{'expires_in'});                
            return $token;                
            
        }
    }        
}