DokumentationWorkfrontWorkfront-Handbuch

Benutzerdefinierte OAuth 2-Anwendungen Ihres Unternehmens mithilfe des Autorisierungscode-Flusses konfigurieren und verwenden

Last update: Fri Aug 09 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • Themen:

Erstellt für:

  • Entwickler

Um die Integration mit Workfront zu ermöglichen und die Kommunikation Ihrer Client-App mit Workfront im Namen des Benutzers zu ermöglichen, müssen Sie:

  • Erstellen einer OAuth2-Anwendung
  • Drittanbieteranwendung konfigurieren
  • Link zur Autorisierungsseite für Ihre Benutzer
  • Einrichten des Autorisierungscodeflusses: Benutzer melden sich bei der Workfront-Instanz an und stimmen zu, dass sie der Client-Anwendung erlauben, in ihrem Namen eine Verbindung zu Workfront herzustellen. Daher erhalten Sie einen Autorisierungscode, den Sie mit Zugriffs- und Aktualisierungstoken austauschen.
  • Aktualisierungstoken-Fluss einrichten: In diesem Fluss verwenden Sie das Aktualisierungstoken, um ein neues Zugriffstoken zu erhalten, wenn das alte abgelaufen ist.

Erstellen einer OAuth2-Anwendung

Anweisungen zum Erstellen der OAuth2-Anwendung finden Sie unter Erstellen einer OAuth2-Anwendung mit Benutzeranmeldeinformationen (Autorisierungscode-Fluss) in Erstellen von OAuth2-Anwendungen für Workfront-Integrationen .

NOTE
Sie können bis zu zehn OAuth2-Anwendungen gleichzeitig haben.

Ihre Benutzer müssen sich anmelden, um diese Integration in ihrem eigenen Konto zu autorisieren. Die Seite, die sie autorisieren können, hat ein bestimmtes Format, wie hier beschrieben. Verwenden Sie diese Informationen, um die Adresse der Autorisierungsseite für die App zu ermitteln und Ihren Benutzern diese Adresse oder einen Link darauf bereitzustellen.

  • Die vollständige URL der Domäne Ihres Unternehmens. Beispiel:

    code language-none 
    https://myorganization.my.workfront.com

  • client_id: Dies ist die Client-ID, die beim Erstellen der OAuth2-App in Workfront generiert wurde.

  • redirect_uri: Diese URL muss mit der Umleitungs-URL übereinstimmen, die Sie beim Erstellen der OAuth2-App in Workfront eingegeben haben. Ihre Benutzer werden zu dieser Seite weitergeleitet, nachdem sie die App für ihr Konto autorisiert haben.

  • response_type: Dieser Wert muss den Wert code haben.

Die URL für die Autorisierungsseite lautet daher:

https://<URL of your organization's domain>/integrations/oauth2/authorize?client_id=<Your ClientID>&redirect_uri=<Your redirect URL>&response_type=code
NOTE
Es wird empfohlen, eine Schaltfläche oder einen anderen Link zu erstellen, auf den Ihre Benutzer klicken können, um zu dieser Seite weitergeleitet zu werden.

Drittanbieteranwendung konfigurieren

Die Drittanbieteranwendung erfordert möglicherweise eine Konfiguration. Die folgende Tabelle enthält Informationen zu Feldern, die bei der Konfiguration der Drittanbieteranwendung erforderlich sein können.

Autorisierungs-URI

https://<the full URL of your organization's domain>/integrations/oauth2/authorize

Beispiel: https://myorganization.my.workfront.com/integrations/oauth2/authorize

Token-URL

https://<the full URL of your organization's domain>/integrations/oauth2/api/v1/token

Beispiel: https://myorganization.my.workfront.com/integrations/oauth2/api/v1/token

Bereiche
Sie müssen keine Bereiche angeben.

Einrichten des Autorisierungscode-Flusses

Um Ihre Benutzer mit OAuth2 anzumelden, gehen Sie wie folgt vor:

  1. Wenn der Benutzer die Autorisierungsseite öffnet, wird er zur Workfront-Anmeldeseite weitergeleitet, damit er sich bei Workfront anmelden kann. Wenn der Benutzer über eine SSO-Konfiguration verfügt, wird die Anmeldeseite des Identitäts-Providers geöffnet.

    Wenn der Benutzer bereits im selben Browser bei Workfront angemeldet ist oder sich der Benutzer erfolgreich bei Workfront anmeldet, wird der Benutzer zum Bildschirm für die Zustimmung weitergeleitet:

  2. Wenn der Benutzer den Zugriff zulässt, wird die Seite zu "redirect_url"umgeleitet. Die Umleitung muss die folgenden Abfrageparameter enthalten:

  • code: Der Autorisierungscode, der zum Abrufen des Zugriffs-/Aktualisierungstokens erforderlich ist.

  • domain: Die Domäne Ihres Unternehmens. Beispiel: In myorganization.my.workfront.com ist die Domäne myorganization.

  • lane: die Spur der Anfrage. Beispiel: In myorganization.preview.workfront.com ist die Spur preview.

    note important
    IMPORTANT
    Die code ist nur für 2 Minuten gültig. Daher müssen Sie die Aktualisierungs- und Zugriffstoken innerhalb dieser Zeit abrufen.

  1. Wenn Sie über einen Code verfügen, können Sie eine Aktualisierung anfordern und auf Token zugreifen, indem Sie den Code zusammen mit den Anmeldeinformationen der Client-App an den Endpunkt /integrations/oauth2/api/v1/token senden.

    Die vollständige Token-Anforderungs-URL lautet

    code language-none 
    https://<URL of your organization's domain></span>/integrations/oauth2/api/v1/token

    Beispiele: Beispiel für CURL-Aufruf an Token-Endpunkt:

    Beispiel 1

    code language-none 
       curl --location --request POST '**<workfront host>**/integrations/oauth2/api/v1/token' \
   --header 'Authorization: Basic **<base64(client_id:client_secret)>**' \
   --header 'Content-Type: application/json' \
   --data-raw '{
   "code": "**<code>**",
   "grant_type": "**authorization_code**",
   "redirect_uri": "**<redirect_url>**"
   }'

    Beispiel 2

    code language-none 
       curl --location --request POST '**<workfront host>**/integrations/oauth2/api/v1/token' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'grant_type=**authorization_code**' \
   --data-urlencode 'redirect_uri=**<redirect_url>**' \
   --data-urlencode 'code=**<code>**' \
   --data-urlencode 'client_id=**<client_id>**' \
   --data-urlencode 'client_secret=**<client_secret>**'
    note important
    IMPORTANT
    Das Client-Geheimnis wurde bei der Registrierung der App in Workfront generiert. Sie sollten ihn an einem sicheren Ort speichern, da er nicht wiederhergestellt werden kann, wenn er verloren geht.

    Wenn alle übergebenen Parameter korrekt sind, gibt der Token-Endpunkt die folgende Payload zurück:

    code language-none 
    {
   "token_type": "sessionID",
   "access_token": "string", // the value of sessionID
   "refresh_token": "string",
   "expires_in": 0,
   "wid": "string"
}

    Das Zugriffstoken ist mit sessionID identisch und läuft genauso ab wie regulärer sessionID

    note important
    IMPORTANT
    Speichern Sie das Aktualisierungs-Token an einer sicheren Stelle. Sie benötigen es, um ein neues Aktualisierungstoken zu erhalten, wenn das alte abgelaufen ist. Workfront speichert Ihr Aktualisierungstoken nicht.

  2. Wenn Sie jetzt über ein Zugriffstoken verfügen, können Sie API-Aufrufe an Workfront durchführen

    code language-none 
    curl --request GET 'https://<workfront host>/attask/api/v14.0/proj/search \
--header 'sessionID: <access_token>'

Zugriffstoken aktualisieren einrichten

Um das access_token zu aktualisieren, müssen wir erneut einen 'POST'-Aufruf an den Token-Endpunkt durchführen. Diesmal senden wir wie folgt unterschiedliche Formulardaten:

curl --location --request POST '<workfront host>/integrations/oauth2/api/v1/token' \
--header 'Authorization: Basic <base64(client_id:client_secret)>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "grant_type": "refresh_token",
   "refresh_token": "<refresh_token>"
}'

###### OR

curl --location --request POST '<workfront host>/integrations/oauth2/api/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'redirect_uri=<redirect_url>' \
--data-urlencode 'refresh_token=<refresh_token>' \
--data-urlencode 'client_id=<client_id>' \
--data-urlencode 'client_secret=<client_secret>'

Es wird das folgende Ergebnis zurückgegeben:

{
  "token_type": "sessionID",
  "access_token": "string", // the value of sessionID
  "refresh_token": "string",
  "expires_in": 0,
  "wid": "string"
}

Und auch das Zugriffstoken ist der sessionID , der verwendet werden kann, um eine API-Anfrage an Workfront zu richten.

recommendation-more-help
5f00cc6b-2202-40d6-bcd0-3ee0c2316b43