️ Zurück

Autorisierung von OAuth-Apps

Sie können anderen Benutzern ermöglichen, sich mit Ihre OAuth App zu autorisieren.

Die OAuth-Implementierung von Homeworker unterstützt den Standard "Authorization Code Grant".

Wenn Sie die Autorisierung Ihrer Anwendung auf dem Standardweg überspringen möchten, z. B. beim Testen Ihrer Anwendung, können Sie den nicht webbasierten Anwendungsfluss verwenden.

Authorisierungsfluss in Web-Anwendungen

Der Webanwendungsfluss zur Autorisierung von Benutzern für Ihre Anwendung ist:

Benutzer werden zur Abfrage ihrer Homeworker-Identität weitergeleitet
Benutzer werden von Homeworker auf ihre Anwendung zurückgeleitet
Ihre Anwendung greift auf die API mit dem Access-Tokens des Benutzers zu

1. Anfordern der Homeworker-Identität eines Benutzers

GET https://homeworker.li/auth/oauth2/authorize

Parameter

Name	Type	Description
`client_id`	`string`	Erforderlich. Die Client-ID, die Sie bei der Registrierung von Homeworker erhalten haben.
`redirect_uri`	`string`	Die URL in Ihrer Anwendung, an die Benutzer nach der Autorisierung gesendet werden. Siehe Einzelheiten zu Weiterleitungs URLs weiter unten.
`scopes`	`string`	Eine durch leerzeichen getrennte Liste von Scopes. Wenn nicht angegeben, wird für Benutzer, die keine Scopes für die Anwendung autorisiert haben, standardmäßig eine leere Liste angezeigt. Der Benutzer wird bei jeder Anmeldung auf die Verwendung der Scopes hingewießen.
`state`	`string`	Eine unberechenbare zufällige Zeichenfolge. Sie wird zum Schutz gegen Cross-Site-Request-Forgery Angeriffen verwendet.

2. Benutzer werden von Homeworker zurück auf Ihre Website umgeleitet

Wenn der Benutzer Ihre Anfrage akzeptiert, leitet Homeworker mit einem temporären Code in einem Code-Parameter sowie mit dem Status, den Sie im vorherigen Schritt in einem Status-Parameter angegeben haben, zu Ihrer Website zurück. Der temporäre Code läuft nach 10 Minuten ab. Wenn die Zustände nicht übereinstimmen, dann hat eine dritte Partei die Anfrage erstellt, und Sie sollten den Vorgang abbrechen.

Tauschen Sie diesen code gegen ein Access-Token aus:

POST https://homeworker.li/api/v2/oauth2/token

Parameter

Name	Type	Description
`client_id`	`string`	Erforderlich. Die Client-ID, die Sie von Homeworker für Ihre Homeworker-App erhalten haben.
`client_secret`	`string`	Erforderlich. Den Client-Secret, welches Sie von Homeworekr für Ihre Homeworker-App erhalten haben.
`code`	`string`	Erforderlich. Den Code, welchen Sie als Antwort in Schritt 1 erhalten haben.
`grant_type`	`string`	Erforderlich. Dieses Feld muss `authorization_code` sein. Siehe OAuth 2.0 Spezifikation
`redirect_uri`	`string`	Die URL in Ihrer Anwendung, an die Benutzer nach der Autorisierung gesendet werden.
`state`	`string`	Die unberechenbare zufällige Zeichenfolge, die Sie in Schritt 1 angegeben haben.

Antwort

{
    "access_token": "54c5ec844575e9f9ad2f5c5f149d3db421cc2ee21f713de6fa9cb65b3d5f25d7",
    "expires_in": 3600,
    "scope": "me courses.memberships",
    "token_type": "Bearer",
    "refresh_token": "e9ff3758ab6f3ed1b758f6b5e98f115623674ec7f9d8512321087b35514a0dfe"
}

3. Verwenden Sie den Access-Token, um auf die API zuzugreifen

Der Access-Token ermöglicht es Ihnen, im Namen eines Benutzers Anfragen an die API zu stellen.

Authorization: Bearer OAUTH-TOKEN
GET https://homeworker.li/api/v2/me

Beispielsweise können Sie in CURL den Berechtigungskopf wie folgt einstellen:

curl -H "Authorization: token OAUTH-TOKEN" https://homeworker.li/api/v2/me

4. Erneuern Sie den Access-Token anhand des Refresh-Tokens

Access-Tokens laufen nach einer gewissen Zeit ab und werden somit ungültig. Sollten Sie danach noch Zugriff auf die API haben wollen, müssen Sie einen neuen Access-Token anhand des refresh_token beantragen. Somit erhalten Sie auch Zugriff auf die Schnittstellen, wenn der Benutzer nicht anwesend ist.
Nach der Anfrage erhalten Sie einen neuen Access-Token. Der Refresh-Token kann aktualisiert werden.

POST https://homeworker.li/api/v2/oauth2/token

Parameter

Name	Type	Description
`client_id`	`string`	Erforderlich. Die Client-ID, die Sie von Homeworker für Ihre Homeworker-App erhalten haben.
`client_secret`	`string`	Erforderlich. Den Client-Secret, welches Sie von Homeworekr für Ihre Homeworker-App erhalten haben.
`refresh_token`	`string`	Erforderlich. Den Refresh-Token, welche Sie in Schritt 2 erhalten haben
`grant_type`	`string`	Erforderlich. Dieses Feld muss `refresh_token` sein. Siehe OAuth 2.0 Spezifikation

Antwort

{
    "access_token": "54c5ec844575e9f9ad2f5c5f149d3db421cc2ee21f713de6fa9cb65b3d5f25d7",
    "expires_in": 3600,
    "scope": "me courses.memberships",
    "token_type": "Bearer",
    "refresh_token": "e9ff3758ab6f3ed1b758f6b5e98f115623674ec7f9d8512321087b35514a0dfe"
}

Nicht-Web-Anwendungsfluss

Nicht-Web-Authentifizierung ist für begrenzte Situationen wie Tests verfügbar. Bei Bedarf können Sie mit Basic Authentication über Ihre Einstellungsseite persönliche Access-Tokens erstellen. Diese Technik ermöglicht es dem Benutzer, den Zugriff jederzeit zu widerrufen.

Weiterleitungs-URLs

Der Parameter redirect_uri ist optional. Wenn er nicht angegeben wird, leitet Homeworker die Benutzer zu der in den Einstellungen der OAuth Application konfigurierten Weiterleitungs-URL um. Falls angegeben, müssen Host und Port der Umleitungs-URL genau mit der Weiterleitungs-URL übereinstimmen. Der Pfad der Umleitungs-URL muss auf ein Unterverzeichnis der Weiterleitungs-URL verweisen.

CALLBACK: http://example.com/path

GUT: http://example.com/path
GUT: http://example.com/path/subdir/other
SCHLECHT:  http://example.com/bar
SCHLECHT:  http://example.com/
SCHLECHT:  http://example.com:8080/path
SCHLECHT:  http://oauth.example.com:8080/path
SCHLECHT:  http://example.org

Localhost Weiterleitungs-URLs

Der optionale Parameter redirect_uri kann auch für Localhost-URLs verwendet werden. Wenn die Anwendung eine Localhost-URL und einen Port angibt, werden Benutzer nach der Autorisierung der Anwendung auf die angegebene URL und den Port umgeleitet. Der redirect_uri-Parameter muss nicht mit dem Port übereinstimmen, der in der Weiterleitungs-URL für die Anwendung angegeben ist.

Für die Rückruf-URL http://localhost/path können Sie diese redirect_uri verwenden: http://localhost:1234/path