Mobile Credentialing API

This tutorial describes how to use the IdExchange API to generate a mobile credential for a device. The {{IdExchangeServer}} placeholder should be replaced with id.cyberarmed.com

Tools:

In this example, the Postman tool can be used to provide an example of how the API calls are structured. However, any code platform capable of making REST calls will work.

Authentication

The API requires a digital certificate for authentication. When the certificate is verified, the API will return a Java Web Token (JWT) that can be used for subsequent calls.

API Endpoint: https://{{IdExchangeServer}}:444/WebApi/Token

Body: grant_type=password

Response:

Mobile Credential Creation

Step 1: User Registration

The user must be provisioned to the IDMS so that devices can be linked to the user. In the first step, the base user information and PIV Authentication is sent in.

API Endpoint: https://{{IdExchangeServer}}:444/WebApi/api/Requests

Parameters:

Sample JSON:

{
"userId": "MobCred77470740",
"lastName": "MobileLast",
"firstName": "MobileFirst",
"emailAddress": "tuser@cyberarmed.onmicrosoft.com",
"dob": "NR",
"hasSupplementalDocuments": "SETTOREQUESTED",
"userCredentialKey": "IDNTI",
"externalIdSource":"IDMS Applicant Resource",
"PivAuthenticationCertificate":"BASE_64_ENCODED_CERTIFICATE_FROM_PIV_CARD"
}

If successful, the call will return with a 10 digital ID (see screenshot below). Save this ID for later steps.

Step 1.A: User Attribute Registration

User organization information can be added to provide additional identity proofing and credential customization. For example, organization structure information, additional contact information and other information relevant to describe the user’s business relationship with the organization.

API Endpoint: https://{{IdExchangeServer}}:444/WebApi/api/UpdateUserSupplementalAttributes

Parameters

Sample JSON:

{
"UserId": "1000009166",
"AttributeType": "USERSUPPLEMENTATTR",
"AttributeValue": "W3siZGF0YU5hbWUiOiAidXNlcnByaW5jaXBhbG5hbWUiLCJkYXRhVmFsdWUiOiAiTWVzdExhc3Q5NzM4NjYwNUB0ZXN0bW9iaWxlLmxvY2FsIiwidGV4dCI6IG51bGx9LHsiZGF0YU5hbWUiOiAib3JnYW5pemF0aW9uYWxVbml0IiwiZGF0YVZhbHVlIjogIkxBTkwiLCJ0ZXh0IjogbnVsbH0seyJkYXRhTmFtZSI6ICJvcmdhbml6YXRpb25hbFVuaXQyIiwiZGF0YVZhbHVlIjogIk9MVFBLSSIsInRleHQiOiBudWxsfSx7ImRhdGFOYW1lIjogIm9yZ2FuaXphdGlvbmFsVW5pdDMiLCJkYXRhVmFsdWUiOiAiVS5TLiBHb3Zlcm5tZW50IiwidGV4dCI6IG51bGx9LHsiZGF0YU5hbWUiOiAiY291bnRyeSIsImRhdGFWYWx1ZSI6ICJVUyIsInRleHQiOiBudWxsfSx7ImRhdGFOYW1lIjogInNhbWFjY291bnRuYW1lIiwiZGF0YVZhbHVlIjogIk1vYkNyZWQ5NzM4NjYwNSIsInRleHQiOiBudWxsfV0=",
"FileName": "SupplementalData",
"FileType": "json",
"FileSize": "json"
}

Step 2: Add User Biographic Data

The IDMS supports PIV identity proofing workflows that support biometric capture. The next step will be submit the user’s photo, fingerprints, documents and other biometric information required by the credential policy. Even if there is no biometric data to be submitted, this API must be called with empty biometrics in order to enable the user to qualify to receive a credential.

API Endpoint: https://{{IdExchangeServer}}:444/WebApi/api/BioSubmission2

Parameters:

Sample JSON:

{
"Photo":"",
"TransactionType":"AUTOINS",
"userId": "MobCred21625837",
"externalIdSource":"IDMS Applicant Resource",
"UserCredentialPolicyKey":"IDNTI"
}

Step 3: Register user’s device.

In this phase, device information will be registered and linked to the user. The device unique ID, description, device management system and device type will be sent. Additionally, the user id from step 1 will be sent in order to associated the device with the user.

API Endpoint: https://{{IdExchangeServer}}:444/WebApi/api/DeviceInsert

Parameters:

Sample JSON:

{
"Description":"Blackberry",
"DeviceId":"ZZIFKOAN",
"DeviceManagementSystem":"Blackberry",
"DeviceType": "MOBILE",
"TransactionType": "DEVICEADD",
"UserId":"1000009162"
}

Step 4: Approve the user’s device

To provide multi-person control, the device registration and approval phase is separated into two calls to enable one person to register, and another person to verify. When the device is verified, a temporary registration code will be returned. This temporary registration code will be used in the certificate retrieval phase to further verify the request.

API Endpoint: https://{{IdExchangeServer}}:444/WebApi/api/DeviceManagement

Parameters

Sample JSON:

{
"deviceId":"ZZIFKOAN",
"TransactionType":"VERIFY",
"userId":"1000009162",
"DeviceManagementSystem":"Blackberry",
"DeviceType":"Blackberry",
"Description":"Blackberry",
"CertificateAuthorityForCredentialing":"MicrosoftCA"
}

Step 5: Retrieve certificate for device

After the device has been approved, the certificate and be issued.

API Endpoint: https://{{IdExchangeServer}}:444/WebApi/api/DeviceManagement

Parameters:

Sample JSON (no certificate subject customization. only the CSR will be used to create certificate)

{
"DeviceId":"ZZIFKOAN",
"Description":"Mobile credential request",
"DeviceType": "MOBILE",
"TransactionType": "REQCERTIFICATE",
"CertificateAuthorityForCredentialing": "",
"CertificateSigningRequest": "BASE_64_PKCS10_CSR",
"DeviceManagementSystem": "Blackberry",
"TemporaryRegistrationCode":"F2148746-B"

}

Sample JSON (with certificate subject customization)

{
"DeviceId":"ZZIFKOAN",
"Description":"Mobile credential request",
"DeviceType": "MOBILE",
"TransactionType": "REQCERTIFICATE",
"CertificateAuthorityForCredentialing": "",
"CertificateSigningRequest": "BASE_64_PKCS10_CSR",
"DeviceManagementSystem": "Blackberry",
"TemporaryRegistrationCode":"F2148746-B",
"credentialRequestSpecifications": {
"CommonName":"IDMS",
"DeviceId":"IDMS",
"OrganizationalUnitPath": "C = US, O = U.S. Government, OU = TEST, OU = TEST"
}

}

Revoking a device

To revoke the certificate that was retrieved for the certificate, the “TERMDEVICE” transaction type is required.

Sample JSON:

{
"DeviceId":"ZZIFKOBM",
"Description":"Mobile credential termination",
"DeviceType": "MOBILE",
"TransactionType": "TERMDEVICE"
}