Suche in diesem Bereich

Skip to end of metadata
Go to start of metadata

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

Übersicht

Ablaufdiagramm

Auftragstypen-Codes, Namen und Routen

AuftragstypTaskcodeRoute
CertificateCreate400101POST /certificate
ContactCreate400201POST /sslcontact
CertificateInfo400104GET /certificate/$id
PollInfo0905GET /poll
PollConfirm0906PUT /poll/$id
CertificatePrepareOrder
400110
POST /certiicate/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 eigentliche 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. Aktuell stehen bei S/MIME-Zertifikaten 12 oder 36 Monate zur Auswahl.
  • 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

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@testexample.com]]></name>
            <approver_email><![CDATA[max.mustermann@testexample.com]]></approver_email>
            <password>****</password>
            <firstname>Max</firstname>
            <lastname>Mustermann</lastname>
            <organization_unit_name>Entwicklung</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@testexample.com</value>
      </object>
    </status>
  </result>
</response>

Auftragsbenachrichtigungen abfragen und bestätigen

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. Diese kannst du über den Auftragstyp PollInfo abfragen.

War der Auftrag erfolgreich, so erhälst du unter anderem die ID des bestellten Zertifikates. Abschließend musst du den Auftrag mit PollConfirm bestätigen.

PollInfo - Beispiel

Request
GET /poll
Response
{
    "stid": "20180926-stid",
    "status": {
        "code": "S0905",
        "text": "Die Benachrichtigung wurde erfolgreich abgerufen.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "message",
        "value": "1819853"
    },
    "data": [
        {
            "summary": 2,
            "message": {
                "id": 1819853,
                "job": {
                    "id": 4295609712,
                    "certificate": {
                        "id": 13258,
                        "orderId": "2695961",
						...
                    }
                },
                "stid": "20180926-stid",
                "object": {
                    "type": "ssl",
                    "value": "example.com"
                },
                "status": {
                    "code": "S400101",
                    "type": "SUCCESS"
                }
            }
        }
    ]
}
Request
<request>
	<auth>
		<user>USER</user>
		<context>CONTEXT</context>
		<password>PASSWORD</password>
	</auth>
	<task>
		<code>0905</code>
	</task>
</request>
Response
<response>
	<result>
		<data>
			<summary>1</summary>
			<message>
				<id>650664</id><!-- Die ID der PollMessage -->
				<owner>
					<user>USER</user>
					<context>CONTEXT</context>
				</owner>
				<job>
					<certificate>
						...						
						<id>1485</id><!-- Die ID des Zertifikats -->
						...
					</certificate>
					<job_id>536396</job_id><!-- Die ID des Jobs -->
					<status>
						<code>S400101</code><!-- Zeigt an ob der Task CertifikateCreate erfolgreich war oder nicht -->
						<type>success</type><!-- Zeigt an ob der Task CertifikateCreate erfolgreich war oder nicht -->
						<object>
							<type>ssl</type>
							<value>example.com</value><!-- Der Name des Zertifikats -->
						</object>
					</status>
				</job>
			</message>
		</data>
		<status>
			<code>S0905</code>
			<text>The notification was polled successfully.</text>
			<type>success</type>
			<object>
				<type>message</type>
				<value>650664</value>
			</object>
		</status>
	</result>
</response>

PollConfirm - Beispiel

Request
PUT /poll/{id}
Response
{
    "stid": "20180926-stid",
    "status": {
        "code": "S0906",
        "text": "Die Benachrichtigung wurde erfolgreich bestätigt.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "message",
        "value": "1819853"
    }
}
Request
<request>
	<auth>
		<user>USER</user>
		<context>CONTEXT</context>
		<password>PASSWORD</password>
	</auth>
	<task>
		<code>0906</code>
    	<message>
			<id>650664</id>
		</message>
    </task>
</request>
Response
<response>
    <result>
        <data>
            <summary>0</summary>
            <message>
                <id>650664</id>
            </message>
        </data>
        <status>
            <code>S0906</code>
            <text>Die Benachrichtigung wurde erfolgreich bestätigt.</text>
            <type>success</type>
            <object>
                <type>message</type>
                <value>650664</value>
            </object>
        </status>
    </result>
</response>

Zertifikats-Daten ermitteln

Der Auftragstyp CertificateInfo ermittelt alle Zertifikatsdaten. Die Daten können mit Hilfe der ID aus dem Schritt Pollmessages abfragen und bestätigen 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": "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"
        }
    ]
}
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>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>
</response>