API SECURITY

API Security Home Quick Start T-Mobile API Overview Token Overview Step 1:
Generate PoP Token - OAuth 2.0 Step 2:
Generate OAuth 2.0 Access and ID Tokens Step 3:
Generate PoP Token - API Resource Step 4:
Functional Call to API Resource Server Formats Status Code Definitions

Step 1: Generate a PoP Token - OAuth 2.0

Home / Portfolio / Content / Technical Writing / API Security / Step 1

Introduction

This document guides the reader on how to create a T-Mobile proprietary OAuth 2.0 Proof of Possession (PoP) Token.

This is step 1 of 4 in the T-Mobile API Access Protocol (TAAP) process. To learn more about the TAAP process, please read the documents T-Mobile API Overview and Token Overview.

Prerequisites

  1. A DevEdge Account. If you do not have a DevEdge account please create one now.
  2. Be subscribed to a T-Mobile API. If you are not subscribed to a T-Mobile API you will not receive the client_id and client_secret.
  3. Your OAuth 2.0 client_id and client_secret found in your DevEdge account here.
  4. An understanding of OpenSSL.
  5. A computer with Git installed on it.
  6. A computer with node.js installed on it.

Some Important Things to Note

  1. Again, this is step 1 of 4 in the T-Mobile API Access Protocol (TAAP) process.
  2. This walkthrough teaches you:
    1. How to install the Proof of Possession (PoP) token library locally on your computer.
    2. How to use the PoP Token Library to generate an OAuth 2.0 PoP Token.
  3. Note that there are two different types of Proof of Possession (PoP) tokens.
    1. An OAuth 2.0 PoP Token
    2. An API Resource PoP Token

  4. When developing a Java, JavaScript, or .NET client, we recommend using a TAAP PoP Token Creation Library developed by T-Mobile. In the case of other languages (e.g. Python, PHP, etc.) the library should create a JWT object in the format mentioned in TAAP documentation. Please see the PoP Token JWT Format below.

    Header: {alg, type}
Body {
  iat: 
  exp: 
  ehts:  => All request headers, URI, HTTP method and body fields used to create hash
  edts: 
  jti: 
  v: "1"
}
Signature:
  5. A new Proof of Possession (PoP) token needs to be created for each request, including the JWT and initial OAuth 2.0 access token request.

Generating the PoP Token

For demonstration purposes, we will use the JavaScript PoP Token library to generate the PoP Token.

Step A

Create OpenSSL Public and Private Keys

  1. Install node.js.

  2. Download the following JavaScript file onto your Desktop: index_create_key_pair.js

    The code for this JavaScript file can also be found below:

    /*
* Copyright 2019 T-Mobile US, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*     http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

const { generateKeyPair } = require('crypto');
var fs = require("fs");

generateKeyPair('rsa', {
  modulusLength: 2048,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem'
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem'
  }
}, (err, publicKey, privateKey) => {
  fs.writeFile('public-key.txt', publicKey, (err) => {
   if (err) {
      throw err;
   } else {
    console.log('The public-key.txt file has been saved.');
    }
});

fs.writeFile('private-key.txt', privateKey, (err) => {
   if (err) {
       throw err;
    } else {
    console.log('The private-key.txt file has been saved.');
    }
  });
});
  3. Open your command line app. For demonstration purposes we will be using Terminal on a Mac.

  4. Change directories to your Desktop.

  5. Type node index_create_key_pair.js then press Return on your keyboard.

  6. On your Desktop both a public and private key is generated.

  7. Login to DevEdge.
  8. Navigate to the Dashboard.
  9. Click Activate kit.

  10. Save your IMEI and ICCID in a safe place then click Activate.

  11. Click Done.

  12. Go to the Subscription page.

  13. Click the ellipsis next to a subscribed API then click View API keys.

  14. Click Add key.

  15. Open the public-key.txt file that you created in step 5. Select all the text in the file.

  16. Paste the public key into the text area then click Add key.

    Paste the entire contents of the public-key.txt into the text area, including the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----, or the PoP Token will not work. Also remember to avoid adding any spaces.

  17. You should receive a message that your public key was updated successfully.

Step B

Encode your Client ID and Client Secret

  1. Obtain your Client ID and Client Secret from the DevEdge Subscription > ellipsis > View API keys area.

  2. Paste them into a text editor as follows:

    client_id:client_secret

    Do not forget the colon in between. This is required. Also remember to remove any spaces.

  3. Go to https://www.base64encode.org/ and paste in your client_id:client_secret then click Encode.

  4. Save the encoded client_id:client_secret somewhere safe. You will need it to generate the PoP Token.

Step C

Download the JavaScript PoP Token Library.

  1. Install Git.
  2. Open your command line prompt app.

  3. Clone the Proof of Possession (PoP) Token libraries from our GitHub repository using the Git command below.

    git clone https://github.com/tmobile/tmobile-api-security-lib.git

    As of this writing, we have .NET, Java, JavaScript, and C# PoP Token libraries to choose from. The above clone will download all of these libraries. Again, we are only concerned with JavaScript PoP Token library.

  4. In the Finder app navigate to the folder on your computer where the JavaScript PoP Token Library was downloaded.

  5. Remember this location.

Step D

Install a node.js framework for the Proof of Possession (PoP) Token library.

  1. Install node.js.
  2. Open your command line app.

  3. In your command line app, navigate to where you downloaded the JavaScript PoP Token Library on your computer.

    1. cd tmobile-api-security-lib then
    2. cd poptoken-lib then
    3. cd poptoken-builder then

    4. cd js-lib-tmobile-oss-poptoken-builder

  4. Enter npm install then press Return on your keyboard.

  5. A new node_modules folder appears in your js-lib-tmobile-oss-poptoken-builder when you finish running npm install.

  6. Close your command line app.

Step E

Generate the OAuth 2.0 PoP Token.

  1. In a Finder app, navigate to the html_example folder in the JavaScript PoP Token library (js-lib-tmobile-oss-poptoken-builder) folder.

  2. Open the poptoken-builder-text.html in a web browser.

  3. Update the poptoken-builder-text.htm file thusly.

    1. Content-Type should be application/json.
    2. Authorization should be a "Basic" token and the Base64 encoded result of your client_id:client_secret that you created in Step B.
    3. URI should be set to /oauth2/v2/tokens or the endpoint of the API URL.
    4. HTTP-Method should be set to POST.
    5. Body should be left blank.
    6. Replace the Private Key text field with your private-key.txt key. Ensure to copy and paste the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- text or the PoP Token will break.

    7. Note that these fields need to match the API call EXACTLY or the PoP Token will break. No extra spaces, carriage returns, or characters are allowed. And text case does matter. If the method is POST, all upper case, then ensure that the HTTP-Method is spelled all upper-case, POST.

      Before

      After

  4. Click Generate PoP Token.

  5. The PoP Token will only be viable for 60 seconds. Also note that the Proof of Possession (PoP) Token is only good for one hop. You cannot use the PoP token on any other call.

Troubleshooting

  • Issue 1 - What If I have not subscribed to an API? Will I be able to obtain my client_ID and client_secret?
  • Solution 1 - Unfortunately, no. You must be subscribed to the API in order to obtain your client_ID and client_secret on the subscription page. Please activate your IoT Developer Kit or contact us if your are not subscribed to an API.

 

  • Issue 2 - How do I know what my OAuth 2.0 endpoint is for my subscribed API?

  • Solution 2 - Please follow the below:

    • The endpoint /oauth2/v2/tokens is for the following APIs:

      • Connectivity API
      • Location API
      • SMS Notification API

    • The endpoint /oauth2/v6/tokens is for the following APIs

      • Call Verification
      • Fraud Prevention

FAQ

  • Question 1 - Does the endpoint /oauth2/v6/tokens have a request body?
  • Answer 1 - Yes it does. The endpoint for /oauth2/v6/tokens should be { "client_id": "xxxxx", "client_secret" : "yyyyy", "scope" : "response_mode", "grant-type": "client_credentials" }. Replace the client_id and client_secret values with your arguments.

 

  • Question 2 - Is there another way to generate a public and private key?
  • Answer 2 - Yes there is. You can use the Shining Light Production installation files. Note that this method will only work on a Windows OS.

    1. Download the Shining Light Production installation files then install them on your Windows based computer.

    2. Search for the OpenSSL command line app then open it.

    3. Enter the following at OpenSSL command line to generate your RSA public and private keys using the following commands.

      # Creates private key in PKCS1 format
openssl genrsa -out private-key-pkcs1.pem 2048

# Converts private key to PKCS8 format
openssl pkcs8 -topk8 -inform PEM -in private-key-pkcs1.pem -outform PEM -nocrypt -out private-key-pkcs8.pem

# Creates public key in PKCS8 format
openssl rsa -in private-key-pkcs8.pem -outform PEM -pubout -out public-key.pem

    4. The following files are created after running the above OpenSSL commands.

    5. Save the private-key-pkcs8.pem. You will need it to generate the PoP Token.

    6. Open the public-key.pem with a text app, select all the text, then copy the public key text.

      Copy the entire contents of the public key, including the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----, or the PoP Token will not work.

    7. Login to DevEdge.
    8. Navigate to the subscription page

    9. Click the ellipsis next to a subscribed API, click View API keys, click Add key, paste your public key into the text area, then click Add key again.

      Paste the entire contents of the public key into the text area, including the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----, or the PoP Token will not work.

 

  • Question 3 - I do not know where to find my private-key-pkcs8.pem and public-key.pem on my computer. Where could they be?

  • Answer 3 - In your OpenSSL command line app, look at the path.

    In a File Explorer window, navigate to this path. This is where you will find your private-key-pkcs8.pem and public-key.pem files.