OAuth Example Three – LinkedIn Integration

Overview

This use case describes how user authorization can be achieved in Maltego through OAuth 2.0.

We create a LinkedIn developer application that redirects a Maltego user to LinkedIn to authorize access to their information on LinkedIn.

This tutorial is broken into the following parts: 

1. Create a LinkedIn Developer App Registration
2. Construct the Authorization Code Request URL
3. Construct Token Access URL
4. Configure OAuth Settings in the Transform Distribution Server
5. Develop and Deploy the Transform Code
6. Configure Seed and Pair with Transform
7. Run and Test Transform

Tutorial

1. Login and create an application https://www.linkedin.com/developers/apps 

In the Auth Settings section, input the Auth settings we will be using the following callback URLs:

• https://127.0.0.1:63141/callback    
• http://127.0.0.1:63141/callback

By default, LinkedIn apps will only have the following OAuth 2.0 Scopes, to access more you need to get verified by LinkedIn.

Note down the Client ID and Client Secret

2. Construct the Authorization Code Request URL

We are using the Authorization code flow, where we will redirect a user to LinkedIn’s Oauth2.0 authorization page, where the member will authorize access to their details. More details are outlined here.

GET https://www.linkedin.com/oauth/v2/authorization 

Example Request URL 

3. Construct the Token Request URL

The URL in step 2 will return an authorization code and we need to Exchange Authorization Code for an Access Token.

POST https://www.linkedin.com/oauth/v2/accessToken

Please verify the URLs in POSTMAN or your favorite API test tool. After you are certain the URLs are functioning proceed to the next step.

4. Configure OAuth Settings in the Transform Distribution Server

The Transform Distribution Server will take the OAuth 2.0 configuration values, pass them on to the Maltego Client which  will redirect to the authorization screen when a Transform is run.

4.1 Open your iTDS server or the public TDS and create an account. Open OAuth Settings

4.1.1 Public TDS OAuth Settings Image

4.1.2 Internal TDS OAuth Settings Image

4.1.3 Settings Configuration

Input the following OAuth settings as given below, replace with your values and save. 

5. Develop and Deploy the Transform code

We will be using the Maltego open source maltego-trx library to develop the demo Transform. Upon completion the Transform will need to be deployed to a publicly accessible server such as a VPS or VM with Python3 and pip installed.

5.1 Install the Prerequisite Software

python3 -m pip install --user virtualenv
python3 -m venv oauth-venv 
(oauth-venv) pip install maltego-trx
// install version 1.3.7+ only

5.2 Create a maltego-trx project

(oauth-venv) maltego-trx start linkedin_project 

This will create a folder linkedin_project with the example project

5.3 Adding a Transform

Add a new Transform by creating a new Python file titled LinkedIn.py in the "transforms" folder. 

Any Python file in the Transform folder whose class name matches the filename, and the class inherits from Transform, will automatically be discovered, and added to your Transform server. 

Add the following files and the corresponding code.

5.4 Create File:  linkedin_project /transforms/ LinkedIn.py

from pathlib import Path
 
import requests
from maltego_trx.entities import Phrase, Email
from maltego_trx.maltego import UIM_TYPES
from maltego_trx.transform import DiscoverableTransform
from maltego_trx.oauth import MaltegoOauth
 
 
class LinkedIn(DiscoverableTransform):
    """
    Uses Oauth token from the LinkedIn and see the logged in persons Details
    """
 
    @classmethod
    def create_entities(cls, request, response):
        try:
            encrypted_secrets = request.getTransformSetting('maltego.web.api.key.linkedIn')
            private_key_path = Path("private_key.pem").resolve()
            token_fields = MaltegoOauth.decrypt_secrets(private_key_path, encrypted_secrets)
            api_url = "https://api.linkedin.com/v2/emailAddress?q=members&projection=(elements*(handle~))"
            headers = {'Authorization': 'Bearer {}'.format(token_fields['token'])}
            result = requests.get(api_url, headers=headers)
            email = result.json()['elements'][0]['handle~']['emailAddress']
            emailEntity = response.addEntity(Email, email)
            emailEntity.setNote("Email For LoggedIn User")
            ciphertext = response.addEntity(Phrase, encrypted_secrets)
            ciphertext.setNote("ciphertext")
            token = response.addEntity(Phrase, token_fields['token'])
            token.setNote("token")
        except Exception as e:
            response.addUIMessage("Error: " + str(e), UIM_TYPES["partial"])

5.5 Add the private key for decryption

5.5.1 Create file : linkedin_project /private_key.pem

Add the contents of the private key to this PEM file. It is possible to just upload/save the actual PEM file to this location if you have it as a PEM file.

5.6 Navigate to linkedin_project /

5.7 Run the trx project with

(oauth-venv)python project.py runserver

If all went well, you should see a result similar to the one in the image below:

5.8 Deploy the entire project folder /linkedin_project to a remote VPS/VM/Dockerized environment. More details on how to deploy for production can be found here for standard web deployment and here for Docker containerized deployment. The simplest method for this tutorial is to upload the folder to a remote server through git or ftp.

5.9 Navigating to your VPS IP http://<ip-address>/run/linkedin in a browser you should the following output. If this doesn’t work, please check that you have opened the port on the firewall.

6. Configure Seed and Pair with Transform

Now that we have our Transform up and running, we need to create a Seed to distribute the Transform. The TDS will generate a random alphanumeric seed name for you, but you can also use one of your choosing.

6.1 Add Transform and OAuth Settings to Seed

Next, we need to add the Transform, in there we also add the OAuth Setting,the Input Entity, and Seed URL.

6.2 Install Seed in the Maltego Client

After we are done adding the Transform, we can now install our Seed in Maltego

6.3 Verify the OAuth Settings in the Service Manager

We can view the OAuth Authenticator settings in the Service Manager by selecting the Manage Service options under the Transforms menu. Cross check that the protocol set in step 2.3 are the same as here. The settings the Service Manager correspond should correspond to the callback URL set in the provider Application.

6.4 Run the Transform

Drag a Person Entity on an empty graph and then right click and run the Transform

Upon running the Transform, a prompt will appear asking to Sign in to use the Transform. Click Sign In. A browser page will be opened with the URL http://127.0.0.1:63141/signin and we are redirected to the Okta login page, please note you might observe an SSL certificate warning sign in the browser, ignore it and proceed.

.

After successful login a user can now make a query and the Transform will check if they can run the Transform. Our demonstrative Transform looks up the logged-on user‘s email and also returns the decrypted access token.

Note: To shorten authorization urls and to reference the returned token, Maltego uses configuration placeholders as follows:

For OAuth 2, "apiKey" and "callback" can be used as replacement variables in the authorization URL, e.g. http://example.com/oauth2/authorize?client_id={apiKey}&redirect_uri={callback}.

For OAuth 1.0a, only "token" can be used as a replacement variable, e.g. http://example.com/oauth1/authorize?oauth_token={token}.

For further explanation regarding OAuth endpoint configuration, please read more here.