OAUTH Authentifikation für die API des CLS Centers

OAUTH Authentifikation für das CLS Center

Die Module des CLS Center besitzen verschiedene REST-APIs. Dabei unterstützen alle eingesetzten APIs den OAUTH Standard für die Authentifikation. Es wurde dabei ein SSO (Single Sign-on) Mechanismus umgesetzt.

Die Nutzerverwaltung ihres CLS Centers ist der User Account Service, kurz UAS. Die notwendigen Zugangsdaten erhalten Sie bei Ihrem CLS Center Hoster.

POC für die Erzeugung des Token

Jedes Modul, welches eine API exportiert bietet einen definierten POC (Point of Contact) für die Erzeugung des Single Sign-on Tokens an. Die notwendige URL ist dementsprechend:

https://KUNDE.aktiver-emt.de/MODUL/oauth/token

Die Parameter der URL müssen entsprechend ersetzt werden. Die Kundeninstanz muss korrekt über den Platzhalter KUNDE addressiert werden. Als MODUL können Sie verschieden Module ansprechen, je nach der API, die Sie verwenden möchten. Wir empfehlen allerdings das Modul clscenter anzusprechen, da dieser Token als einziger alle Sub-Module abdeckt.

Alle Module setzen OAUTH mit Authentifikation über Benutzernamen und Passwort ein. Der daraus entstehende Access-Token kann danach für alle Anfragen verwendet werden. Läuft der Token ab, so kann der übermittelte Refresh-Token für weitere Anfragen verwendet werden. Die Einzelheiten dieses OAUTH Flows entnehmen Sie bitte dem RFC 6749 oder der Dokumentation der Softwarebibliothek, die Sie verwenden.

Das nachfolgende Beispiel soll Sie bei der Implementierung unterstützen. Der Code ist in Python verfasst und nutzt die requests_oauthlib Library.

Sollten Sie umfangreichere Beispiele oder fertige Funktionen wünschen, die Sie in Ihre Software integrieren können, so finden Sie diese auf unseren GitHub Seiten.

# Import legacy login for password flow
from oauthlib.oauth2 import LegacyApplicationClient, TokenExpiredError
from requests_oauthlib import OAuth2Session

client_id   = "python_request"
NUTZER      = "ihr_nutzer"     # Ersetzen Sie diesen Eintrag durch ihren Nutzer
PASSWORT    = "ihr_passwort"   # Ersetzen Sie diesen Eintrag durch ihr Passwort
KUNDE       = "Bitte_ersetzen" # Ersetzen Sie diesen Eintrag durch ihre ID
MODUL       = "clscenter"

# Hilfsfunktion für den Login beim angegebenen Modul
def login(username, password, client_id, endpoint):
  logging.info("Logging into API")
  token_endpoint  =  endpoint + "/oauth/token"
  oauth = OAuth2Session(client=LegacyApplicationClient("Python App"))
  token = oauth.fetch_token(token_url=token_endpoint, username=username, password=password)
  logging.info("Received a new token with scopes: {}".format(token.scope)[:50])
  return token

# Abrufen des Tokens
endpoint = "https://%s.aktiver-emt.de/%s" % (KUNDE, MODUL)
token = login(NUTZER, PASSWORT, client_id, endpoint)

# Sollte der Token auslaufen, muss die passende URL verwendet werden, um diesen zu
# erneuern.
refresh_url = endpoint + "/oauth/refreshToken"

# Abrufen der Nutzinformationen
protected_endpoint = endpoint + "/gateways?api_key=special-key"

# Im Falle eines abgelaufenen Token wird eine Exception geworfen
try:
  client = OAuth2Session(client_id, token=token)
  r = client.get(protected_endpoint)
  #
  # Die Variable r kann nun wie bei python-requests üblich verwendet werden
  #
except TokenExpiredError as e:
  #
  # Sollte der Token abgelaufen sein, so muss der Durchlauf wiederholt werden
  # 
  token = client.refresh_token(refresh_url)