Anleitung zur vollständigen Automatisierung des Bestellprozesses für S/MIME Zertifikate. Als Beispiel wird hier das Produkt GlobalSign - PersonalSign Class 1 verwendet. Bei S/MIME-Zertifikaten handelt es sich um Zertifikate für das Verschlüsseln und Signieren von E-Mails. Aktuell werden die S/MIME-Produkte von Globalsign angeboten.

Inhaltsverzeichnis dieser Seite

Grundlagen der JSON-und XML-API

Alle wichtigen Informationen für die Nutzung der JSON- und XML-API findest du bei den API-Grundlagen,  den XML- und JSON-Grundlagen.
Die spezifischen SSL-Objekte sind hier dokumentiert, die SSL-Auftragstypen hier.

Prozessübrsicht

Ablaufdiagramm

Auftragstypen-Codes und Routen

AuftragstypCodeRoute
CertificateCreate400101POST /certificate
SSLContactCreate400201POST /sslcontact
CertificateInfo

400104

GET /certificate/$id
PollInfo0905GET /poll
PollConfirm0906PUT /poll/$id
CertificatePrepareOrder

400110

POST /certificate/_prepareOrder

Vorbereitung der Bestellung

Kontakt anlegen

Für die Bestellung eines S/MIME-Zertifikats benötigst du einen administrativen Kontakt (AdminC). Du kannst bereits vorhandene Kontakte verwenden oder neue Kontakte anlegen. Du kannst alle Kontakte für zukünftige Bestellungen verwenden.

ContactCreate - Beispiel

Request 
POST /sslcontact
{
  "fname": "John",
  "lname": "Doe",
  "phone": "+49-123-12345",
  "fax": "+49-123-12345",
  "email": "john.doe@example.com",
  "title": "Admin",
  "organization": "Company",    
  "address": [
	"123 Main Street"
  ],     
  "pcode": "12345",
  "city": "Anytown",
  "country": "DE",
  "state": "BY"
}
Response 
{
    "stid": "20180926-stid",
    "status": {
        "code": "S400201",
        "text": "Kontakt wurde erfolgreich angelegt.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "contact",
        "value": "100"
    },
    "data": [
        {
            "fname": "John",
            "lname": "Doe",
            "phone": "+49-123-12345",
            "email": "john.doe@example.com",
            "title": "Admin",
            "organization": "Company",
            "address": "123 Main Street",
            "pcode": "12345",
            "city": "Anytown",
            "country": "DE",
            "state": "BY",
            "owner": {
                "user": "user",
                "context": 9
            },
            "id": 100
        }
    ]
}
Request 
<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>400201</code>
        <contact>
            <first>Michael</first>
            <last>Mustermann</last>
            <phone>+49-941-1234560</phone>
            <email>michael.mustermann@example.com</email>
            <title>Admin</title>
            <organization>Beispiel GmbH</organization>
            <address>Maximilianstrasse 36000</address>
            <postal_code>93047</postal_code>
            <city>Regensburg</city>
            <country>DE</country>
            <state>Bayern</state>
        </contact>
    </task>
</request>
Response 
<response>
    <result>
        <data/>
        <status>
            <code>S400201</code>
            <text>Kontakt wurde erfolgreich angelegt.</text>
            <type>success</type>
            <object>
                <type>contact</type>
                <value>100</value> <!-- Die ID des angelegten Kontaktes -->
            </object>
        </status>
    </result>
</response>

Ein S/MIME-Zertifikat bestellen

Zertifikat bestellen

Mit dem Auftragstyp CertificateCreate  sendest du die Bestellung ans System. Dabei musst du bestimmte Werte setzen:

  • Zertifikatstyp = Typ des Zertifikates für S/MIME "MAIL".
  • Admin = Die ID des administrativen Kontaktes (AdminC).
  • Name =  Der Name des Zertifikates. Bei S/MIME-Zertifikaten ist dies die E-Mail-Adresse, für die das Zertifikat verwendet wird.
  • Produkt =  Wert des S/MIME-Zertifikates, für unser Beispiel ist dies GLOBALSIGN_PERSONALSIGN_1.
  • Vorname = Vorname
  • Nachname = Nachname
  • Laufzeit =  Die gewünschte Laufzeit. Die möglichen Laufzeiten hängen vom Zertifikats-Produkt ab.
  • Passwort = Das Passwort zum Herunterladen des Zertifikates von Globalsign.
  • Organisationseinheit = Die zuständige Organisationseinheit, z. B.  "Marketing-Abteilung".
  • CSR = Angabe, ob ein eigener CSR verwendet wird oder nicht. Tag <has_csr> mit den Werten "True" oder "False".

CertificateCreate - Beispiel


Route: POST /certificate

Request 
{
   "adminContact": {
      "id": 100
   },
   "technicalContact": {
      "id": 100
   },
   "name": "john.doe@example.com",
   "lifetime": {
      "unit": "MONTH",
      "period": 36
   },
   "csr": "-----BEGIN CERTIFICATE REQUEST-----MIICujCCAaICAQAwdTELMAkGA1UEBhMCREUxDzANBgNVBAgMBmJhdmFyaTETMBEGA1UEBwwKcmVnZW5zYnVyZzERMA8GA1UECgwIc3VwZXJkZXYxFDASBgNVBAsMC2RldmVsb3BtZW50MRcwFQYDVQQDDA5qdW5rZHJhZ29ucy5kZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMSMhi30bENDqWeXp7SfHhi2epocJeuI6bBeqGYyQCM5yuoUyAC6wuQ5xudC+hJ6dnDp8p8l8ObkcLrU8/vZJCVmfHxkQpOy6oIsz8uvNA7VcLqOQfxINxe0lqAD0SAWYUaB2W+4CVqyFxaKIn/1c2Isg+8d8Y/3l/t0lI0CF7Y4Q/EmIh1Rl2cr1ONQd4P+3mx2V0ExYN69zPRIsEHt1bV9Mo3l7QpMybHKANMK4BHVL+F5oL8vyGElLCScm3ryrl4W+C0N5V1SSGLNTfNiDxkPx9dwCc5iBy/X8FfhZ7z3+JdjluWo513wvdwZH+jbWhvQ7wsmnV0lGQoe4jHwF+UCAwEAAaAAMA0GCSqGSIb3DQEBCwUAA4IBAQCzQXKkBJWdaGtHLdI9/pqJ/zVCISGsH8lXo8tMBUyZk9cCYdH0hvsVduqNJRpBzNi07ivK/T3+Ru3SUYl0DKlsfHm5IEjf2lYJgJORXS5SRMkr7sYfYSAeGsoUIXc1GC4hBnSFmKN6NoLLbHaAItNDo9AWKVr/1ZqPy9v5vaJpTSzYidrTcZth4lF+i4QqcchorIPq4hSMKWkhZs5tzd/+hAR0XV2hcH1RGcuHTWOJmAvk0Nw2eVxUgNJSmiU0OneyRO4qQoWC/1khDFI0/xt0apn0OeYpcu8rA3aXsHCbcCqpjLUSBZ45szn60KL5sW9/S4y2oUjUbUQb3NW4TFgw-----END CERTIFICATE REQUEST-----",
   "product": "GLOBALSIGN_PERSONALSIGN_1",
   "firstname": "Jon",
   "lastname": "Doe",
   "password": "Hello1"
}
Response 
{
   "stid": "20190702-app3-dev-10171",
   "status": {
      "code": "N400101",
      "text": "Zertifikats-Auftrag wurde erfolgreich gestartet.",
      "type": "NOTIFY"
   },
   "object": {
      "type": "Certificate",
      "value": "john.doe@example.com"
   },
   "data": [
      {
         "id": 4297543967
      }
   ]
}
Request 
<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <certificate>
            <certificate_type>MAIL</certificate_type>
            <product>GLOBALSIGN_PERSONALSIGN_1</product>
            <lifetime>36</lifetime>
            <name><![CDATA[max.mustermann@example.com]]></name>
            <approver_email>admin@example.com</approver_email>
            <password>****</password>
            <firstname>Max</firstname>
            <lastname>Mustermann</lastname>
            <organization_unit_name>marketing</organization_unit_name>
            <has_csr>false</has_csr>
            <admin>
                <id>100</id>
            </admin>
        </certificate>
        <code>400101</code>
    </task>
</request>
Response 
<response>
  <result>
    <data>
      <certificate_job>
        <job>
          <id>123456</id>
          <status>RUNNING</status>
        </job>
      </certificate_job>
    </data>
    <status>
      <code>N400101</code>
      <text>Zertifikatsauftrag wurde erfolgreich gestartet. </text>
      <type>notify</type>
      <object>
        <type>certificate</type>
        <value>max.mustermann@example.com</value>
      </object>
    </status>
  </result>
</response>

Benachrichtigungen erhalten

Der Auftragstyp CertificateCreate erzeugt automatisch einen Auftrag für die Bestellung des Zertifikats. Ist der Auftrag abgearbeitet, wird eine Benachrichtigung generiert, mit Informationen über den Auftrag. War der Auftrag erfolgreich, so erhälst du unter anderem die ID des bestellten Zertifikates. Die Benachrichtigung kann mit den Methoden Polling und Push abgerufen bzw. zugesendet werden.

Zertifikats-Daten ermitteln

Der Auftragstyp CertificateInfo ermittelt alle Zertifikatsdaten. Die Daten können mit Hilfe der ID aus dem Schritt Benachrichtigungen erhalten abgefragt werden.

CertificatInfo - Beispiel

Request 
GET /certificate/$id
Response 
{
    "stid": "20180926-stid",
    "status": {
        "code": "S400104",
        "text": "Zertifikatsdaten wurden erfolgreich ermittelt.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "certificate",
        "value": "example.com"
    },
    "data": [
        {
            "created": "2018-09-26T00:00:00.000+0200",
            "updated": "2018-09-26T11:38:08.000+0200",
            "id": 13258,
            "owner": {
                "user": "user",
                "context": 9
            },
            "orderId": "2695961",
            "adminContact": {
                "id": 100
				...
            },
            "technicalContact": {
                "id": 100
				...
            },
            "name": "john.doe@example.com",
            "lifetime": {
                "unit": "MONTH",
                "period": 12
            },
      
            "csr": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----",
            "server": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----\n",
            "serialNumber": "750C3006B23B90D0F396A3D153EB4C8",
            "product": "GLOBALSIGN_PERSONALSIGN_1",
            "expire": "2019-09-26T12:00:00.000+0200",
            
            "certificateTransparencyPrivacy": "PUBLIC",
            "domain": "example.com"
        }
    ]
}
Request 
<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>400104</code>
        <certificate>
            <id>100</id>
        </certificate>
    </task>
</request>
Response 
<response>
  <result>
    <data>
      <certificate>
        <order_id>1003396954</order_id>
        <technical>
          <first>Michael</first>
            <last>Mustermann</last>
            <phone>+49-941-1234560</phone>
            <email>michael.mustermann@example.com</email>
            <title>Admin</title>
            <organization>Beispiel GmbH</organization>
            <address>Musterstrasse36000</address>
            <postal_code>93047</postal_code>
            <city>Musterstadt</city>
            <country>DE</country>
            <state>Bayern</state>
          <owner>
            <user>USER</user>
            <context>CONTEXT</context>
          </owner>
          <updater>
            <user>USER</user>
            <context>CONTEXT</context>
          </updater>
          <id>20398</id>
          <created>2017-01-01 10:35:22</created>
          <updated>2017-01-01 01:05:07</updated>
        </technical>
        <admin>
          <first>Michael</first>
            <last>Mustermann</last>
            <phone>+49-941-1234560</phone>
            <email>michael.mustermann@example.com</email>
            <title>Admin</title>
            <organization>Beispiel GmbH</organization>
            <address>Musterstrasse 36000</address>
            <postal_code>93047</postal_code>
            <city>Musterstadt</city>
            <country>DE</country>
            <state>Bayern</state>
          <owner>
            <user>USER</user>
            <context>CONTEXT</context>
          </owner>
          <updater>
            <user>USER</user>
            <context>CONTEXT</context>
          </updater>
          <id>20398</id>
          <created>2017-01-01 10:35:22</created>
          <updated>2017-01-01 01:05:07</updated>
        </admin> 
        <name>example.com</name>
        <lifetime>12</lifetime>
        <software>APACHE2</software>
        <csr><![CDATA[----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----]]></csr>
        <server><![CDATA[----BEGIN CERTIFICATE ----- .... -----END CERTIFICATE-----]]></server>
        <serial_number>SERIALNUMBER</serial_number>
        <product>QUICKSSLPREMIUM</product>
        <sha>SHA2</sha>
        <expire>2030-01-01 23:59:59</expire>
        <extension />
        <certification_authority>
          <ca_type>ICA1</ca_type>
          <ca_cert><![CDATA[----BEGIN CERTIFICATE ----- .... -----END CERTIFICATE-----]]></ca_cert>
        </certification_authority>
        <authentication>
          <method>DNS</method>
          <dns>example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"</dns>
        </authentication>
        <owner>
          <user>USER</user>
          <context>CONTEXT</context>
        </owner>
        <updater>
          <user>USER</user>
          <context>CONTEXT</context>
        </updater>
        <id>100</id>
        <created>2017-01-01 00:00:00</created>
        <updated>2017-01-01 14:30:36</updated>
      </certificate>
    </data>
    <status>
      <code>S400104</code>
      <text>Zertifikatsdaten wurden erfolgreich ermittelt.</text>
      <type>success</type>
      <object>
        <type>certificate</type>
        <value>example.com</value>
      </object>
    </status>
  </result>
</response>