Create a Private X.509 Certificate with Component API

Developers can create components using Boomi’s Component API through REST API calls. One of the components you can create with the API is the X.509 Certificate. This API can be helpful when needing to automate cycling of new certificates through automation.

The Component API creates an X.509 certificate in a manner similar to how you create a certificate within the UI. Private certificates must be in a .pfx or .p12 format. If you can create a certificate through the UI, then you can also create that same certificate within the API.

Certificate type	File extension(s)
Private X.509	.pfx or .p12

This article reviews the basic set up required to create a certificate and extends that example to chains of API calls used for automation.

Create a Private X.509 Certificate

Private X.509 certificates contain the private certificate and can contain the root CA (Certificate Authority) and intermediates. It is recommended to import a pfx file that contain the full chain of certificates. This certificate is commonly used with Boomi runtime’s Shared Web Server.

Private Certificate - Building the Payload

The resource path for creating an X.509 is /Component. The full XML structure is below with the required and optional fields. The optional fields are helpful when viewing the X.509 component within Boomi. Yet, they are not required and the certificate functions the same with or without the required fields. The table below contains the required elements. The CertificateData field is truncated to make the example easier to read.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bns:Component  xmlns:bns="http://api.platform.boomi.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="Atomsphere API X.509 Example" type="certificate">
	<bns:object>
		<bns:CertificateModel xmlns:bns="http://api.platform.boomi.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" password="boomi">
			<bns:Type>private</bns:Type>
			<bns:IssuedTo fullName="CN=CN,OU=OU,O=Org,L=LOC,ST=USA,C=CTY" />
      <bns:Issuer fullName="CN=CN,OU=OU,O=Org,L=LOC,ST=USA,C=CTY"/>
      <bns:Validity issueDate="2024-06-10T20:21:59.000Z"/>
			<bns:CertificateData>MIACAQMwgASVJWJDiF+jsFYyBoIAkgASCA+gwgDCABgkqhkiGvABIID6DCCBU8wggVLKkdqpw3og
        BgsqhkiG9liAuJcCYeyfC7BbKQMlV7nBjFLbeeLggT2MCgGCiqGSIb3DQEMAQM/OpkoDywLvKwtr
        ....
        AAAAAAAAAAAAAAAAAAAwPTAhMAkGBSsOAwIaBQAEFELOWrFZEi2T+gWAGr51ZZWuDi/YBBTTLCPg
        Jf7DGgUABBTSrxhowQ0zlCICBAAAAA==</bns:CertificateData>
		</bns:CertificateModel>
	</bns:object>
</bns:Component>

Table 1. List of elements used for Private X.509 Certificates.

Private Certificate Elements	Description	Required
Component.@branchId	Id of the branch to create the component. Defaults to the user’s default branch.	No
Component.@folderId	Id of the folder to create the component. Defaults to the root folder.	No
Component.@name	Name of certificate within Boomi	Yes
Component.description	Description within Boomi	No
Component.object.CertificateModel.@MD5Fingerprint	MD5 Fingerprint of certificate. Useful for identification.	No
Component.object.CertificateModel.@SHA1Fingerprint	SHA1 Fingerprint of certificate. Useful for identification.	No
Component.object.CertificateModel.@serialNumber	Serial Number of certificate. Useful for identification.	No
Component.object.CertificateModel.@signatureAlgorithm	Signature Algorithm of certificate.	No
Component.object.CertificateModel.@password	Password for the certificate	Yes
Component.object.CertificateModel.Type	private	Yes
Component.object.CertificateModel.IssuedTo.@fullName	String that includes the CN, O, OU, L, ST, and C of the Issued To	Yes
Component.object.CertificateModel.IssuedTo.@country	Issued To Country	No
Component.object.CertificateModel.IssuedTo.@organization	Issued To Organization	No
Component.object.CertificateModel.IssuedTo.@organizationalUnit	Issued To Organization Unit	No
Component.object.CertificateModel.Issuer.@fullName	String that includes the CN, O, OU, L, ST, and C of the Issuer	Yes
Component.object.CertificateModel.Issuer.@country	Issues Country	No
Component.object.CertificateModel.Issuer.@organization	Issuer Organization	No
Component.object.CertificateModel.Issuer.@organizationalUnit	Issuer Organizational Unit	No
Component.object.CertificateModel.Validity.@expireDate	Expiration Date of the certificate. Datetime Format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`	No
Component.object.CertificateModel.Validity.@issueDate	Issue Date of the certificate. Datetime Format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`	Yes
Component.object.CertificateModel.CertificateData	The full certificate that is base64 encoded	Yes

NOTE: CertificateData contains the entire certificate base64 encoded.

The image below is what the certificate looks like within Boomi with only the required fields populated. It is pretty sparse in information but it is a functional private certificate.

A private certificate with only the basic fields populated.

Figure 1. A private certificate with only the basic fields populated.

The image below is what the certificate looks like within Boomi with the required and optional fields populated. It looks similar to if you imported the certificate within the UI. The API does not do any of the additional reading and parsing of the certificate that the UI does.

A private certificate with all fields populated.

Figure 2. A private certificate with all fields populated.

Private Certificate - Base64 Encode the Certificate

There are multiple ways to base64 encode the certificate, but one possible way is to open the certificate within Notepad++ and use the base64 plugin to encode it.

First open the certificate with Notepad++.

A view of binary data within the certificate

Figure 3. A private X.509 certificate open in Notepad++.

Next, install the MIME Tools plug-in if it is not already installed. Navigate to Plugins -> Plugin Admin… -> Search for MIME -> Select and Install.

After installing MIME Tools, select the entire certificate text and navigate to Plugins -> MIME Tools -> Base64 Encode.

Select Base64 Encode within Notepad++

Figure 4. Select Base64 Encode within Notepad++.

Finally, copy and paste the contents into the CertificateData field.

Base64 Encoded Private Certificate to populate within the CertificateData field.

Figure 5. Base64 Encoded Private Certificate to populate within the CertificateData field.

Automation Concepts

With a grounding of the basics, the next part of the article reviews the steps involved within automating the creation of a new certificate Component and applying it to the runtime’s Shared Web Server or deploying it to an environment. The private X.509 certificate is often used for the shared web server. The following outlines the steps to creating a private certificate and adding it to the Shared Web Server.

Step 1 - Private X.509 Certificate - Create Component

Make a POST call to the Component API to create a new component.

POST https://api.boomi.com/api/rest/v1/{accoundIt}/Component

<!-- Component Create Request -->
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bns:Component  xmlns:bns="http://api.platform.boomi.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="Atomsphere API X.509 Example" type="certificate">
	<bns:object>
		<bns:CertificateModel xmlns:bns="http://api.platform.boomi.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" password="boomi">
			<bns:Type>private</bns:Type>
			<bns:IssuedTo fullName="CN=CN,OU=OU,O=Org,L=LOC,ST=USA,C=CTY" />
      <bns:Issuer fullName="CN=CN,OU=OU,O=Org,L=LOC,ST=USA,C=CTY"/>
      <bns:Validity issueDate="2024-06-10T20:21:59.000Z"/>
			<bns:CertificateData>MIACAQMwgASVJWJDiF+jsFYyBoIAkgASCA+gwgDCABgkqhkiGvABIID6DCCBU8wggVLKkdqpw3og
        BgsqhkiG9liAuJcCYeyfC7BbKQMlV7nBjFLbeeLggT2MCgGCiqGSIb3DQEMAQM/OpkoDywLvKwtr
        ....
        AAAAAAAAAAAAAAAAAAAwPTAhMAkGBSsOAwIaBQAEFELOWrFZEi2T+gWAGr51ZZWuDi/YBBTTLCPg
        Jf7DGgUABBTSrxhowQ0zlCICBAAAAA==</bns:CertificateData>
		</bns:CertificateModel>
	</bns:object>
</bns:Component>

Component API Response

<!-- Component Create Response -->
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bns:Component xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bns="http://api.platform.boomi.com/" folderFullPath="" componentId="13a0a904-de7a-4a3f-8e93-12345" version="1" name="Atomsphere API X.509 Example" type="certificate" createdDate="2025-02-21T22:32:10Z" createdBy="" modifiedDate="2025-02-21T22:32:10Z" modifiedBy="" deleted="false" currentVersion="true" folderName="" folderId="RjoDI123" branchName="main" branchId="Qjoz123">
    <bns:encryptedValues>
        <bns:encryptedValue path="//CertificateModel/@password" isSet="true"/>
        <bns:encryptedValue path="//CertificateModel/CertificateData/text()" isSet="true"/>
    </bns:encryptedValues>
    <bns:description>rst</bns:description>
    <bns:object>
        <CertificateModel xmlns="" MD5Fingerprint="5A:10:86:0C:F0:EA:00:D4:96:AF:FF:D1:E9:7C:AE:23" SHA1Fingerprint="58:24:71:4E:0C:CC:74:C8:EC:8D:79:6A:69:5E:4C:24:15:D1:A7:CE" password="704bfcfc591bb0e51d4453bd53d914678800f5772417174574313a33591630ce67a20b0a11b" serialNumber="00:D0:3C:6B:AB:04:A2:4E:73:BE:D0:F6:1D:04:BB:B0:18" signatureAlgorithm="SHA512withRSA" version="3">
            <Type>private</Type>
            <IssuedTo commonName="CN" country="CTY" fullName="CN=CN,OU=OU,O=Org,L=LOC,ST=USA,C=CTY" organization="Org" organizationalUnit="OU"/>
            <Issuer commonName="CN" country="CTY" fullName="CN=CN,OU=OU,O=Org,L=LOC,ST=USA,C=CTY" organization="Org" organizationalUnit="OU"/>
            <Validity expireDate="2025-06-10T20:21:59.000Z" issueDate="2024-06-10T20:21:59.000Z"/>
            <CertificateData>052b129286ef5f75d56ee5d5b3f79b5a6463f5e8a5eb82ce20e12e8c</CertificateData>
        </CertificateModel>
    </bns:object>
</bns:Component>

The response returns the componentId and is used in the next call.

Step 2 - Private X.509 Certificate - Upload Certificate to the Runtime’s Shared Web Server

The ShareWebServer API updates the Shared Web Server on a Boomi runtime.

Figure 6. Example Runtime with SSL enabled in the Shared Web Server panel.

Make a GET call to the shared Web Server.

GET https://api.boomi.com/api/rest/v1/{accoundId}SharedWebServer/{atomId}

The SharedWebServer API request returns the following response.

// SharedWebServer Get Response
{
  "@type": "SharedWebServer",
  "atomId": "60a40341-21f2-4bc9-ad5f-da4e7024123",
  "generalSettings": {
    "@type": "SharedWebServerGeneral",
    "apiType": "ADVANCED",
    "authentication": {
      "@type": "SharedWebServerAuthentication",
      "authType": "BASIC",
      "cacheAuthorizationCredentials": false,
      "loginModuleOptions": {
        "@type": "SharedWebServerLoginModuleConfiguration"
      },
      "cacheAuthenticationTimeout": 0
    },
    "overrideUrl": false,
    "baseUrl": "https://ip-123123.ec2.internal:9090",
    "examineForwardHeaders": false,
    "externalHost": "",
    "internalHost": "",
    "listenerPorts": {
      "@type": "ListenerPortConfiguration",
      "port": [
        {
          "@type": "SharedWebServerPort",
          "enablePort": true,
          "port": 9090,
          "ssl": true,
          "authType": "BASIC",
          "externalPort": 0,
          "externalSSL": false,
          "defaultPort": true,
          "baseUrlForRequest": "https://ip-123123.ec2.internal:9090"
        },
        {
          "@type": "SharedWebServerPort",
          "enablePort": true,
          "port": 9091,
          "ssl": false,
          "authType": "BASIC",
          "externalPort": 0,
          "externalSSL": false,
          "defaultPort": false,
          "baseUrlForRequest": "http://ip-123123.ec2.internal:9091"
        }
      ]
    },
    "maxNumberOfThreads": 250,
    "protectedHeaders": {
      "@type": "SharedWebServerProtectedHeaders"
    },
    "sslCertificate": "a7155f03-0847-4b0e-9212-2dfff123123"
  },
  "userManagement": {
    "@type": "SharedWebServerUserManagement",
    "enableAPIMInternalRoles": false,
    "users": []
  },
  "corsConfiguration": {
    "@type": "SharedWebServerCors"
  }
}

Start with the response payload and keep only the @type, atomId, and generalSettings elements. The other sections do not require updates. Update sslCertificate and send the payload as a POST to the same resource path.

POST https://api.boomi.com/api/rest/v1/{accoundId}/SharedWebServer/{atomId}

// SharedWebServer Update Request
{
  "@type": "SharedWebServer",
  "atomId": "60a40341-21f2-4bc9-ad5f-da4e701234",
  "generalSettings": {
    "@type": "SharedWebServerGeneral",
    "apiType": "advanced",
    "authentication": {
      "@type": "SharedWebServerAuthentication",
      "authType": "BASIC",
      "cacheAuthorizationCredentials": false
    },
    "overrideUrl": false,
    "baseUrl": "http://ip-123123.ec2.internal:9091",
    "examineForwardHeaders": false,
    "externalHost": "",
    "internalHost": "",
    "listenerPorts": {
      "@type": "ListenerPortConfiguration",
      "port": [
        {
          "@type": "SharedWebServerPort",
          "enablePort": true,
          "port": 9090,
          "ssl": true,
          "authType": "BASIC",
          "externalPort": 0,
          "externalSSL": false,
          "defaultPort": true
        },
        {
          "@type": "SharedWebServerPort",
          "enablePort": true,
          "port": 9091,
          "ssl": false,
          "authType": "BASIC",
          "externalPort": 0,
          "externalSSL": false,
          "defaultPort": false
        }
      ]
    },
    "maxNumberOfThreads": 250,
    "protectedHeaders": {
      "@type": "SharedWebServerProtectedHeaders"
    },
    "sslCertificate": "13a0a904-de7a-4a3f-8e93-12345" // New Provate X.509 Certificate Id
  }
}

A successful response returns the same payload and the new certificate is visible within the Shared Web Server UI.

Conclusion

Now that you have the tools to create a private X.509 certificate, you are able to automate the creation of certificates without having to manually import a new certificate.

The article was originally posted at Boomi Community.