Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Anleitung zur vollständigen Automatisierung des Bestellprozesses für Zertifikate.  Als Beispiel wird hier das Produkt QuickSSLPremium verwendet und als Authentifizierungsmethode DNS.

Der Bestellprozess für S/MIME-Zertifikate weicht ab und wird hier beschrieben.

Panel
titleColor#FFFFFF
titleBGColor#E44313
titleInhaltsverzeichnis dieser Seite

Table of Contents
maxLevel3
outlinetrue
stylenone

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übersicht

Ablaufdiagramm

Auftragstypen, Codes und Routen

AuftragstypCodeRoute
SSLContactCreate400201POST /sslcontact
CertificatePrepareOrder

400110

POST /certificate/_prepareOrder
CertificateCreate400101POST /certificate
PollInfo0905GET /poll
PollConfirm0906PUT /poll/$id
CertificateInfo

400104

GET /certificate/$id

DNS-Validierung

Die DNS-Validierung, also die Validierung durch Zonen-Eintrag, wird von vielen domain-validierten Zertifikaten unterstützt.  Dafür musst du für manche CAs in der zum Zertifikats-Namen gehörenden Zone einen bestimmter TXT- oder CNAME-Record hinterlegen. Dieser wird von der austellenden Zertifikats-Stelle auf Gültigkeit geprüft. Wird die dazugehörige Zone von InterNetX verwaltet, erfolgt die Provisionierung der Zone automatisch.

Vorbereitung

Anchor
sslconnect
sslconnect
SSLManager mit AutoDNS verbinden

Für die automatische Provisionierung der Zone, musst du einmalig den SSLManager mit deinem AutoDNS Zugang verbinden.
Gehe im SSL Manager zu den Benutzereinstellungen und klicken auf den MenüpunktSSL Manager mit dem Domain-Verwaltungssystem verbinden.

Du wirst dann auf die AutoDNS Login-Seite geleitet. Gebe hier zum Herstellen der Verbindung deine AutoDNS Zugangsdaten ein.



Info
Gegebenenfalls musst du die URL zu Ihrem Personal AutoDNS oder Registrar AutoDNS selbst eingeben.
Info

Beachte, dass du die folgenden Aktionen mit deinem SSLManager Benutzer durchführen musst.

Kontakt anlegen (Contact Create)

Für die Bestellung eines QuickSSLPremium Zertifikats wird ein technischer und administrativer Kontakt benötigt. Du kannst bereits vorhandene Kontakte verwenden oder neue Kontakte anlegen, die du dann alle für zukünftige Bestellungen verwenden kannst.

ContactCreate  Beispiel

SP Tabs group
dispositionhorizontal
SP Tab pane
anchor2286824
nameJSON
Code Block
languagejs
titleRequest
linenumberstrue
collapsetrue
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"
}
Code Block
languagejs
titleResponse
linenumberstrue
collapsetrue
{
    "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
        }
    ]
}
SP Tab pane
anchor87031
nameXML
Code Block
languagexml
titleRequest
linenumberstrue
collapsetrue
<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>
Code Block
languagexml
titleResponse
linenumberstrue
collapsetrue
<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 QuickSSLPremium Zertifikat bestellen

DNS-Record erzeugen und CSR prüfen (Certificate Prepare Order)

QuickSSLPremium Zertifikate werden durch TXT-Einträge verifiziert. Dafür muss in der zum Common-Name (CNAME) gehörenden Zone ein neuer TXT-Record mit bestimmten Werten hinterlegt werden.

Beispiel TXT : 
example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q
"

Mit dem Auftragstyp CertificatePrepareOrder wird der bereitgestellte CSR Key geprüft (z.B. auf die richtige Bit-Länge) und es werden die benötigten Authentifizierungsdaten erzeugt.

Info
Beachte, dass der CSR-Code in einer einzigen Zeile stehen muss. Evtl. vorhandene Zeilenumbrüche müssen entfernt werden.

CertificateOrderPrepare Beispiel

SP Tabs group
dispositionhorizontal
SP Tab pane
anchor2286824
nameJSON
Code Block
languagejs
titleRequest
linenumberstrue
collapsetrue
POST /certificate/_prepareOrder
{
  "plain": "----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----",
  "product": "QUICKSSLPREMIUM"
}
Code Block
languagejs
titleResponse
linenumberstrue
collapsetrue
{
    "stid": "20180926-stid",
    "status": {
        "code": "S400110",
        "text": "CSR Key wurde erfolgreich geprüft.",
        "type": "SUCCESS"
    },
    "data": [
        {
            "plain": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----",
            "name": "example.com",
            "keySize": 2048,
            "countryCode": "DE",
            "state": "BY",
            "city": "Regensburg",
            "organization": "Company GmbH",
            "organizationUnit": "Entwicklung",
            "product": "QUICKSSLPREMIUM",
            "authentication": [
                {
                    "method": "EMAIL",
                    "approverEmails": [
                        "admin@example.com",
                        "administrator@example.com",
                        "hostmaster@example.com",
                        "webmaster@example.com",
                        "postmaster@example.com"
                    ]
                },
                {
                    "method": "DNS",
                    "dns": "example.com.\t\t300\tIN\tTXT\t\"2018092608362142n4sbul8rv8ttv7zkhjgzvyim8n1kpa9lys0uqdszxzs0pa0l\""
                },
                {
                    "method": "FILE"
                }
            ],
            "algorithm": "RSA",
            "signatureHashAlgorithm": "SHA256"
        }
    ]
}
SP Tab pane
anchor87031
nameXML
Code Block
languagexml
titleRequest
linenumberstrue
collapsetrue
<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>400110</code>
        <certificate_request>
            <plain><![CDATA[----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----]]></plain>
            <product>QUICKSSLPREMIUM</product>
        </certificate_request>
    </task>
</request>
Code Block
languagexml
titleResponse
linenumberstrue
collapsetrue
<response>
    <result>
        <data>
            <certificate_request>
                <plain><![CDATA[-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----]]></plain>
                <name><![CDATA[example.com]]></name>
                <key_size>2048</key_size>
                <country_code>DE</country_code>
                <state><![CDATA[Bayern]]></state>
                <city><![CDATA[Regensburg]]></city>
                <organization><![CDATA[Company GmbH]]></organization>
                <organization_unit>Entwicklung</organization_unit>
                <email>email@example.com</email>
                <product>QUICKSSLPREMIUM</product>
                <authentication>
                    <method>DNS</method>
                    <dns>example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"</dns>
     				<provisioning>1</provisioning>
                </authentication>
                <authentication>
                    <method>FILE</method>
                    <file_name><![CDATA[http://example.com/.well-known/pki-validation/fileauth.txt]]></file_name>
                    <file_content><![CDATA[201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q]]></file_content>
                </authentication>
                <algorithm>RSA</algorithm>
                <signature_hash_algorithm>SHA256</signature_hash_algorithm>
            </certificate_request>
        </data>
        <status>
            <code>S400110</code>
            <text>CSR Key wurde erfolgreich geprüft.</text>
            <type>success</type>
        </status>
    </result>
  <stid>20170407-app1-3562</stid>
</response>

Zertifikat bestellen (Certificate Create)

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

  • Kontakt:  Geben die Kontakt-ID der geforderten Kontakte an. Bei QuickSSLPremium sind dies der administrative Kontakt und der technische.
  • Name: Der Name des Zertifikates
  • Produkt: Der Wert für QuickSSLPremium ist QUICKSSLPREMIUM
  • Authentifizierung: Die generierten Authentifizierungsdaten
  • Laufzeit: Gib eine für das Zertifikat zulässige Laufzeit an. Bei QuickSSLPremium sind dies 12 oder 24 Monaten
  • Software: Wähle APACHESSL oder IIS5 aus
  • CSR: Der zum Zertifikat gehörende CSR

Info

Für die automatische Provisionierung der Zone, also das automatische Anstoßen der Zonen-Aktualisierung, muss sie über AutoDNS verwaltet werden und die Systeme SSL Manager und AutoDNS müssen miteinander verknüpft sein. Siehe Schritt SSLManager mit dem AutoDNS verbinden.

CertificateCreate  Beispiel

SP Tabs group
dispositionhorizontal
SP Tab pane
anchor2286824
nameJSON
Code Block
languagejs
titleRequest
linenumberstrue
collapsetrue
POST /certificate
{
  "adminContact": {
    "id": 100
  },
  "technicalContact": {
    "id": 100
  },
  "name": "example.com",
  "lifetime": {
    "unit": "MONTH",
    "period": 12
  },
  "software": "APACHESSL",
  "csr": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----",
  "product": "QUICKSSLPREMIUM",
  "authentication": {
    "method": "DNS",
    "dns": "example.com.\t\t300\tIN\tTXT\t\"2018092608362142n4sbul8rv8ttv7zkhjgzvyim8n1kpa9lys0uqdszxzs0pa0l\"",
    "provisioning": true
  }
}
Code Block
languagejs
titleResponse
linenumberstrue
collapsetrue
{
    "stid": "20180926-stid",
    "status": {
        "code": "N400101",
        "text": "Zertifikatsauftrag wurde erfolgreich gestartet. ",
        "type": "NOTIFY"
    },
    "object": {
        "type": "Certificate",
        "value": "example.com"
    },
    "data": [
        {
            "id": 123456
        }
    ]
}
SP Tab pane
anchor87031
nameXML
Code Block
languagexml
titleRequest
linenumberstrue
collapsetrue
<request>
    <auth>
        <user>USER</user>
        <password>PASSWORD</password>
        <context>CONTEXT</context>
    </auth>
    <task>
        <code>400101</code>
        <certificate>
            <technical>
                <id>100</id>
            </technical>
            <admin>
                <id>100</id>
            </admin> 
            <name>example.com</name>
            <product>QUICKSSLPREMIUM</product>
            <authentication>
                <method>DNS</method>
                <dns>example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"</dns> 
                <provisioning>1</provisioning>
            </authentication>
            <lifetime>12</lifetime>
            <software>APACHESSL</software> <!-- APACHESSL / IIS5 -->
            <csr><![CDATA[---------BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----]]></csr> <!-- Der CSR KEY -->
        </certificate>
    </task>
</request>
Code Block
languagexml
titleResponse
linenumberstrue
collapsetrue
<response>
  <result>
    <data>
      <certificate_job>
        <job>
          <id>123456</id><!-- Die ID des angelegten Jobs -->
          <status>RUNNING</status><!-- Der Status des angelegten Jobs -->
        </job>
      </certificate_job>
    </data>
    <status>
      <code>N400101</code><!-- Beschreibt den Status des Tasks -->
      <text>Zertifikatsauftrag wurde erfolgreich gestartet. </text>
      <type>notify</type><!-- Beschreibt den Status des Tasks -->
      <object>
        <type>certificate</type>
        <value>example.com</value><!-- Der Name des Zertifikats -->
      </object>
    </status>
  </result>
 <stid>20170407-app1-3762</stid>
</response>

Anchor
Auftragsbenach
Auftragsbenach
Benachrichtigungen erhalten

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

Zertifikats-Daten ermitteln (Certificate Info)

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

CertificatInfo - Beispiel

SP Tabs group
dispositionhorizontal
SP Tab pane
anchor2286824
nameJSON
Code Block
languagejs
titleRequest
linenumberstrue
collapsetrue
GET /certificate/$id
Code Block
languagejs
titleResponse
linenumberstrue
collapsetrue
{
    "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": "example.com",
            "lifetime": {
                "unit": "MONTH",
                "period": 12
            },
            "software": "APACHESSL",
            "csr": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----",
            "server": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----\n",
            "serialNumber": "750C3006B23B90D0F396A3D153EB4C8",
            "product": "QUICKSSLPREMIUM",
            "expire": "2019-09-26T12:00:00.000+0200",
            "authentication": {
                "method": "DNS",
                "dns": "example.com.\t\t300\tIN\tTXT\t\"2018092608362142n4sbul8rv8ttv7zkhjgzvyim8n1kpa9lys0uqdszxzs0pa0l\"",
                "provisioning": true
            },
            "certificateTransparencyPrivacy": "PUBLIC",
            "domain": "example.com"
        }
    ]
}
SP Tab pane
anchor87031
nameXML
Code Block
languagexml
titleRequest
linenumberstrue
collapsetrue
<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>400104</code>
        <certificate>
            <id>100</id>
        </certificate>
    </task>
</request>
Code Block
languagexml
titleResponse
linenumberstrue
collapsetrue
<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>Maximilianstrasse 36000</address>
            <postal_code>93047</postal_code>
            <city>Regensburg</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>Maximilianstrasse 36000</address>
            <postal_code>93047</postal_code>
            <city>Regensburg</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><!-- Der Name des Zertifikats -->
        <lifetime>12</lifetime><!-- Die Laufzeit des Zertifikats -->
        <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><!-- Das Expire Datum des Zertifikats -->
        <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><!-- Die ID des Zertifikats -->
        <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><!-- Der Name des Zertifikats -->
      </object>
    </status>
  </result>
 <stid>20181211-app1-3892</stid>
</response>