Skip to content

IDP Client Assertion

Instead of having individuals create one time passwords to personalize every device, through Client Assertion, a device can be configured to assert who it is and allow the IDP to automatically provision the device and create the access token without human intervention.

Certificate Authority Creation

A certificate authority is required to use the IDP Client Assertion Flow. A root certificate can be uploaded. to the Jumpmind Device IDP that will identify an organizations root signing authority for all devices.

Create Root Certificate Authority

  1. Create openssl.conf for Root CA and Intermediate CA
cat > openssl.conf << EOF
[v3_ca]
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer
basicConstraints=critical,CA:true

[v3_intermediate_ca]
basicConstraints=CA:TRUE,pathlen:0
EOF
  1. Create Root CA Private Key
   openssl genrsa -out root-ca.key 4096
  1. Create Root CA Certificate
   openssl req -new -nodes -x509 -days 3650 -key root-ca.key -out root-ca.crt -subj "/C=Country/ST=State/L=City/O=Organization/CN=Root CA" -extensions v3_ca -config ./openssl.conf

Intermediate Certificate Authority

  1. Create Intermediate CA Key
   openssl genrsa -out intermediate-ca.key 4096
  1. Create Intermediate CA Certificate Request
   openssl req -new -key intermediate-ca.key -out intermediate-ca.csr -subj "/C=Country/ST=State/L=City/O=Organization/CN=Device Intermediate CA"
  1. Sign Intermediate Certificate with Root CA
   openssl x509 -req -in intermediate-ca.csr -CA root-ca.crt -CAkey root-ca.key -CAcreateserial -out intermediate-ca.crt -days 1825 -extensions v3_intermediate_ca -extfile ./openssl.conf
  1. Create Certificate Chain File
   cat intermediate-ca.crt root-ca.crt > ca-chain.crt

For End-Entity Certificates

  1. Generate end-entity key
   openssl genrsa -out device.key 2048
  1. Create certificate request
   openssl req -new -key device.key -out device.csr -subj "/C=Country/ST=State/L=City/O=Business Unit ID/CN=device-id-or-asset-id"
  1. Sign with intermediate CA
   openssl x509 -req -in device.csr -CA intermediate-ca.crt -CAkey intermediate-ca.key -CAcreateserial -out device.crt -days 365
  1. Create full chain
   cat device.crt intermediate-ca.crt root-ca.crt > device.chain.crt

MacOS Importing Device Key and Certificate

  1. Export device private key and certificate chain into a PKCS#12 file format. 
       openssl pkcs12 -export -out device.p12 -inkey device.key -in device.crt -certfile device.chain.crt

IDP Configuration

After creating the certificate authority and device certificates, the IDP must be configured to trust the root CA and the device must be registered with the appropriate scopes.

Upload Root CA to IDP

The root CA certificate must be uploaded to the IDP client pool so it can validate device certificate chains during the JWT-bearer assertion flow.

POST /api/internal/{clientPoolId}/certificates
Content-Type: multipart/form-data
X-API-Key: {globalAdminApiKey}

certificate: @root-ca.crt

Example with curl: 

curl -X POST "https://idp.device.cp.jumpmind.cloud/api/internal/{clientPoolId}/certificates" \
  -H "X-API-Key: your-global-admin-key" \
  -F "certificate=@root-ca.crt"

Response: 

{
  "success": true,
  "message": "Certificate uploaded successfully",
  "clientPoolId": "abc123",
  "filename": "root-ca.crt"
}

Notes: - The certificate must be in PEM format - Only the root CA needs to be uploaded; intermediate CAs in the device certificate chain will be validated against the root - Requires a global admin API key with certificate management permissions

Device Registration for JWT-Bearer Flow

When registering a device that will use the JWT-bearer assertion flow, the device's client application must be created with the device scope. This scope authorizes the device to request access tokens via certificate-based authentication.

POST /api/internal/org/{orgId}/env/{envId}/device/{deviceId}/app
Content-Type: application/json
X-API-Key: {apiKey}

{
  "clientAppId": "client",
  "scopes": ["device"]
}

Important: The scopes array must include "device" for the JWT-bearer flow to succeed. Without this scope, token requests will fail with an invalid_scope error.