Kapitel 2

API Nutzung

OAuth 2.0 ist ein offener Standard zur sicheren Autorisierung von Zugriffen auf geschützte Ressourcen. Er ermöglicht es Anwendungen, im Namen eines Nutzers auf Daten oder Dienste zuzugreifen, ohne dass Benutzername und Passwort weitergegeben werden müssen.

Stattdessen erhält die Anwendung zeitlich und inhaltlich begrenzte Access Tokens, die genau festlegen, was sie darf und wie lange. OAuth 2.0 trennt dabei klar die Rollen von Benutzer, Client-Anwendung, Autorisierungsserver und Ressourcendienst und sorgt so für mehr Sicherheit, Flexibilität und Kontrolle.

Vorbedingungen

Bevor OAuth 2.0 genutzt werden kann, muss die Anwendung beim Autorisierungsserver registriert werden. Dabei erhält der Client eine Client-ID zur eindeutigen Identifikation sowie ein Client-Secret, das zur Authentifizierung der Anwendung dient. Zusätzlich wird ein Scope definiert, der festlegt, auf welche Ressourcen und Funktionen die Anwendung zugreifen darf. Diese Angaben sind notwendig, um den Autorisierungsvorgang sicher und kontrolliert durchführen zu können.

Für jede Umgebung – Sandbox, Testing und Produktion – müssen separate Client-IDs und Access Token angefordert werden. Die Umgebungen sind technisch und sicherheitsseitig voneinander getrennt, sodass Zugangsdaten und Tokens nicht environment-übergreifend verwendet werden dürfen. Dadurch wird sichergestellt, dass Tests keinen Einfluss auf Produktivdaten haben und jede Umgebung klar abgegrenzt und kontrolliert genutzt werden kann.

Sie erhalten die notwendigen Client-ID und das Secret über das Kundenportal.

Access Token anfordern

Voraussetzend, dass Sie Client-ID und Secret über das Portal angefordert und erhalten haben, können Sie nun das Access Token anfragen. Folgend können Sie den entsprechenden curl-Befehl beispielhaft sehen. In Realität sollten Sie natürlich die Technologie nutzen, die Ihre IT-Anwendung verwendet.

# Beispiel zur Erzeugung eines Access Tokens für die Testing-Umgebung
curl  -X POST https://hydra.nxtlabs.online/oauth2/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=client_credentials" \
      -d "scope=thg-testing" \
      -u a43e4908-5839-4421-aa81-76672c85b400:S~MddeCBr~U1aPxWOC4s0~HSQY
# Analog für Sandbox (thg-sandbox) und Produktion (thg-production)

Antwort

{"access_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6ImJlNWY4YzcwLTQ4ZjMtNGU1NS1iMDZkLThjYzRjMmU3YWFjNiIsInR5cCI6IkpXVCJ9.eyJhdWQiOltdLCJjbGllbnRfaWQiOiJhNDNlNDkwOC01ODM5LTQ0MjEtYWE4MS03NjY3MmM4NWI0MDAiLCJleHAiOjE3NzA3MTYyMzYsImV4dCI6e30sImlhdCI6MTc3MDYyOTgzNiwiaXNzIjoiaHR0cHM6Ly9oeWRyYS5ueHRsYWJzLm9ubGluZSIsImp0aSI6IjAzYTNmNzkyLWE5YjUtNGYzOS1hYWM2LWQ4ZTVkYzg4Zjg5ZCIsIm5iZiI6MTc3MDYyOTgzNiwic2NwIjpbInRoZy10ZXN0aW5nIl0sInN1YiI6ImE0M2U0OTA4LTU4MzktNDQyMS1hYTgxLTc2NjcyYzg1YjQwMCJ9.H_ntZDn5-JO6rmqJPh-Y67vTL1Ejq8Dhg0aPn4x4wfX0_HC26bjRjXz0XYr14N66eaaJd3pT8Ujj9UEOaR1ZLYYw5rTX5qp1im_VztthhVWbuePw1nbj0ZCsBs-RSrMRf-qYLiCC76UstVargie2LW5OcwIiofzb3guJ1TCTruJZ15Tz8V9RUy-T-JeR3YCZVY4k___2ACGfx4vdiEVO-Qkkk1gckQN4pnXg3YC4Wu3Fp6eDLnS-2n27lSg9ESzK7iBE73XjgCXzxIDRXhMy-w_2-oYzJD4EkapkPtNmhIzKli5dtFbhxEalexWB4-M17YueCy8rgZDgsRPlgBN9hHA--jt5pIw3an1TgIo2u9dmawHm6W871F5JjtP7HCDoYLFNXOAMnWSp0pj4ku8BX5lD68AF0UGx5q-Fs6vDhygkpErzflk_kZCavSofRrh4TJQt9JkayW2T1Zi6Xqt5okpDc6iU5VzO-gCgvrci0pkb1Xto8wThrq0zumMtBgzZtcllxdO_IiKDs_7Gb9I3cv7_gGUYiOyoD_BRCHTM9QUfv_qCXA8Vdnp6VF4YXDh9TGVvbui63QWnmTr_GIJFNRV8lq_lHBgCgbaXivXT27EAvJ_InFyk4FNNBPsH4yAJ22pck4ct3tFiJPlm28979N9YRcz2vdULFr0Qae_XhZA",
  "expires_in":86399,"scope":"thg-testing","token_type":"bearer"}

Hinweise:

  • Die oben zu sehende Antwort ist nur ein Beispiel für ein Access Token. Die Antwort ihrer Anfrage sieht selbstverständlich anders aus, ist aber dennoch ein gültiges JSON Web Token (JWT).
  • Das Access Token ist nur für eine begrenzte Zeit gültig und muss daher regelmäßig (täglich) über die oben beschriebene Routine erneuert werden.
  • Den Inhalt des erzeugten Access Tokens kann man sich bei Bedarf auch anschauen, z.B. mithilfe der Webseite JWT IO.
// Beispiel: Decodiertes Access Token
{
  "aud": [],
  "client_id": "a43e4908-5839-4421-aa81-76672c85b400",
  "exp": 1770716236,
  "ext": {},
  "iat": 1770629836,
  "iss": "https://hydra.nxtlabs.online",
  "jti": "03a3f792-a9b5-4f39-aac6-d8e5dc88f89d",
  "nbf": 1770629836,
  "scp": [
    "thg-testing"
  ],
  "sub": "a43e4908-5839-4421-aa81-76672c85b400"
}

Hinweis: Den JSON Web Key Set (JWKS) erhalten Sie unter https://hydra.nxtlabs.online/.well-known/jwks.json. Damit können Sie das erzeugte Access Token (JWT) selbst verifizieren.

Anfrage stellen

Mit dem zurückgegebenen Access Token können nun Anfragen gegen die API gestellt werden, indem das Token (also die Zeichenkette im Feld “access_token” ) im Authorization Header als Bearer Token mitgegeben werden.

Beispielhaft sehen Sie eine Anfrage an den Endpunkt /api/v1/whoami.

curl  -v https://thg.nxtlabs.online/api/v1/whoami \
      -H Authorization: Bearer <access_token>
# Setzen Sie das für Sie erzeugte Access Token anstelle von <access_token> in die Anfrage ein.

Antwort

{"identity":"b2466469-825f-4233-9122-c585d163daed","roles":"user,thg-testing,oauth2"}

Analog verfahren Sie bitte mit den anderen Endpunkten wie in der API-Dokumentation beschrieben.