Using the Graph API to enroll hardware tokens is a newly introduced feature in Entra ID. Currently, you can use the Graph API to upload tokens into Entra ID, but there is no UI in the Entra Admin Portal for administrators or the help desk team to manage those tokens. Those tokens can only be self-enrolled by the users.

If you need a system that allows administrators or the help desk team to enroll and manage tokens, as well as allows your users to self-enroll their tokens, then check out the SafeID Token Service.

To enroll hardware tokens into Entra ID using the Graph API, follow the steps below.

Step 1: Get the JSON file of the hardware tokens

To get the JSON file of your hardware tokens, follow the steps below:

Download the Token Secret File in the "Entra MFA JSON" format

If you have purchased OTP hardware token devices from us, then you will first receive the physical hardware token devices delivered to you by FedEx or post. Once you have received the token devices, you will need to make a request to receive the token file, i.e. the seed/secret keys of the tokens.

To make the request, click the link below.

https://services.deepnetsecurity.com/csp/SeedFileRequests


Follow the steps below:

Step 1 - Find Your Order

You can find your order by one of the following 3 numbers

  • Your Purchase Order Number
  • Our Invoice Number
  • Our Shipment Number

You also need to enter your business email address.

If your email address does not match your account in our system, then you will not be able to proceed. If that is the case, then you will need to contact your account manager to have your account updated, or send an email to our delivery team at "delivery@deepnetsecurity.com" with the shipment number, invoice number or your PO number.

Step 2 - Verify Shipments

Once your order has been found, all of the shipments in the order will be listed for your selection.

If there is more than one shipment in the order, you have the option to receive the seed/secret keys of all shipments or some of the shipments.

Once you have specified the shipments, you will be asked to verify each shipment by providing the serial number of one of the tokens in the shipment.

Step 3 - Select Token File Encryption

For security, the token seed/secret file will be encrypted by a password and/or PGP key. 

First, you have to decide if you want to receive the seed/secret keys of all tokens in one file, or in separate files by shipments. 

Then, you have to decide how you want the token file to be encrypted. You have 3 options:

  • Password only
  • PGP only
  • Password and PGP

For simplicity, select the password option. For better security, select the PGP encryption option. If you have not used PGP, then please refer to the guide below

How to encrypt or decrypt files using PGP

For the best security, you can encrypt the token file by both password and PGP key.

If you select to use the password option, you must create a new password and save a copy of the password in a safe place, as you will need it to decrypt the seed/secret files when you have received them. 

If you select to use the PGP option, you must create a new PGP key and save a copy of the PGP private key in a safe place, as you will need it to decrypt the seed/secret files when you have received them. (If you are using the WinGPG software, then your PGP private key is automatically saved by the software itself).

Step 4 - Select Token File Format

Next, you need to specify the format of the seed/secret file that you wish to receive.

Select one of the following options:

  • Entra MFA CSV
  • Entra MFA JSON
  • DualShield
  • Duo CSV
  • OKTA CSV
  • PSKC - Passphrase-Based Key
  • PSKC - Plain text
  • PSKC - Pre-Shared Key
  • SafeID Token Service CSV
  • Sales Force CSV
  • Custom CSV

All options are self-explanatory except the "Custom CSV" option.

The "Custom CSV" option allows you to specify your own CSV data content.

A custom CSV file consists of a list of fields, and each field has a name and value. 

Click on "Add Field" button to add a new field. 

Enter the name of the filed, then specify the value of the field. You can either specify a fixed value or select one of the token's properties.

Also, you need to specify whether or not you want the list of field names to be included CSV file as the first row - the header row. 

Finally, you need to specify how the seed/secret key should be encoded. There are 3 options:

  • Hex
  • Base32
  • Base64



Finally, click on the "Submit" button to submit your request.

For extra security, your request will be reviewed by our delivery team to ensure that all details are correct.

Step 5 - Receive Token Download Email

If all of the details that you submitted are correct, then shortly you will receive an email from delivery@deepnetsecurity.com, like below:

  

If you have several shipments and decided to receive seed/secret files separately, then you will receive several emails.

Step 6 - Download Token File

To download the seed file., click the download link. 

You will be prompted to enter your password if you decided to secure the seed file by password at the request

image.png

Once the correct password is entered, then the file will be downloaded automatically

Step 7 - Decrypt Token File

The seed file is delivered as a zip file. You need to unzip it

If the seed is password encrypted then you will be asked to enter the password to unzip the file


If the seed file is PGP encrypted, then you will need to decypt it by using the WinGPG tool


You will be prompted to entre the passphrase of your PGP key

(Please note that this passphase is the password of your PGP key, not the password of the seed file)


The seed file is delivered as a zip file. You need to unzip it after PGP decryption

If the seed is password encrypted then you will be asked to enter the seed file password to unzip the file.


Step 8 - Confirm Download

Now that you have received your token seed/secret file, and you have sucessfuly decrypted it, we suggest that you should click the confirmation link in the email. By confirming it, the download link will be deleted immediately. This is an additional measurement for security.


If you have previously downloaded the token secret file in the "Entra MFA CSV format, then you can follow the steps below to convert CSV to JSON

Download CSV2JSON PowerShell Script

Download CSV2JSON PowerShell Script and save it in a local folder.

Convert the CSV file to JSON file

Run Windows PowerShell, execute the cmd below:

 .\CSV2JSON.ps1 -InputPath "{your token CSV file}" -OutputPath "{your token JSON file}"

See an example below:


Step 2: Upload hardware tokens using the Graph Explorer

Access the Graph Explorer: https://developer.microsoft.com/en-us/graph/graph-explorer

Sign in using your Entra account

Change the HTTP method from "GET" to "PATCH", and change the endpoint to "https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices"

Now, click the "Modify Permissions" to check if you have the "Policy.ReadWrite.AuthenticationMethod" permission

Click "Open the permissions panel" link

If you have not been granted the consent for the "Policy.ReadWrite.AuthenticationMethod" permission, then you need to admin the global administrator to grant the consent to use the Graph API.

Option 1 – Through Graph Explorer (Admin Account)

  1. Have a Global Administrator or Privileged Role Administrator sign in to Graph Explorer.

  2. In the Permissions tab, find Policy.ReadWrite.AuthenticationMethod.

  3. Instead of “Consent on behalf of yourself,” the admin will see an option to Consent on behalf of the entire organization.

  4. Click Consent → approve.

Option 2 – Through Azure Portal (Enterprise Applications)

  1. Go to Azure Portal → Azure Active Directory → Enterprise Applications.

  2. Find Graph Explorer (it’s registered as an Enterprise Application in your tenant).

  3. Under Permissions → Admin Consent, the admin can review pending permissions.

  4. Grant consent for Policy.ReadWrite.AuthenticationMethod on behalf of the organization.

If you have the the consent for the "Policy.ReadWrite.AuthenticationMethod" permission, then you can continue.

Click the "Request body" tab

Open the JSON file in a text editor, copy all the contents, and paste the data into the Request body 

Click the Run query button.

If you see "OK - 200 - ...", then the tokens have been successfully uploaded into the Token Repository in your Entra ID tenant.


Step 3: Check the token repository using Graph API

Optionally, you might want to check the token repository to make sure that the tokens have been successfully uploaded into Entra ID

To check your Token Repository in Entra ID, you must also use the Graph API.

In the Graph Explorer, set the HTTP method to "GET", and set the endpoint URL to: https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices

Click "Run Query"

You can scroll down to find the tokens that you have just uploaded, e.g. "serialNumber": "70029370",



Step 4: Self-Enroll hardware tokens into Entra ID

You can now give the tokens to your users and ask them to self-enroll their tokens in Entra ID

For users to self-enroll their tokens, sign in: https://mysignins.microsoft.com

Navigate to: Security Info

Click "Add sign-in method"

Select the "Hardware token" method from the available options.

The user will be prompted to enter the serial number of the hardware token.

Enter the token's serial number, e.g. 70029370

Click "Next"

The user is now prompted to enter the name of the hardware token.

Enter the token's name, e.g. SafeID/Enterprise

Click "Next"

The user is now prompted to enter a verification code generated from the hardware token.

Enter the code generated from the hardware token, e.g. 077400

Click "Next"

If the code entered is correct, the hardware token has been successfully added to the user's account.

Click "Done"

The hardware token is now ready to be used for verifying the user at the next login.





  • No labels