de:dfnpki:tcs:restapi [Dokumentation DFN-AAI, DFN-PKI und eduroam]

Diese Seite ist nicht editierbar. Sie können den Quelltext sehen, jedoch nicht verändern. Kontaktieren Sie den Administrator, wenn Sie glauben, dass hier ein Fehler vorliegt.
=====Sectigo REST-API=====


Die Systeme von Sectigo können per REST-API angesprochen werden. Es gibt zur Zeit (2024-05) **zwei** Versionen der API.

1. Eine ältere API mit Endpunkten unter https://cert-manager.com/
   * Authentifizierung per Username/Passwort eines RAO oder DRAO-Accounts im HTTP-Header
   * Dokumentation unter https://sectigo.com/knowledge-base/detail/Sectigo-Certificate-Manager-SCM-REST-API/kA01N000000XDkE

2. Eine neuere API mit Endpunkten unter https://admin.enterprise.sectigo.com/
   * Authentifizierung per OAUTH2 Client Credentials Grants
   * Anknüpfungspunkt in SCM sind spezielle RAO- und DRAO-Accounts vom Typ "API"
   * OAuth2 Client-ID und Client-Secret können in SCM erzeugt werden über ☰->Settings->Admins, Account vom Typ "API" auswählen und dann Button "API-Keys"
   * JSON-Dokumentation nach dem OpenAPI-Standard unter https://admin.enterprise.sectigo.com/api/v3/api-docs
  


Das REST-API kann nur dann zum Enrollment verwendet werden, wenn unter ☰->Organizations-><Auswahl> per Button Edit im Tab "Certificate Settings" in den Abschnitten "SSL Certificates" bzw. "Client Certificates" die Checkbox "Enable Web / REST API" angekreuzt ist.


=== Beispiele für REST API Typ 1 ===

Es ist ein Login/Passwort eines im Cert-Manager angelegten Accounts zu übergeben. Sofern dieser Account ein "Standard"-Account ist, muss dessen 
Anfangspasswort bereits geändert worden sein, bevor dieser Account zum Zugriff auf das REST-API verwendet werden kann. Accounts vom Typ "API" funktionieren ausschließlich für den Zugriff mittels REST-API und bedürfen keiner initialen Passwortänderung. Die in der Dokumentation angegebene Client-Authentifizierung per Zertifikat für das REST-API ist noch nicht getestet.

Tipp: Man kann einen Account in seiner Rolle so einschränken, dass ausschließlich der REST-API-Zugang verwendet werden kann, siehe [[de:dfnpki:tcsfaq#admins_rollen_privilegien|Admins, Rollen & Privilegien]]

Beispiel für die Beantragung von **Serverzertifikaten**:

<code>curl 'https://cert-manager.com/api/ssl/v1/enroll' -i -X POST \
    -H "Content-Type: application/json;charset=utf-8" \
    -H "login: <account>" \
    -H "password: <passwort>" \
    -H "customerUri: DFN" \
    -d '{"orgId":<OrgId>,"subjAltNames":"<FQDN des Servers>","certType":<Nummer des Zertifikatprofils>,"numberServers":0,"serverType":-1,"term":365,"comments":"","externalRequester":"","customFields": [],"csr":"-----BEGIN CERTIFICATE REQUEST-----\nMIICYjCCAU...N818=\n-----END CERTIFICATE REQUEST-----"}'</code>

Die <OrgId> (ID) ist direkt im cert-manager.com ablesbar: ☰->Organizations-><Organisationsauswahl>->Button Edit. Für DRAO-Accounts muss auf Department-Ebene die <OrgId> (ID) entsprechend vom zugehörigen Departement des DRAO-Accounts hergenommen werden: ☰->Organizations-><Organisationsauswahl>->Button Edit-><Department-Auswahl>->Button Edit.

Die <Nummer des Zertifikatprofils> muss einmalig mit folgendem Aufruf ermittelt werden:

<code>curl 'https://cert-manager.com/api/ssl/v1/types' -i -X GET \
    -H "Content-Type: application/json;charset=utf-8" \
    -H "login: <account>" \
    -H "password: <passwort>" \
    -H "customerUri: DFN" \</code>

Ausgestellte Zertifikate können mit folgendem Aufruf abgeholt werden:

<code>curl  'https://cert-manager.com/api/ssl/v1/collect/<Antragsnummer>/<Format>' -i -X GET \
    -H "Content-Type: application/json;charset=utf-8" \
    -H "login: <account>" \
    -H "password: <passwort>" \
    -H "customerUri: DFN" \</code>

<Antragsnummer> wurde bei einem vorherigen Aufruf von ...enroll als Rückgabewert zurückgeliefert.

<Format> spezifiziert das Rückgabeformat, z.B. "pem", weitere mögliche Werte siehe https://sectigo.com/knowledge-base/detail/SCM-Sectigo-Certificate-Manager-REST-API/kA01N000000XDkE

Für **Nutzerzertifikate** ist die Beantragung ähnlich aufgebaut. Die Aufrufe müssen an ''https://cert-manager.com/api/smime/v1/types'', ''.../smime/v1/enroll'' und ''.../smime/v1/collect/...'' geschickt werden. Für weitere Details zu den Parametern ist die API-Dokumentation von Sectigo heranzuziehen.

Beispielaufruf zur Beantragung eines Nutzerzertifikats: 

<code>curl 'https://cert-manager.com/api/smime/v1/enroll' -i -X POST \
    -H "Content-Type: application/json;charset=utf-8" \
    -H "login: <account>" \
    -H "password: <passwort>" \
    -H "customerUri: DFN" \
    -d '{ "orgId":<OrgId>, "certType":<Nummer des Zertifikatprofils z.B. 21247>,\  
          "email":"<e-mail-adresse>",\
          "firstName":"<vorname>", "lastName":"<nachname>",\
          "term":<Gültigkeit in Tagen, je Nach Zertifikatprofil entweder 365 oder 730>,\
          ...,\
          "csr":"-----BEGIN CERTIFICATE REQUEST-----\nMIICYjCCAU...N818=\n-----END CERTIFICATE REQUEST-----"}</code>


=== Beispiele für REST API Typ 2 ===

Für die modernere Variante des APIs sind Aufrufe mittels ''curl'' wegen der OAUTH2-Authentifizierung etwas unhandlich. Ein kleines Beispiel in Python, mit dem die angelegten Personen in SCM aufgelistet werden:

<code>
import urllib.request
from oauthlib.oauth2 import BackendApplicationClient
from requests_oauthlib import OAuth2Session

# clientid und clientsecret über den Button "API-Keys" zu einem Admin-User im SCM erzeugt
clientid=<XYZ>
clientsecret=<XYZ>

token_url='https://auth.sso.sectigo.com/auth/realms/apiclients/protocol/openid-connect/token'
client = BackendApplicationClient(client_id=clientid)
oauth = OAuth2Session(client=client)

token = oauth.fetch_token(token_url='https://auth.sso.sectigo.com/auth/realms/apiclients/protocol/openid-connect/token',
                client_id=clientid, client_secret=clientsecret)

headers = {'Authorization': 'Bearer %s' % token.get('access_token')}

resp = requests.get('https://admin.enterprise.sectigo.com/api/person/v2/', headers=headers)
print(resp.headers)
print(resp.json()) 
</code>