OAuth 2.0 API
Client Zugriff auf die XELOS API über OAuth 2.0. Freischaltung, Autorisierung und Nutzung des Access Tokens mit der XELOS API.
OAuth 2.0
Dieser Artikel setzt allgemeine Kenntnisse über das OAuth 2.0 Verfahren zur Autorisierung und Authentifizierung voraus. (Lesetipp für eine übersichtliche Darstellung des Verfahrens).
XELOS verwendet den sog. Authorization Code Flow und unterstützt die Mechanismen "Refresh Token" und "Revoke Token". OAuth 2.0 kann verwendet werden, um mit einer anderen Anwendung im Namen eines Anwenders über die XELOS API auf Daten und Ressourcen zuzugreifen, welche für den Anwender zugänglich sind.
Voraussetzungen
Autorisieren sie im ersten Schritt Ihre Anwendung, mit welcher Sie auf die API zugreifen wollen.
In der Webservice Konfiguration registrieren Sie hierzu Ihre Anwendung durch die Vergabe einer client_id ein, z.B. "myapiscript"
Sie können auch ein Client Secret vergeben, dazu verwenden Sie einfach folg. Syntax: client_id:client_secret
1. Authorization Request
Im ersten Schritt muss der Anwender den Zugriff autorisieren. Diese Autorisierung erfolgt über einen Request welche in der Regel durch Ihre Anwendung ausgelöst wird, z.B.:
https://example.xelos.net/webservice/authorize/?redirect_uri=https://api.example.com/myscript&scope=crm&state=mystate1234&client_id=myapiscript&response_type=code
Beschreibung der Request Parameter. Alle Parameter sind notwendig.
response_type | Für den Code Flow steht der Parameter auf code |
client_id | Die registrierte Client ID, wie zuvor in der Konfiguration eingetragen. |
redirect_uri | Die redirect URL zur Weitergabe des Authorization Code |
scope | Auf welche Ressourcen möchte die Anwendung Zugriff bekommen? (Instanz IDs, Leerzeichen separiert) |
state | Der client state wird an die redirect_uri durchgereicht und sollte ein Sicherheitsmerkmal enthalten |
Der Anwender wird durch o.g. Request auf die XELOS Installation geleitet und muss den Zugriff autorisieren. Nach entsprechender Zustimmung wird der Anwender auf die Redirect URI geleitet und der Request beinhaltet einen Authorization Code zur weiteren Verarbeitung durch die Drittanwendung.
Beispiel Redirect Request nach erfolgreicher Autorisation:
https://api.example.com/myscript?state=mystate1234&code=a768403c825b5516f7599569c4ef8fc60069afa3
2. Token Request
Die Client Anwendung kann nun mit dem Authorization Code einen Access Token anfordern. Der Token Request muss innerhalb kurzer Zeit erfolgen, da der Authorization Code nur eine begrenzte Laufzeit gültig ist (Standard: 1h). Hierzu wird von der Anwendung der Token Endpoint mit dem Code als Parameter aufgerufen:
https://example.xelos.net/webservice/authorize?client_id=myapiscript&client_secret=myapisecret&grant_type=authorization_code&code=a768403c825b5516f7599569c4ef8fc60069afa3
Beschreibung der Request Parameter. Alle Parameter sind notwendig.
client_id | Die registrierte Client ID, wie zuvor in der Konfiguration eingetragen. |
client_secret | Das registrierte Client Secret, wie zuvor in der Konfiguration eingetragen. |
grant_type | Für den Token Request immer auf authorization_code . |
code | Der Code aus dem Authorization Request |
In der Antwort erhält die Client Anwendung einen Access Token und einen Refresh Token:
{ "access_token": "...", "expires_in": "...", "refresh_token": "...", }
3. Refresh Token Request
Bevor der Access Token abläuft kann die Client Anwendung über den Refresh Token Endpoint einen neuen Access Token anfordern.
Der Request wird an den Refresh Token Endpoint geschickt:
https://example.xelos.net/webservice/authorize/refresh_token?client_id=myapiscript&client_secret=myapisecret&grant_type=refresh_tokenb&refresh_token=<refresh_token>
Beschreibung der Request Parameter. Alle Parameter sind notwendig.
client_id | Die registrierte Client ID, wie zuvor in der Konfiguration eingetragen. |
client_secret | Das registrierte Client Secret, wie zuvor in der Konfiguration eingetragen. |
grant_type | Für den Refresh Token Request immer auf refresh_token . |
refresh_token | Der Refresh Token |
In der Antwort erhält die Client Anwendung einen neuen Access Token und einen neuen Refresh Token:
{ "access_token": "...", "expires_in": "...", "refresh_token": "...", }
4. Revoke Token Request
Es ist der Client Anwendung möglich einen Token vorzeitig zu löschen, hierzu wird der Revoke Endpoint mit Access oder Refresh Token aufgerufen.
Beispiel:
https://example.xelos.net/webservice/authorize/revoke?client_id=myapiscript&client_secret=myapisecret&token_type_hint=refresh_tokenb&token=<refresh_token>
Beschreibung der Request Parameter. Alle Parameter sind notwendig.
client_id | Die registrierte Client ID, wie zuvor in der Konfiguration eingetragen. |
client_secret | Das registrierte Client Secret, wie zuvor in der Konfiguration eingetragen. |
token_type_hint | refresh_token oder access_token |
token | Access oder Refresh Token |
In der Antwort erhält die Client Anwendung eine Bestätigung:
{ "result": "Token revoked" }
5. API Requests
Mit dem gültigen Access Token kann die Client Anwendung nun die XELOS API Endpoints des vorher festgelegten Scopes aufrufen. Hierzu wird der Access Token als HTTP Authorization Header in den API Requests mitgeschickt:
Beispiel:
POST /webservice/json/crm HTTP/1.1 Host: example.xelos.net Authorization: Bearer <TOKEN> {"jsonrpc": "2.0", "method": "list.", "params": { "..." },"id": 1}