Zurück zu Webservice API

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_typeFür den Code Flow steht der Parameter auf code
client_idDie registrierte Client ID, wie zuvor in der Konfiguration eingetragen.
redirect_uriDie redirect URL zur Weitergabe des Authorization Code
scopeAuf welche Ressourcen möchte die Anwendung Zugriff bekommen? (Instanz IDs, Leerzeichen separiert)
stateDer 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_idDie registrierte Client ID, wie zuvor in der Konfiguration eingetragen.
client_secretDas registrierte Client Secret, wie zuvor in der Konfiguration eingetragen.
grant_typeFür den Token Request immer auf authorization_code .
codeDer 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_idDie registrierte Client ID, wie zuvor in der Konfiguration eingetragen.
client_secretDas registrierte Client Secret, wie zuvor in der Konfiguration eingetragen.
grant_typeFür den Refresh Token Request immer auf refresh_token .
refresh_tokenDer 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_idDie registrierte Client ID, wie zuvor in der Konfiguration eingetragen.
client_secretDas registrierte Client Secret, wie zuvor in der Konfiguration eingetragen.
token_type_hintrefresh_token  oder access_token 
tokenAccess 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}



Sie benutzen noch kein XELOS Social Workplace?

Jetzt informieren!

Durch klick auf den Link "jetzt informieren", gelangen Sie auf unsere Produktseite "xelos.net".