OAuth2 Authentifizierung für die timr REST API

Überblick

Integrationen, welche die timr REST API aufrufen, authentifizieren sich über OAuth2. Statt Benutzername und Passwort einer timr-Nutzerin oder eines timr-Nutzers zu verwenden, erhält eine Anwendung ein Access Token vom timr-Authorization-Server und sendet dieses Token bei jedem API-Aufruf mit. timr unterstützt zwei Grant-Type-Konfigurationen — Client Credentials für Maschine-zu-Maschine-Integrationen ohne Benutzeranmeldung und Authorization Code mit Refresh Token für Integrationen, die im Namen einer einzelnen angemeldeten timr-Nutzerin oder eines timr-Nutzers handeln. Dieser Artikel erklärt die OAuth-Grundlagen, das Anlegen von API-Zugangsdaten in timr sowie das Anfordern und Verwenden von Access Tokens für beide Flows. Er richtet sich an Administratorinnen und Administratoren sowie Entwicklerinnen und Entwickler, die Integrationen für die timr API erstellen.
 

1. Voraussetzungen

2. OAuth-Grundlagen

3. Den richtigen Grant-Type wählen

4. OAuth-Endpoints

5. API-Zugangsdaten in timr anlegen

6. Client Credentials Flow

7. Authorization Code Flow mit Refresh Token

8. Das Access Token verwenden

9. Häufige Fragen

1. Voraussetzungen

• Zum Anlegen von API-Zugangsdaten benötigen Sie Administrator-Rechte in timr.
• Legen Sie vor dem Start fest, welchen Grant-Type Ihre Integration benötigt (siehe Abschnitt 3).
• Für den Authorization Code Flow benötigen Sie mindestens eine absolute Redirect-URL, die Ihre Anwendung kontrolliert.
   

2. OAuth-Grundlagen

OAuth ermöglicht kontrollierten Zugriff auf geschützte Ressourcen, ohne Passwörter an Drittanbieter-Anwendungen weiterzugeben. Es gelten die folgenden formalen Rollen:

• Resource Owner: die Instanz, die den Zugriff auf geschützte Ressourcen gewährt. Je nach Flow ist das der timr-Client oder eine einzelne timr-Nutzerin bzw. ein einzelner timr-Nutzer.
• Resource Server: die Instanz, die die geschützten Ressourcen bereitstellt. In timr ist das die timr API.
• OAuth Client: die Anwendung, die Zugriff auf geschützte Ressourcen anfordert.
• Authorization Server: die Instanz, die den Resource Owner authentifiziert, die Autorisierung einholt und Tokens an den OAuth Client ausgibt.
   

3. Den richtigen Grant-Type wählen

timr unterstützt zwei Grant-Type-Konfigurationen. Wählen Sie die für Ihre Integration passende aus:

• Client Credentials — Für Maschine-zu-Maschine-Integrationen, bei denen sich keine einzelne timr-Nutzerin und kein einzelner timr-Nutzer anmeldet. Das Access Token wird für den timr-Client ausgestellt und gewährt API-Zugriff im Client-Kontext. Es kann daher gemäß den mit client_credentials verknüpften API-Berechtigungen auf Daten über mehrere Benutzer hinweg zugreifen.
• Authorization Code mit Refresh Token — Wenn die Integration im Namen einer einzelnen timr-Nutzerin oder eines timr-Nutzers handelt, die bzw. der sich explizit anmeldet. Das Access Token wird im Kontext dieses authentifizierten Benutzers ausgestellt und ist auf dessen Berechtigungen beschränkt. Es gewährt keinen mandantenweiten Client-Zugriff.
   

4. OAuth-Endpoints

Der OpenID-Discovery-Endpoint liefert die relevanten OAuth-Endpoints des timr-Authorization-Servers:

https://system.timr.com/id/.well-known/openid-configuration

Verwenden Sie das Discovery-Dokument, um den aktuellen Authorization-Endpoint und Token-Endpoint nachzuschlagen. Für das produktive timr werden üblicherweise folgende Endpoints verwendet:

• Authorization-Endpoint: https://system.timr.com/id/oauth2/authorize
• Token-Endpoint: https://system.timr.com/id/oauth2/token
• API-Basis-URL: https://api.timr.com/v1
   

5. API-Zugangsdaten in timr anlegen

Gehen Sie wie folgt vor, um einen neuen OAuth Client anzulegen:

1. Öffnen Sie timr in der Webanwendung und navigieren Sie zu Verwaltung → Einstellungen → Integrationen.
2. Klicken Sie bei "API Zugriffsdaten" auf "+ Hinzufügen". 
3. Vergeben Sie einen Namen und wählen Sie den Grant-Type für den Client aus.
4. Speichern Sie den Client.

Nach dem Anlegen des OAuth Clients zeigt timr die OAuth Client ID und das OAuth Client Secret an.

Hinweis: Bewahren Sie das Client Secret sicher auf. Es wird zum Anfordern von Tokens benötigt und wird nur in der Administrationsoberfläche angezeigt.

6. Client Credentials Flow

Verwenden Sie den Client Credentials Flow für Maschine-zu-Maschine-Integrationen ohne Benutzeranmeldung. Client-Credentials-Clients verwenden die Scopes openid timrclient.

Senden Sie zum Anfordern eines Tokens eine POST-Anfrage an den Token-Endpoint mit dem Header Content-Type: application/x-www-form-urlencoded:

POST /id/oauth2/token HTTP/1.1
Host: system.timr.com
Content-Type: application/x-www-form-urlencoded

client_id=<OAuth Client ID>&client_secret=<OAuth Client Secret>&grant_type=client_credentials&scope=openid timrclient

Eine erfolgreiche Antwort hat den Status 200 OK und enthält ein Access Token:

{
    "access_token": "<access_token>",
    "scope": "openid timrclient",
    "token_type": "Bearer",
    "expires_in": 3599
}

Hinweis: Der Client Credentials Flow gibt kein Refresh Token zurück. Fordern Sie nach Ablauf des Access Tokens mit derselben Anfrage ein neues Access Token an.
 

7. Authorization Code Flow mit Refresh Token

Verwenden Sie den Authorization Code Flow, wenn die Integration im Namen einer einzelnen timr-Nutzerin oder eines timr-Nutzers handelt. Der Benutzer meldet sich am timr-Authorization-Server an, und das Access Token wird im Kontext dieses authentifizierten Benutzers ausgestellt. Authorization-Code-Clients verwenden die Scopes openid offline_access. Der Scope offline_access ermöglicht es dem Authorization-Server, zusammen mit dem Access Token ein Refresh Token auszustellen.
 

7.1 Redirect-URLs konfigurieren

Authorization-Code-Clients benötigen mindestens eine erlaubte Redirect-URL. Konfigurieren Sie die Redirect-URLs beim Anlegen oder Bearbeiten des OAuth Clients in der timr-Administrationsoberfläche. Redirect-URLs müssen absolute URLs sein und dürfen kein Fragment enthalten. Konfigurieren Sie eine URL pro Zeile.

Gültige Beispiele:

https://example.com/oauth/timr/callback
https://app.example.com/integrations/timr/callback

Ungültige Beispiele:

/oauth/timr/callback
https://example.com/oauth/timr/callback#fragment

Hinweis: Die in der Authorization-Anfrage und in der Token-Anfrage verwendete redirect_uri muss exakt mit einer der konfigurierten Redirect-URLs übereinstimmen.
 

7.2 Autorisierung und Tokens anfordern

Schritt 1: Den Benutzer zum Authorization-Endpoint weiterleiten

Öffnen Sie den Authorization-Endpoint im Browser des Benutzers:

GET /id/oauth2/authorize?response_type=code&client_id=<OAuth_Client_ID>&redirect_uri=<Redirect_URL>&scope=openid%20offline_access&state=<State> HTTP/1.1
Host: system.timr.com

Parameter:

• response_type — Muss code sein.
• client_id — Die OAuth Client ID aus der timr-Administrationsoberfläche.
• redirect_uri — Eine der konfigurierten Redirect-URLs.
• scope — Verwenden Sie openid offline_access.
• state — Ein von Ihrer Anwendung erzeugter Zufallswert. Speichern Sie ihn vor der Weiterleitung und prüfen Sie ihn, wenn der Benutzer zurückkehrt.

Nach der Anmeldung leitet timr den Browser zurück zur konfigurierten Redirect-URL:

https://example.com/oauth/timr/callback?code=<Authorization Code>&state=<State>

Prüfen Sie, dass der zurückgegebene state-Wert mit dem von Ihrer Anwendung erzeugten Wert übereinstimmt.

Schritt 2: Den Authorization Code gegen Tokens eintauschen

Senden Sie eine POST-Anfrage an den Token-Endpoint mit dem Header Content-Type: application/x-www-form-urlencoded:

POST /id/oauth2/token HTTP/1.1
Host: system.timr.com
Content-Type: application/x-www-form-urlencoded

client_id=<OAuth Client ID>&client_secret=<OAuth Client Secret>&grant_type=authorization_code&code=<Authorization Code>&redirect_uri=<Redirect URL>

Eine erfolgreiche Antwort hat den Status 200 OK und enthält ein Access Token und ein Refresh Token:

{
    "access_token": "<access token>",
    "refresh_token": "<refresh token>",
    "scope": "openid offline_access",
    "token_type": "Bearer",
    "expires_in": 3599
}

Schritt 3: Das Access Token erneuern

Senden Sie nach Ablauf des Access Tokens eine Refresh-Token-Anfrage:

POST /id/oauth2/token HTTP/1.1
Host: system.timr.com
Content-Type: application/x-www-form-urlencoded

client_id=<OAuth_Client_ID>&client_secret=<OAuth_Client_Secret>&grant_type=refresh_token&refresh_token=<Refresh Token>

Eine erfolgreiche Antwort liefert ein neues Access Token:

{
    "access_token": "<access token>",
    "refresh_token": "<refresh token>",
    "scope": "openid offline_access",
    "token_type": "Bearer",
    "expires_in": 3599
}

Hinweis: Wenn die Antwort ein neues Refresh Token enthält, ersetzen Sie das zuvor gespeicherte Refresh Token durch das neue.
 

8. Das Access Token verwenden

Senden Sie das Access Token bei Aufrufen der timr API als Bearer-Token im Authorization-Header:

GET /v1/<resource> HTTP/1.1
Host: api.timr.com
Authorization: Bearer <access_token>

9. Häufige Fragen

Welchen Grant-Type sollte ich verwenden? 
Verwenden Sie client_credentials, wenn Ihre Integration ein Backend-Dienst ist und ohne Benutzeranmeldung im Client-Kontext auf timr zugreifen soll. Verwenden Sie authorization_code mit Refresh Token, wenn sich ein Benutzer explizit anmeldet und die Integration mit dessen Berechtigungen auf timr zugreifen soll.

Warum habe ich kein Refresh Token erhalten? 
Der Client Credentials Flow gibt kein Refresh Token zurück. Fordern Sie nach Ablauf mit derselben Token-Anfrage ein neues Access Token an. Refresh Tokens werden nur im Authorization Code Flow ausgestellt, und nur wenn der Scope offline_access enthalten ist.

Welche Berechtigungen gewährt ein Access Token? 
Ein Token aus dem Client Credentials Flow gewährt API-Zugriff im Client-Kontext gemäß den mit client_credentials verknüpften API-Berechtigungen. Ein Token aus dem Authorization Code Flow ist auf die Berechtigungen des authentifizierten timr-Benutzers beschränkt.

Warum wird meine Authorization-Anfrage abgelehnt? 
Prüfen Sie, dass die redirect_uri in der Anfrage exakt mit einer der für den OAuth Client konfigurierten Redirect-URLs übereinstimmt, dass die URL absolut ist und kein Fragment enthält.
 

Weiterführende Informationen

• What Is OAuth? A Breakdown for Beginners | Nordic APIs
• What is OAuth 2.0 and what does it do for you? | Auth0
• RFC 6749: The OAuth 2.0 Authorization Framework