Oauth Integration / Configuration

 

Introduction   [Back to Top]

OAuth is an open standard for authorization. It provides a means of allowing Maltego users/analysts to log into third party providers with their credentials and have an access token returned to the tool. This access token can then be sent to the transform which in turn can request information from the provider on behalf of the end user.

Within the iTDS there are two types of providers that can be added:
  1. A new provider – one that has not been seen before on this server (and likely within your client).
  2. A previously used provider – one that has been used previously in the tool so that you can re-use the access token.

OAuth within the Maltego application

Within the Maltego client, the OAuth providers can be found under the Manage tab by clicking on the "Manage Services" button:



After clicking on that button you will be presented with the Service Manager panel that describe the available OAuth providers configured as well as the ability to login and logout of the various providers:



Within the application, if any transforms require OAuth tokens, you will also be prompted to login before the transform is run.
 

Configuring the OAuth providers  [Back to Top]

The OAuth settings required for a provider are as follows:

  • Authenticator name - This is the overall OAuth provider name.
  • Description - A description of the OAuth provider, something like "LinkedIn Provider".
  • Version - Which version of OAuth being used, the currently supported versions are OAuth 2.0 and OAuth 1.0a.
  • Access token endpoint - The endpoint that the Maltego client will request for the access token.
  • Request token endpoint - The endpoint that the Maltego client will send the user to for application approval.
  • Authorization URL - URL used to by the client to approve/grant access tokens.
  • Application/API key - API or Application key that the developer is issued from the provider.
  • Application/API secret - API or Application secret/private key that the developer is issued from the provider.
  • Icon - Base64 of the 64x64 pixel Icon to be used within the Maltego client application.
  • Access token variable name - The variable name used within the transforms (this is what the transform will receive).
  • Variable description - Simply describes the variable used.
  • Public Key - The public key used to encrypt the access token when it is sent to the transform code itself.
 

Configuring the iTDS for a NEW OAuth provider (LinkedIn)  [Back to Top]

In this section we will look at an example provider, in this case LinkedIn, but it should be relatively similar with all major providers.

The first step is to configure the application on the provider network, usually in the developer section and would be something like the following:



The next step is configuring where the OAuth provider (In this example LinkedIn) will redirect the browser to after the end user has accepted the application:



After adding the application with the provider and configuring it as above you will then receive your API and secret keys for your specific calls as follows:



Configuring the OAuth settings on the iTDS

Now we have created our application with the provider we can configure the iTDS to use these settings within Maltego. Naturally if you are running your own internal OAuth application this information might already be provided for you. To get to the OAuth settings configuration install your client side certificate within the browser (this is covered in another document) and browse to the iTDS interface. From the main page select "OAuth Settings" and then select "Add OAuth Setting" at the bottom of the list.



Initially you are given the option to either re-use previous OAuth configurations or create a new one. In this case we want to create a new OAuth configuration and can select the “New OAuth configuration” checkbox. From there we will be asked to provide the details for this configuration (as described previously in this document).

The most important fields to remember are the Authenticator name, Access Token Variable Name and Public key (and private key as described in the following section) as these are the fields you will need to provide if you wish for other developers to use the same OAuth tokens within their transforms.

Why do we use a public and private key?

Because tokens that are used within the OAuth communications are 50% of the authorization process (the other being the application keys), these tokens cannot be transmitted in the clear. As such this process is done with a public and private key in the following manner:
  • Maltego client knows about the public encryption key and this is sent during the discovery process.
  • Maltego client will retain the OAuth tokens after the analyst has logged into the provider.
  • When running the transform Maltego will send the tokens as follows:
    • Encrypt the token and token secret with the public encryption key (RSA/ECB/PKCS1Padding).
    • Base64 encode both of them.
    • Concatenate these two base64, encrypted strings joined by a ‘$’ symbol.
    • The final string would be B64(Crypt(Token))$B64(Crypt(TokenSecret)).
  • The transform will know what the private key (either one generated when creating the OAuth configuration or one you already had) and be able to decode the token in the following way:
    • Separate the string on the $ symbol.
    • Base64 decode each section.
    • Decrypt the token and token secret with the private key.
  • Transform can then use the token and token secret to execute the API call against the provider to get the data

Public and private keys can be generated on the iTDS by clicking on the ‘Generate an RSA key pair’ link on the Add OAuth settings page:



Note You will note that the private key is NOT saved anywhere, it will be up to the developers to securely store this private key privately..
 

Configuring the iTDS for a previous OAuth provider (LinkedIn)  [Back to Top]

For this example we will be configuring the OAuth settings as per our current provider (LinkedIn) with the following:

Meta Information

This is the meta information used to describe the OAuth setting.

Name: paterva.oauth.linkedin
Description: LinkedIn OAuth example
Version: OAuth 1.0a

Provider Information

This information is provided from the OAuth provider (LinkedIn)

Access token endpoint: https://api.linkedin.com/uas/oauth/accessToken
Request token endpoint: https://api.linkedin.com/uas/oauth/requestToken
Authorization URL: https://api.linkedin.com/uas/oauth/authenticate?oauth_token={token}
Application Key: 77t9jux0135g3v
Application Secret: E5kLMplGRdwpsqLo

Other Information

This information is used within the application (Icon), the iTDS (Public Key) or in the transform code (Access token variable name). The icon field is a Base64 encoded 64x64 pixel icon to be used within the tool.

Icon: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAfxJREFUeNqUk89r1EAUx78zmWncH83abluoUAhFFNRa/Af8AxShXsSz4MGD4MGjnsSrXgQvni0UxPSw4KH+CQtSqpZWNFDo4rqRbay7biaZODPb3WSlFfYdkvdm3uc7b15eyMzd1eVqtew5TtHFGBaGHT8IDlfY9FTRe3Djintu1hmHx86P0H2+XvdYxSm4P7vA250D7LVCLDqWSfgaJliYOVl0/hTB9FTJZfaEha2ghyQFFsoUz26eNwn332yjeRidKBD8BphFwOI4QTdK+qsszaWkiETy32tolsUqKYr7iRu7B7i39sn461stVJ3CCMAowVylqE6mfQGhBeLYONooIXh564LxX9ffY//hVeNv7v/C5TOTaHcFHte+4HMgYFEKzdIkUXAikagqpJTHlqphbacLHE+un8X3dqfPKJZqkKepUpNIZdYDkhNYrTfwqLY7FBFHjGapVGUMApbDSpwN/afvfHgfWlkvVJ5mNMt0GUMBmgmUbTbSvH+baRjFMl2OpYI/QuKoucYmJzIBa5Q3sWY0S/XDVgs9pZbSTIHbPJsItZ7f075mNEtm77xKry1dxHZHoq0+gp07eWC9KDbvwV5FwYtcorb5UV0hEv5es+FempsH5/bxI1fiI6EQPXxrNtT8CJ9Ubr9YVhPkqbLG+p2JlD5kuvJXgAEAMvzqSyjfahkAAAAASUVORK5CYII=
Access Token Variable Name: maltego.web.api.key.linkedin
Variable Description: OAuth token variable
Public Key
-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDcAKHjZy3cUS7SLXGUiH0mPeD6
KvVZHhaaggRJz5ZiN+hHUDZFciOAiTa4FmjMwDR/2wYoPjXdVj8Tt9WRump+SWaL
PNEDQd5LQtw+r4kYiKnPzXGKUmLQgkfcitJRlOJ05+xjktMlEDKud1CEutI+/VC4
+0DAGwY9/oAnRj/aAQIDAQAB
-----END PUBLIC KEY-----

Once this has been completed you can click on ‘Add OAuth Setting’ at the bottom of the page to add this OAuth setting.

Pairing OAuth settings with Transforms

Due to OAuth settings being specific per transform – one could have multiple transforms each using their own provider or none. OAuth settings are paired with transforms rather than with a specific seed. Within the iTDS interface for adding transforms you will now see a new section that will allow you to pick the OAuth settings required for this transform:



This document will not get into the details of adding a transform (you can follow the steps in the TDS transform guide), merely how to use the new OAuth functionality within the tool and transform. Once you have added your transform and included it in your seed you can proceed to discover the seed within Maltego:



This is a brief snippet of PHP code using the LinkedIn OAuth library to show it being used within the transform:

Implementing OAuth settings in code

This is a brief snippet of PHP code using the LinkedIn OAuth library as a reference of it being used within the transform:

<?php
//LinkedIn OAuth Library
	include_once("oauth/linkedinoauth.php");
	// Encrypted OAuth key
	$key = $maltegoInput->transformFields["maltego.web.api.key.linkedin"]; 
	//Our Private Key *DO NOT SHARE THIS*
	$real_private_key = '-----BEGIN PRIVATE KEY-----
MIICdQIBADANBgkqhkiG9w0BAQEFAASCAl8wggJbAgEAAoGBANwAoeNnLdxRLtIt
cZSIfSY94Poq9VkeFpqCBEnPlmI36EdQNkVyI4CJNrgWaMzANH/bBig+Nd1WPxO3
1ZG6an5JZos80QNB3ktC3D6viRiIqc/NcYpSYtCCR9yK0lGU4nTn7GOS0yUQMq53
UIS60j79ULj7QMAbBj3+gCdGP9oBAgMBAAECgYAvE9OQnduqcZTbVO4hIrPlIwip
f9fQoiekGH5ibRF5Iw2JdRin86y1LKeQ7PqwFdEmKvA+XFGac4I77fK9pG51AftQ
wgHriyHlpocXXESakLiWuI/6kPjooyBYsPTgjJcsFW/XnHUUTCwEZXfOIusG1Alz
KnXPINmKIJeGIIjRoQJBAPoDysJLcdHRcyeYS3rJReDFgqSHQ66gR4gX7moxK2DK
Kr2Tp51c4TuacN0RWIf2+6g5VOhK5jabMhTNlzQi2usCQQDhROkgE7SKPLq+4m/b
4y9KhIMsAXA+DkxMiIED56gl7z3QdpROBRLiwR7DD1pxMT736m0z8lE6RlZaHVaI
IQvDAkAW4a325ky+dTrizs9pp24byjfQswiAvO6PCBGr6mAb9aS/wPnALzX17IaT
1PiTSQlzNfwNXn1/VejZeo9yGBaNAkBvsAfZlIuFoliAfaoyHjB7RLn4Xno0+kfQ
BjnZIskWjchbC/+5swBLFq7WzUztJBpxNnSQNcsaFneH1FXrxl6bAkBvolQxT61l
I29vP3dS1zSgqvRbos9jl63o6Igl6ombyVb6Nqp+LSEuabFKYMWGwLJs0I7NrhbJ
b8yegsQP+/8Z
-----END PRIVATE KEY-----';
	
	//Lets seperate the two encrypted sections
	$parts = explode("$",$key);
	//B64 decode each section
	$token = base64_decode($parts[0]);
	$secret = base64_decode($parts[1]);

	//Decrypt each segment with our private key
	openssl_private_decrypt($token, $decrypted_token, $real_private_key,OPENSSL_PKCS1_PADDING);
	openssl_private_decrypt($secret, $decrypted_secret, $real_private_key,OPENSSL_PKCS1_PADDING);

	$consumer_key = "77t9jux0135g3v"; // API key
	$consumer_secret = "E5kLMplGRdwpsqLo"; // API Secret
	
	//Lets create a new LinkedIn Object and fetch the current user details
	$linkedInObj = new LinkedInOAuth($consumer_key,$consumer_secret,$decrypted_token,$decrypted_secret);
	//Fetch current user data
	$profile_result = $linkedInObj->oAuthRequest('http://api.linkedin.com/v1/people/~');
	$profile_data = simplexml_load_string($profile_result);
	//Create 
	$ent = $mt->addEntity("maltego.Person",$profile_data[0]->{'first-name'} . " " . $profile_data[0]->{'last-name'});
	$mt->returnOutput();



Configuring the iTDS for a previous OAuth provider (LinkedIn)

You may wish to reuse an OAuth provider already configured within Maltego due to using transforms on additional iTDS servers or re-using tokens that a 3rd party has installed.
If you wish to reuse an OAuth provider within Maltego you will need the following details:
  • Authenticator Name
  • Access Token Variable
  • Private Key


To create this token it’s almost the same process as above however you will only need the Authenticator Name and Access Token Variable to be the same as the previous OAuth provider. For these details you will need to contact the administrator of the TDS where the original transforms were configured. As per our previous example (using LinkedIn) we can use something like the following:



From here the transform adding and configuration within the tool are identical - in fact you can even use the code provided in next section at the end of this document.

Please Note while you do NOT need to provide the public key, the previously used public key will be used to encrypt the tokens, and you will need to use the corresponding private key to decrypt these tokens.
 

PHP Code snipper for fetching profile data  [Back to Top]

<?php
include_once("Maltego.php");
//set return content-type to be XML
header ("content-type: text/xml");
$maltegoInput = new MaltegoTransformInput();
$mt = new MaltegoTransformResponse();

if ($maltegoInput->getEntity())
{
	//LinkedIn OAuth Library
	include_once("oauth/linkedinoauth.php");
	// Encrypted OAuth key
	$key = $maltegoInput->transformFields["maltego.web.api.key.linkedin"]; 
	//Our Private Key *DO NOT SHARE THIS*
	$real_private_key = '-----BEGIN PRIVATE KEY-----
MIICdQIBADANBgkqhkiG9w0BAQEFAASCAl8wggJbAgEAAoGBANwAoeNnLdxRLtIt
cZSIfSY94Poq9VkeFpqCBEnPlmI36EdQNkVyI4CJNrgWaMzANH/bBig+Nd1WPxO3
1ZG6an5JZos80QNB3ktC3D6viRiIqc/NcYpSYtCCR9yK0lGU4nTn7GOS0yUQMq53
UIS60j79ULj7QMAbBj3+gCdGP9oBAgMBAAECgYAvE9OQnduqcZTbVO4hIrPlIwip
f9fQoiekGH5ibRF5Iw2JdRin86y1LKeQ7PqwFdEmKvA+XFGac4I77fK9pG51AftQ
wgHriyHlpocXXESakLiWuI/6kPjooyBYsPTgjJcsFW/XnHUUTCwEZXfOIusG1Alz
KnXPINmKIJeGIIjRoQJBAPoDysJLcdHRcyeYS3rJReDFgqSHQ66gR4gX7moxK2DK
Kr2Tp51c4TuacN0RWIf2+6g5VOhK5jabMhTNlzQi2usCQQDhROkgE7SKPLq+4m/b
4y9KhIMsAXA+DkxMiIED56gl7z3QdpROBRLiwR7DD1pxMT736m0z8lE6RlZaHVaI
IQvDAkAW4a325ky+dTrizs9pp24byjfQswiAvO6PCBGr6mAb9aS/wPnALzX17IaT
1PiTSQlzNfwNXn1/VejZeo9yGBaNAkBvsAfZlIuFoliAfaoyHjB7RLn4Xno0+kfQ
BjnZIskWjchbC/+5swBLFq7WzUztJBpxNnSQNcsaFneH1FXrxl6bAkBvolQxT61l
I29vP3dS1zSgqvRbos9jl63o6Igl6ombyVb6Nqp+LSEuabFKYMWGwLJs0I7NrhbJ
b8yegsQP+/8Z
-----END PRIVATE KEY-----';
	//Lets seperate the two encrypted sections
	$parts = explode("$",$key);
	//B64 decode each section
	$token = base64_decode($parts[0]);
	$secret = base64_decode($parts[1]);
	//Decrypt each segment with our private key
	openssl_private_decrypt($token, $decrypted_token, $real_private_key,OPENSSL_PKCS1_PADDING);
	openssl_private_decrypt($secret, $decrypted_secret, $real_private_key,OPENSSL_PKCS1_PADDING);
	$consumer_key = "77t9jux0135g3v"; // API key
	$consumer_secret = "E5kLMplGRdwpsqLo"; // API Secret
	
	//Lets create a new LinkedIn Object and fetch the current user details
	$linkedInObj = new LinkedInOAuth($consumer_key,$consumer_secret,$decrypted_token,$decrypted_secret);
	//Fetch current user data
	$profile_result = $linkedInObj->oAuthRequest('http://api.linkedin.com/v1/people/~');
	$profile_data = simplexml_load_string($profile_result);
	//Create 
	$ent = $mt->addEntity("maltego.Person",$profile_data[0]->{'first-name'} . " " . $profile_data[0]->{'last-name'});
	$mt->returnOutput();
}
else
{
	$mt->addException("No input entity found");
	$mt->throwExceptions();
}