Paterva itds OAuth Integration itds OAuth Integration Building and re-using OAuth providers within Maltego AM 2014/09/22
Contents Maltego OAuth Integration... 3 Introduction... 3 OAuth within the Maltego application... 3 Configuring the OAuth providers... 4 OAuth Settings... 4 Configuring the itds for a NEW OAuth provider (LinkedIn)... 5 Configuration of the provider application... 5 Configuring the OAuth settings on the itds... 7 Why do we use a public and private key?... 8 Configuring the itds settings... 9 Meta Information:... 9 Provider Information:... 9 Provider Information:... 9 Pairing OAuth settings with Transforms...10 Implementing the OAuth settings in code...12 Configuring the itds for a previous OAuth provider (LinkedIn)...14 Apendix A: PHP Code snipper for fetching profile data...15
Maltego OAuth Integration Introduction 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 do require OAuth tokens, you will also be prompted to login before the transform is run. Configuring the OAuth providers OAuth Settings 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 within) 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) In this section we will look at an example provider, in this case LinkedIn, but it should be relatively similar with all major providers. Configuration of the provider application 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: o Encrypt the token and token secret with the public encryption key (RSA/ECB/PKCS1Padding) o Base64 encode both of them o Concatenate these two base64, encrypted strings joined by a $ symbol o 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: o Separate the string on the $ symbol o Base64 decode each section o 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:
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 settings 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 Provider 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/9haaaagxrfwhrtb2z0d2fyzqbbzg9izsbjbwfnzvjlywr5ccll
PAAAAfxJREFUeNqUk89r1EAUx78zmWncH83abluoUAhFFNRa/Af8AxShXsSz4MGD4MGjnsSrXgQvni0UxPSw4KH+CQtSqpZ WNFDo4rqRbay7biaZODPb3WSlFfYdkvdm3uc7b15eyMzd1eVqtew5TtHFGBaGHT8IDlfY9FTRe3Djintu1hmHx86P0H2+Xvd YxSm4P7vA250D7LVCLDqWSfgaJliYOVl0/hTB9FTJZfaEha2ghyQFFsoUz26eNwn332yjeRidKBD8BphFwOI4QTdK+qsszaWkiE Ty32tolsUqKYr7iRu7B7i39sn461stVJ3CCMAowVylqE6mfQGhBeLYONooIXh564LxX9ffY//hVeNv7v/C5TOTaHcFHte+4HMgY FEKzdIkUXAikagqpJTHlqphbacLHE+un8X3dqfPKJZqkKepUpNIZdYDkhNYrTfwqLY7FBFHjGapVGUMApbDSpwN/afvfHgfWlk vvj5mnmt0gumbmgmubtbsvh+barjfml2opyi/qukoucymjziba5q3swy0s/xdvgs9pzbstihbpjsitz7f075mnetm77xkry 1dxHZHoq0+gp07eWC9KDbvwV5FwYtcorb5UV0hEv5es+FempsH5/bxI1fiI6EQPXxrNtT8CJ9Ubr9YVhPkqbLG+p2JlD5kuvJX gaeamvzqsyjfahkaaaaasuvork5cyii= 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, 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:
Implementing the 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: //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(); The full transform is listed in Apendix A. 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 3 rd 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 Apendix A at the end of this document. It is important to note that 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.
Apendix A: PHP Code snipper for fetching profile data <?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'}); } else { } $mt->returnoutput(); $mt->addexception("no input entity found"); $mt->throwexceptions();