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

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.

Übersicht

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>

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": "john.doe@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>
						...
					</certificate>
					<job_id>536396</job_id>
					<status>
						<code>S400101</code>
						<type>success</type>
						<object>
							<type>ssl</type>
							<value>john.doe@example.com</value>
						</object>
					</status>
				</job>
			</message>
		</data>
		<status>
			<code>S0905</code>
			<text>Die Benachrichtigung wurde erfolgreich abgerufen.</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 Auftragsbenachrichtigungen 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": "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>