Zugangsdaten: Verwalten von Anmeldeinformation für OAuth 2.0 oder OpenID Connect (Connect 2024)
Der Connect Server verfügt über einen sogenannten Secure Store, d. h. über einen Bereich in der Datenbank, welcher der verschlüsselten Speicherung von Anmeldeinformationen dient. Die Autorisierung bei der Verwendung von OAuth 2.0 bzw. OpenID Connect erfolgt über Tokens, welche im Secure Store abgelegt werden. Darüber hinaus werden bei diesem Szenario in der Regel zusätzliche (langlebige) Tokens für die Erneuerung des (kurzlebigen) Zugriffstokens sowie Verbindungsinformationen für den Erneuerungsprozess benötigt, welche ebenfalls im Secure Store gespeichert werden. Zukünftige Versionen des Connect Servers sollen auch die optionale Auslagerung von Zertifikaten und Passwörtern in den Secure Store unterstützen.
Die Verwaltung der im Secure Store hinterlegten Zugangsdaten erfolgt über die Seite Connection Designer → Zugangsdaten. Hier können neue Zugangsdaten erfasst (bzw. von einem externen Dienst bezogen), bearbeitet und gelöscht werden. Jeder Eintrag im Secure Store besitzt einen eindeutigen Namen, welcher den Eintrag eindeutig identifiziert. Ein Eintrag kann einen oder mehrere der folgenden Datensatztypen enthalten:
Verbindungsinformationen
Zugriffs-Token
Refresh-Token
Passwort (derzeit nicht verwendet)
Zertifikat (derzeit nicht verwendet)
Um gültige Zugangsdaten für einen OAuth 2.0 bzw. OIDC Autorisierungsanbieter zu beziehen, muss zunächst ein Datensatz vom Typ “Verbindungsinformationen” erstellt werden. Mit diesen Informationen kann dann vom Autorisierungsanbieter ein Zugriffs-Token und in der Regel auch ein Refresh-Token für die Erneuerung des Zugriffstokens bezogen werden.
Beziehen von Zugangsdaten für OAuth 2.0 oder OpenID Connect
Um Zugangsdaten von einem OAuth 2.0 oder OpenID Connect Anbieter beziehen zu können, müssen zunächst die entsprechenden Verbindungsinformationen gepflegt werden. Navigieren Sie hierfür zu der Seite Connection Designer → Zugangsdaten und klicken Sie auf die Schaltfläche “Zugangsdaten hinzufügen”. Vergeben Sie im nun angezeigten Fenster einen eindeutigen Namen für den entsprechenden Datensatz im Secure Store.
Nun wird der Editor für einen neuen Secure Store Datensatz angezeigt. Um Zugangsdaten für OAuth 2.0 / OIDC zu erhalten, wählen Sie im Feld Typ den Datensatztyp “OAuth / OpenID Connect” aus. Wählen Sie nun im Feld Autorisierungsanbieter den Anbieter aus, von dem Sie Zugriffsdaten beziehen möchten.
Um die Applikation gegenüber dem Autorisierungsanbieter zu authentifizieren, müssen die Felder Client ID sowie Client Secret mit den vom Autorisierungsanbieter zugewiesenen Daten gefüllt werden. Die Vorgehensweise zum Bezug dieser Daten unterscheidet sich von Anbieter zu Anbieter. Einige Beispiele hierfür finden Sie am Ende dieses Artikels. Sofern der Autorisierungsanbieter mehrere Autorisierungs-Flows unterstützt, muss der zu verwendende Flow im Feld Autorisierungs-Flow ausgewählt werden. Markieren Sie anschließend im Feld Scopes alle Scopes, die für den Zugriff benötigt werden. Beachten Sie hierbei, dass bei einigen Autorisierungsanbietern hier exakt die Scopes ausgewählt werden müssen, die bei der Registrierung der Applikation angegeben wurden. Zum Schluss wird noch die Redirect URI benötigt, d. h. die URI, an welche der Autorisierungsanbieter den Browser nach der anbieterspezifischen Autorisierung weiterleitet. Diese URI muss das Protokoll HTTPS verwenden und vom aktuellen Client aus erreichbar sein. Bei vielen Autorisierungsanbietern muss bei der Registrierung der Applikation diese URI ebenfalls angegeben werden und beide URIs müssen übereinstimmen.
Klicken Sie nach der Pflege dieser Daten auf die Schaltfläche “Speichern”, um die Verbindungsinformationen zu speichern und folgen Sie den Anweisungen im “Abschnitt Erneuern der Zugangsdaten für OAuth 2.0 oder OpenID Connect” um die benötigten Zugriffs-Tokens anzufordern.
Erneuern der Zugangsdaten für OAuth 2.0 oder OpenID Connect
Um neue Zugangsdaten von einem OAuth 2.0 oder OpenID Connect Anbieter zu beziehen, navigieren Sie zur Seite Connection Designer → Zugangsdaten und klicken Sie neben dem gewünschten Eintrag mit Verbindungsinformationen auf die Schaltfläche “Bearbeiten”. Daraufhin wird dir Seite zum Bearbeiten der Verbindungsinformationen angezeigt. Hier können Sie bei Bedarf Anpassungen vornehmen.
Klicken Sie nun auf die Schaltfläche “Speichern”. Es erscheint ein Fenster mit der Frage, ob neue Zugriffs-Tokens angefordert werden sollen.
Klicken Sie auf die Schaltfläche “Ja” um die Anforderung der Zugriffs-Tokens zu starten. Daraufhin öffnet sich ein neues Browserfenster für die Authentifizierung. Der Inhalt dieses Fensters wird vom Autorisierungsanbieter generiert. Folgen Sie den Anweisungen in diesem Fenster, bis es sich von selbst schließt oder bis Sie zum Schließen des Fensters aufgefordert werden. Sollten Sie die Authentifizierung bereits vorgenommen haben, kann es sein, dass sich das Fenster sofort von selbst schießt.
Verwenden der Zugangsdaten für OAuth 2.0 oder OpenID Connect zur Autorisierung
Zu Autorisierung mittels OAuth 2.0 oder OIDC muss in den entsprechenden HTTP-Client die Klasse Http.Client.Handlers.HttpOAuthHandler als Client-Handler eingebunden werden. Der Konstruktor dieser Klasse besitzt nur einen Parameter mit dem Namen “secureStoreItemName“. Dieser muss auf den Namen des Secure Store Datensatzes gesetzt werden, welcher die entsprechenden Verbindungsinformationen und Zugriffs-Token enthält. Es empfiehlt sich, diesen Namen in die Konfiguration der Verbindungsinformationen auszulagern. Das folgende Beispiel zeigt eine typische Definition für einen HTTP-Client mit Autorisierung über OAuth 2.0 bzw. OpenID Connect:
Technische Voraussetzungen die Verwendung von OAuth 2.0 oder OpenID Connect
Bei der Verwendung von OAuth 2.0 muss der Server in der Lage sein, die entsprechenden OAuth Endpunkte über HTTPS zu erreichen. Bitte beachten Sie, dass einige OAuth-Anbieter für den Backchannel eine HTTPS-Verbindung voraussetzen und hierbei oft nur Zertifikate akzeptieren, welche von einer offiziellen Zertifizierungsstelle ausgestellt wurden. Die OAuth Endpunkte des Service-Anbieters sollten für den Connect Server direkt (ohne einen gesonderten Proxy Server) erreichbar sein. Die Verwendung eines auf Betriebssystemebene definierten Standardproxys sollte ebenfalls funktionieren, wurde jedoch nicht explizit getestet.
Die aktuelle Implementierung von OAuth unterstützt folgende Autorisierungs-Flows: Assertion, Authorization Code, Authorization Code mit PKCE und Client Credentials. Die mittlerweile als unsicher geltenden Flows Implicit und Resource Owner Password werden aktuell nicht unterstützt. Ebenfalls nicht unterstützt werden die Autorisierungs-Flows Device Code und Hybrid.
Unterstützt der Autorisierungsanbieter OpenID Connect (OIDC), so kann die Ermittlung der Konfiguration mittels OIDC Discovery erfolgen (sofern vom Anbieter unterstützt). Darüber hinaus werden in diesem Fall die OAuth-Funktionalitäten unterstützt, welche die Basis für OIDC darstellen.
Registrierung von Connect als OAuth 2.0 Client Applikation
Bevor sich der Connect Server bei einem OAuth 2.0 Anbieter eine Autorisierung beantragen kann, muss er dort als Client Applikation registriert werden. Da die URI der Connect Server Installation bei On-Premise-Installationen variiert, kann keine allgemeingültige Registrierung seitens des Softwareherstellers erfolgen.
Azure DevOps
Die Registrierung der App kann über die URI https://app.vsaex.visualstudio.com/app/register erfolgen. Die Basis-URI der Connect Server Installation muss zwingend das Protokoll HTTPS verwenden. Unter “Anwendungswebsite” ist die Basis-URI des Connect Server einzutragen, unter Autorisierungsrückruf-URL die Basis-URI des Connect Server ergänzt um den Pfad /authorization/oauth. Markieren Sie anschließend die benötigten Scopes. Diese können später nur noch angepasst werden, indem die App Registrierung gelöscht und komplett neu angelegt wird. Beachten Sie ebenfalls, dass beim späteren Erzeugen eines Zugriffs-Tokens exakt dieselben Scopes angegeben werden müssen wie bei der Registrierung. Die Anforderung eines Zugriffs-Tokens für einen Teil dieser Scopes wird nicht unterstützt.
Nach dem Registrieren der Client-Applikation wird Client ID sowie Client Secret in den Feldern App ID bzw. Client Secret (nicht App Secret!) angezeigt. Diese Werte werden für die Konfiguration der Verbindung benötigt. Nachträgliche Änderungen an den Einstellungen oder die Löschung der App können über die URI https://app.vsaex.visualstudio.com/me erfolgen.
Wenn REST-APIs einen Fehler zurückgeben, wie z. B. "TF400813: Der Benutzer "<GUID>" ist nicht berechtigt auf diese Ressource zuzugreifen", überprüfen Sie, ob in den Organisationseinstellungen unter https://dev.azure.com/{Ihr-Org-Name}/_settings/organizationPolicy der Zugriff von Drittanbietern mit OAuth erlaubt ist.
Azure Active Directory
Die Registrierung einer App kann im Azure Portal unter Azure Active Directory → App-Registrierungen (https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps) erfolgen. Die Basis-URI der Connect Server Installation muss zwingend das Protokoll HTTPS verwenden. Im Abschnitt “Umleitungs-URI (optional)” wählen Sie bitten den Typ “Web” aus ist und tragen Sie die Basis-URI des Connect Server ergänzt um den Pfad /authorization/oauth ein. Klicken Sie anschließend auf “Registrieren”.
Die Client ID der neu registrierten Applikation finden Sie nun im Feld “Anwendungs-ID (Client)”. Zu Generierung des Client Secrets klicken Sie auf “Ein Zertifikat oder Geheimnis hinzufügen”. Auf der nun angezeigten Seite klicken Sie im Bereich “Geheime Clientschlüssel“ auf die Schaltfläche “Neuer geheimer Clientschlüssel“. Geben Sie nun einen Namen (z. B. “Connect Server”) ein und wählen Sie den Gültigkeitszeitraum des Schlüssels. Klicken Sie anschließend auf “Hinzufügen”, um den Schlüssel zu erzeugen. Nun wird der neue Clientschlüssel in der Tabellenspalte Wert angezeigt. Klicken auf die Schaltfläche rechts dieses Werts, um ihn in die Zwischenablage zu kopieren. Beachten Sie, dass der Schlüssel nur direkt nach der Erzeugung an dieser Stelle angezeigt bzw. kopiert werden kann. Wird zu einem späteren Zeitpunkt der Clientschlüssel benötigt, so muss jeweils ein neuer Schlüssel erzeugt werden. Der Clientschlüssel muss im Connect Server als Client Secret verwendet werden.
Beachten Sie, dass eine Client ID für Azure Active Directory maximal zwei Jahre gültig ist. Spätestens dann muss eine neue Client ID erzeugt werden. Dieses Limit kann nicht verändert werden.
Github
Die Registrierung einer App erfolgt über die URI https://github.com/settings/developers. Wählen Sie den Bereich “OAuth Apps” und klicken Sie auf die Schaltfläche “New OAuth App“.
Geben Sie auf der folgenden Seite die Informationen zu Ihrer Connect Server Installation ein und klicken Sie anschließend auf die Schaltfläche “Register application“:
Auf der nun folgenden Seite wird die Client ID der neu registrierten App angezeigt.
Klicken Sie nun auf “Generate a new client secret” um ein Client Secret zu erzeugen. Sie werden nun aufgefordert Ihre Identität erneut zu bestätigen (z. B. durch Passworteingabe) und anschließend wird das neu generierte Client Secret angezeigt:
Kopieren Sie das Client Secret sofort unter Verwendung des entsprechenden Buttons, da es später nicht mehr angezeigt werden kann.
Die Registrierung einer App erfolgt hier über die Developer Console über die URI https://console.cloud.google.com/projectcreate.
Vergeben Sie hier einen Projektnamen und klicken Sie anschließend auf “Erzeugen”.
Navigieren Sie nun über das Menü am linken Bildschirmrand zu APIs & Services → Enable APIs & services. Nun wird eine Liste der aktuell für ihre App verfügbaren Google-Dienste angezeigt. Über den Menüpunkt “Library” können weitere Google Dienste hinzugefügt und somit verfügbar gemacht werden. Wählen Sie nun den Menüpunkt “Credentials” und klicken Sie anschließend auf die Schaltfläche “Create credentials” am oberen Bildschirmrand. Es erscheint ein Dropdown-Menü:
Wählen Sie hier die Option “OAuth client ID”. Es erscheint folgende Seite:
Wählen Sie hier den Typ “Web Application” aus und vergeben Sie einen Namen für Ihre Applikation. Klicken Sie danach auf “URI hinzufügen” im Bereich “Autorisierte Redirect URIs” und erfassen Sie die Redirect URI ihrer Connect Server Installation. Klicken Sie anschließend auf “Erstellen”. Nun wird ein Fenster mit Client ID und Client Secret Ihrer Applikation angezeigt.
Kopieren Sie diese Informationen, denn Sie können später nicht mehr darauf zugreifen.
Google liefert nur bei der ersten Authentifizierungsanfrage ein Refresh Token mit. Daher ist es wichtig vor der Aktualisierung des Zugrifftokens die Seite https://myaccount.google.com/u/0/permissions aufzurufen und die bestehenden Zugriffsberechtigungen zu entfernen. Daraufhin wird bei der nächsten Authentifizierungsanfrage die Oberfläche für die Bestätigung des Zugriffs erneut angezeigt und anschließend ein neues Refresh-Token generiert.
Jira Cloud (Authorization Code)
Die Registrierung einer App erfolgt hier über die Developer Console über die URI https://developer.atlassian.com/console/myapps. Hier auf den Button Create → OAuth 2.0 integration klicken.
Weitere Schritte nach der Erstellung der App:
Die nötigen Scopes unter Permissions aktivieren.
Unter Authorization die Callback URL eintragen.
Als nächstes muss die Rest-API URI zusammengestellt werden. Die URI sieht wie folgt aus: https://api.atlassian.com/ex/jira/{cloudid}
Die CloudId lässt sich ermitteln, indem ein GET-Request an den Endpunkt https://api.atlassian.com/oauth/token/accessible-resources gesendet wird. Es muss bereits der OAuth-Token im Header (Authorization: Bearer ACCESS_TOKEN) mitgesendet werden. Hier kommen die ganzen Sites zurück. Von einem passenden Eintrag die Id wird dann als CloudId verwendet. In diesem Beispiel wäre es “1324a887-45db-1bf4-1e99-ef0ff456d421". Also somit https://api.atlassian.com/ex/jira/1324a887-45db-1bf4-1e99-ef0ff456d421.
Diese URI ist die Basis für Rest-API Anfragen, wenn OAuth statt Basic Authentication zum Authentifizieren verwendet wird.