How to Use Directory Network Manager

Navigate to...

How to Use Directory Network Manager

Overview

Alias Directory offers the capability to connect to remote directories via a component called Directory Network Manager. Directory Network Manager has the capability to query available remote directories with an Alias and retrieve the associated payment details, if available.

Infographic demonstrating third party directories being connected by the component called Directory Network Manager.

Directory Network Manager Marketing Video

High-level Steps

The steps apply for both sandbox and production environments.

Client
Fill out onboarding form

Client
Code to API specifications

Client and Visa
Exchange OAuth credentials

Client and VIsa
Exchange IP Addresses for whitelisting

Client and Visa
Exchange MLE keys

Client
Provide SSL certificate chain

Client
Complete test cases

Additional Details

Step	Description	Details
1	Remote Directory Onboarding Form	Implementation manager to provide Directory Network Manager onboarding form. The form contains the Remote Directory Profile and OAuth 2.0 Setup Details. Remote Directory to fill out and send back to implementation manager.
2	API Specifications	Remote Directory to expose API endpoints according to Directory Network Manager API specifications here: The URI should follow the below format: <https://<server-name>/<base-uri-defined-by-the-client>/aliases/resolve>
3	OAuth Credentials	Remote Directory to provide OAuth credentials securely to implementation manager. This can be done in parallel with the API development.
4	Whitelist IP Addresses	Implementation manager will provide IP addresses to Remote Directory for whitelisting. Note: Directory Network Manager does not need Remote Directory IPs for whitelisting.
5	MLE Setup	Remote Directory and Visa implementation manager to exchange MLE credentials. The Remote Directory will submit a CSR request to the implementation manager. This CSR will be signed by Visa. The Remote Directory should save the private key used to generate the CSR. Implementation Manager will share the “Visa Online CSR” form to Remote Directory. Remote Directory will fill the “Visa Online CSR” form and return it to Implementation Manager. This form is the input to create the public certificate of Directory Network Manager. Implementation manager will share the public certificate of Directory Network Manager.
6	SSL	The Remote Directory will need to provide the certificate chain to the implementation manager.
7	Test Cases	The Remote Directory must complete the test cases provided by the implementation manager.
8	Remote Directory Service Level Requirements	Remote Directory is required to respond to API requests within 3 seconds. Remote Directory uptime must be 99% or higher.

Remote Directory Onboarding Form Details

If a remote directory would like to connect to Directory Network Manager, the below information will need to be provided as part of onboarding.

Key Terms	Definitions
Remote Directory Name	The name of the directory. This parameter will also be used in API calls when clients want to ping a specific directory.
APIs Exposed	This indicates the APIs that the Remote Directory will expose to Directory Network Manager. Valid values: Alias Resolution Alias Inquiry
Supported Country Codes	Specifies the country codes of the requestor that are allowed by the remote directory. For example, if the remote directory only supports “USA”, but the requestor is in “PERU”, then this directory won’t be called in the resolution process.
Supported Alias Types	Valid values: “PHONE” “EMAIL” “DIRECTORY_ALIASID”
Remote Directory Base URL	The base URL of the Remote Directory exposed endpoints.
List of Entity Ids	The entity Id is used by some remote directories to identify the entities within their directory. For example, a remote directory may have multiple banks within its directory. The Alias Resolution request can be sent to a specific bank within that remote directory by using that bank’s entity ID.

Authentication and Encryption

OAuth Authentication

The Remote Directory should provide the below OAuth information in the Remote Directory onboarding form.

Information	Description
Client ID	The client_id is a public identifier for apps.
Client Secret	The client_secret is a secret known only to the application and the authorization server Note: This must be shared in a secured communication with Visa.
Authentication Path	Path of the authentication API which Directory Network Manager can use to get a JWT (Access token).

Information

Description

Client ID

The client_id is a public identifier for apps.

Client Secret

The client_secret is a secret known only to the application and the authorization server

Note: This must be shared in a secured communication with Visa.

Authentication Path

Path of the authentication API which Directory Network Manager can use to get a JWT (Access token).

OAuth 2.0 Specifications

OAuth 2.0 Grant Type client_credentials must to be used for API authentication between the Directory Network Manager and the remote directory. During the Remote Directory setup, Visa will receive a set of credentials to consume an authentication API that the Remote Directory will expose, specifically:

Client ID and Client Secret:
https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/

The path of authentication API which Directory Network Manager can use to get a JWT (Access token) should also be provided to Visa. The JWT must be created according the following specifications for the request and response:

Client Credentials:
Please note that the grant_type parameter must be set to client_credentials.
https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/

Access Token Response:
https://www.oauth.com/oauth2-servers/access-tokens/acc process the response.

OAuth Testing

During test, client should expect a call from Directory Network Manager with the following format. Please note that the content type to be used is “Content-Type: application/x-www-form-urlencoded”

curl -X POST [CLIENT URL] -d "grant_type=client_credentials&client_id=some_client_id&client_secret=some_client_secret" -H content-type=x-www-form-urlencoded -v

Sample OAuth Request:

curl --request POST \
  --url https://client.visa/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=gtb094fb-8575-4ce5-a10e-5afef11c379d \
  --data 'client_secret=fez7-9jtWHVSH*3w'

Sample OAuth Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ6NE1femd4Z3lXZE03S2E4QnJSZjVRQ3RGdmxZY19YOEctSi1hYVhzT3lZIn0.eyJleHAiOjE2OTM1MDk5MjMsImlhdCI6MTY5MzUwODEyMywianRpIjoiZDg3NWUwYzAtZjFmNS00ZmVhLTllNzItZmViMGZjOGNhYmMyIiwiaXNzIjoiaHR0cHM6Ly9kaXJlY3RvcnktY2RlLXN0Zy55ZWxsb3dwZXBwZXIuY29tL3JlYWxtcy9kaXJlY3Rvcnktc3RnIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6Imd0YjA5NGZiLTg1NzUtNGNlNS1hMTBlLTVhZmVmMTFjMzc5ZCIsInR5cCI6IkJlYXJlciIsImF6cCI6Imd0YjA5NGZiLTg1NzUtNGNlNS1hMTBlLTVhZmVmMTFjMzc5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIiwiZGVmYXVsdC1yb2xlcy1kaXJlY3Rvcnktc3RnIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwiY2xpZW50SG9zdCI6IjE4Ni4yOC45OS4xNjAiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImNsaWVudElkIjoiZ3RiMDk0ZmItODU3NS00Y2U1LWExMGUtNWFmZWYxMWMzNzlkIiwicHJvZ3JhbV9pZCI6ImJhZjg1NjI0LTNjZjYtNGM1Mi1iOTFmLWI4ZjM0OTNlNzMzMCIsInBhcnRpY2lwYW50X2lkIjoiMDEyYWY3M2YtNDRkOC00YzljLWJiZWUtNjI4YjA3ZmFhZTFjIiwicHJlZmVycmVkX3VzZXJuYW1lIjoic2VydmljZS1hY2NvdW50LWd0YjA5NGZiLTg1NzUtNGNlNS1hMTBlLTVhZmVmMTFjMzc5ZCIsImNsaWVudEFkZHJlc3MiOiIxODYuMjguOTkuMTYwIn0.K82wwbe0vwRhaRiZt5XMCkMxlSPdkykTf0atAB9q4aO-3MG6Gm6rgFjxskNg7keRL1EvNS-GeYW7p9kMidczpW-xL7hyGnZ7ezQE88DTFlt5Sd13lcuXQhdoTFnQIzQRGPdjXPTY75ZsUI3SkP9puKaWfBjuRaT9Vpmo1ojBGa15Zga1pcaE33vRJHYn9G_qiQchzI54jHS1aO73q8448GfwRkFKJL2xAxJYiuKbJ2yFnrhWbbNNdZT0ftDSaX06RGKGi4ktSc7h2WTyktv5Jw5erb9vtoT1zeM9NwW5XjwF0NX9jTleWUOakpv4XovEWQkaXS1RvxDoNbFRrZNtog",
  "expires_in": 1800,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "read"
}

Message Level Encryption

Overview

Message Level Encryption (MLE) will be used to encrypt the messages that Directory Network Manager exchanges with the Remote Directory.

Message Level Encryption (MLE) allows you to communicate with other parties while helping to prevent uninvolved parties from understanding the communication. MLE can help address the threat of relying on TLS for message security. SSL is designed to provide point-to-point security, which falls short for web/restful services because of a need for end-to-end security. Where multiple intermediary nodes could exist between the two endpoints, MLE would ensure that the message remains encrypted, even during these intermediate "hops" where the traffic itself is decrypted before it arrives the final destination. Both processes involve a mathematical formula (algorithm) and secret data (key).

MLE is required for APIs that primarily deal with sensitive transaction data (financial/non-financial) which could fall into one or several of the following categories:

PII (Personal Identification Information)
PAN (Personal Account Number)
PAI (Personal Account Information)

During the Remote Directory onboarding, Directory Network Manager and the Remote Directory will exchange public keys to cover the flow described below:

Directory Network Manager will encrypt each request body using the Remote Directory public key.
Directory Network Manager will send the encrypted request to the Remote Directory.
Remote Directory will decrypt the request using its private key and process the message.
Remote Directory will encrypt the response body using the Directory Network Manager public key.
Directory Network Manager will decrypt the response using its private key and process the response.

MLE Certificate Information

As part of the MLE certificate signing process, the implementation manager will need to collect the below fields from the Remote Directory.

ID Organization
Environment
ID Owner’s Name
Job Title
Individual Email Address
Business Address
Phone Number
Group Email Address

Encryption Keys Generation

There are two certificate pairs required for MLE:

Server Encryption Key Pair

Remote Directory generates the server encryption certificate and provides the CSR for the relevant Key-ID to the Alias Directory platform. Definitions for CSRs and Key-IDs below:

CSR

Certificate Signing Request is a block of encoded texts used by a CA (Certificate Authority) to create a certificate.

Key-ID

The Key-ID is a unique identifier (UID) associated with the remote directory and identifies the associated key-pairs. This Key-ID will be included as a request header in API calls.

Key-IDs also allow for a more seamless migration to new MLE certificates when needed.

Public key for this certificate is stored on the the Alias Directory platform. The Alias Directory platform will encrypt the requests (message payload) using the public key (of Remote Directory); Remote Directory will use the applicable private key stored on their environment to decrypt the payload and process the API request.

Client Encryption Key

The Alias Directory platform generates the client encryption certificate based on the provided information for a particular Key-ID. The public key for this certificate will be provided to the remote directory during the implementation process. The remote directory will use this public key to encrypt the responses (message payload) and return the information to the Alias Directory platform. The Alias Directory platform uses the private key associated with the Key-ID to decrypt this payload and process the API response.

Key-ID Generation

The Key-ID is a GUID generated by the Remote Directory that associates MLE certificates with it, this Key-ID must be sent to the Alias Directory platform along with the CSR (generation process described below) to complete the process.

Certificate Generation

Remote Directory can use either OpenSSL or Keytool to generate a CSR & private key. The key fields for the CSR are:

CN=<common name>
OU=<organization unit>
O=<organization name>
L=<city/locality name>
ST=<state name>
C=<country name>
UID=<key ID>

Visa Developer Message Level Encryption Guide

Please refer to this Visa Developer encryption guide for more information on MLE and CSR generation.

API Specifications

The remote directory must implement the specifications for Alias Resolution API and Alias Inquiry API to connect with Directory Network Manager. Please see API specifications here.

API Name	Description
Alias Resolution API	This API accepts an Alias for a query and returns a payment credential which can then be used for a push payment.
Alias Inquiry API	This API enables clients to check if an Alias or list of Aliases is available for Alias resolution. The response will indicate the Aliases that are available for Alias resolution.

Alias Metadata

The current Alias Directory Service connects to remote directories and queries these remote directories during every Resolve or Inquiry API call. With the Alias Metadata feature, the number of API calls to the remote directory can be reduced.

Alias Metadata APIs allow remote directories to store limited info in the Alias Directory such as the alias and preferredFor. Below is an example of a Alias Metadata record

{
  "aliases": [
    {
      "aliasValue": "1234567890",
      "aliasType": "PHONE",
      "preferredPaymentCredentials": [
        {
          "type": "CARD",
          "preferredFor": [
            {
              "type": "RECEIVE"
            }
          ]
        }
      ],
      "action": "ADD"
    }
  ]
}

During an Alias Resolution API call, if the Alias contains a preferredFor, then Alias Directory Service will query the Remote Directory for the payment credential. If the Alias does not contain a preferredFor, then the Alias Directory will not query the Remote Directory. Using the example above, if an Alias Resolve API contains “1234567890” in the query, then Alias Directory will query the Remote Directory to retrieve the payment credential. If “1234567890” was not found in the Alias Metadata or was not marked as preferred for “RECEIVE”, then the Alias Directory will not query the Remote Directory.

Please contact your Visa representative for more information.

Visa Alias Directory Service

Simplify the push payment experience. Link and resolve an Alias to a payment credential.