eMASS Account Process Request and API Registration

The instructions listed in this document are intended for:

• Anyone requesting access to any Sponsoring Organization’s instance of the Enterprise Mission Assurance Support Service (eMASS).
• A client application programming interface (API; e.g., emasser) that requires access to a Sponsoring Organization’s eMASS instance.

The eMASS is a government-owned, web-based application with a broad range of services for comprehensive and fully integrated cybersecurity management. Features include dashboard reporting, controls scorecard measurement, and generation of a system security authorization package. A client eMASS API (e.g., emasser is one specific client) is any application that communicates with Sponsoring Organization’s eMASS instance via representational state transfer (REST) API that enables users to perform assessments and complete actions associated with system records.

Tip

• Most links on the DCSA website require CAC authentication.
• Detailed information on requesting access to eMASS can be found on the DCSA Website eMASS tab.

If you already have an eMASS account proceed to API Registration

eMASS Account Access via Web Browser

To request a National Industrial Security Program (NISP) eMASS account, cleared defense contractors must:

1. Have or obtain a DoD Common Access Card (CAC) through the DoD Sponsoring organization.
2. Complete the DISA Cyber Awareness Challenge training (no CAC required).
3. Complete the DISA eMASS Computer Based Training (CBT).
4. Complete the sponsor organization System Authorization Access Request (SAAR) form.
   • NISP eMASS Account Request and Access Procedures
   • Industry SAAR Instructions
   • Industry SAAR Form
   • Field Office Facilities
5. Submit all artifacts (above) to:
   • DCSA NISP Authorization Office (NAO) eMASS mailbox
   • Or your organization's eMASS instance representative
6. Access NISP eMASS instance and add the new certificate credentials to your user account.

Tip

• When completing the SAAR form select an Identity Role that can be granted API Data Access privileges. Consult with the eMASS owner organization for the proper role.
• NISP eMASS Account Request and Access Procedures guide are found here

API Registration

Requirements:

• User registering an API client must have a valid CAC.
• The user-id used with the API client is the DoD ID Number (EIDIPI) provided on the DoD CAC.
• If actionable requests (POST, PUT, or DELETE) are required, an account in the Sponsoring Organization eMASS instance is required.

Process

For a cleared defense contractor to utilize the emasser API client, the Sponsoring Organization needs to register the emasser API client within their eMASS instance.

1. The Sponsoring Organizations must provision a non-person entity (NPE) certificate to be used with their eMASS instance.

2. Obtain an API-key (api-key):

   • The eMASS Sponsoring Organization development team provides and registered the API-key

   • Use the [eMASS_URL]/api/api-key endpoint to register the NPE certificate & obtain an API-key

   • This can be accomplished using curl or emasser:

     • curl -X POST -d -L "[URL]/api/api-key" --cert .\cert.cer --key .\private.key
     • emasser post register cert

     Note: Using emasser to obtain the api-key requires that environmental variables are properly set.

3. Authorize the API client to perform actionable requests:

   • user must grant permissions for the client from their eMASS User Profile in the API Data Access section by selecting a checkbox for the applicable client and clicking [Save]

Note

Using eMASSer register endpoint to obtain the api-key requires that environmental variables are properly set.

Accessing eMASS via the API

To access a Sponsoring Organization via the emasser eMASS client:

1. Use the provided NPE Certificate for every endpoint call
   • client cert (e.g., .pem or .cer)
   • private key (e.g., .pem or .key)
2. The API-key (api-key) must be provided in the request header for all endpoint calls.
3. The User unique identifier (user-id) key must be provided in the request header for all PUT, POST, and DELETE endpoint calls.
4. Example curl endpoint command for retrieving all systems:

   curl -X GET -d -L "URL/api/systems/" --cert client.pem:certpassword --key key.pem -H "api-key:the-api-key-value"
   

5. If the service receives an untrusted certificate or API key, a 401-error response code will be returned along with an error message.