Zum Inhalt

Authentifizierung NEU

Viele unserer APIs sind nur für identifizierte User nutzbar. Die Authentifizierung erfolgt nach OAuth 2.0 Standard und wird über eine eigene, von der API unabhängige, Plattform (Identity-Service) durchgeführt. Zu Beginn der API Nutzung wird über die zur Verfügung gestellten Zugangsdaten von dieser Plattform ein Zugangstoken (Access-Token) erzeugt. Dieser Token ist dann bei jedem Request im HTTP Header Authorization mitzusenden.

Access-Token

Beim Access-Token handelt es sich um einen sog. JSON Web Token (JWT).
Dieser Token kann über Standard Bibliotheken oder auch Online (jwt.io) ausgelesen werden.

Zugangsdaten

Um einen gültigen Access-Token zu erhalten werden Zugangsdaten bestehend aus

  • client_id (entspricht dem Username),
  • client_secret (entspricht dem Password),
  • scopes (= spezielle Berechtigungen), sowie
  • die Adresse unseres Identity-Services url_to_authentication_service

benötigt. client_id und client_secret erhalten Sie einmalig zu Beginn der Laufzeit des Vertrages. Für unsere verschiedenen APIs (Services) nutzen wir individuelle URLs unseres Identiy-Services. Sie erhalten die url_to_authentication_service zusammen mit den Zugangsdaten.

Scopes sind Berechtigungen, die eine feinere Kontrolle des Zugangs der Anwendung erlauben. Die möglichen Scopes sind in der jeweiligen API Dokumentation ersichtlich und bei jedem Endpunkt angegeben:

Ein Scope

Eine Interaktion mit der API mit nur lesenden Zugriffen benötigt beispielsweise nur lesende Rechte. Zum Erzeugen oder ändern von Ressourcen werden meist auch schreibende Rechte benötigt.

Empfehlung

Geben Sie einer Anwendung nur jene Scopes, die benötigt werden!

Beispiele (in Englisch)

Get Token: Oauth2ClientCredentials

We provide two examples how to obtain an access token. The scopes to be requested should fit to your business application. Only request as many scopes as required to perform the task. The <realm>, <client_id> and <client_secret> are part of your individual credentials and need to be replaced as appropriate. In the given examples placeholders are indicated by angle brackets (like < ... >).

  1. cUrl command to be used within shell scripts
CLIENT_ID="<client_id>"
CLIENT_SECRET="<client_secret>"
SCOPES="openid profile urn:zitadel:iam:org:project:id:443908873612623899:aud"

curl 'https://so.yio.at/oauth/v2/token' \
   --header 'Accept: application/json, text/plain, */*' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'grant_type=client_credentials'  \
   --data-urlencode 'client_id='$CLIENT_ID \
   --data-urlencode 'client_secret='$CLIENT_SECRET \
   --data-urlencode 'scope='"$SCOPES"
  1. Python (3.6+) code snippet for use within your application
import requests

client_id = "<client_id>"
client_secret = "<client_secret>"
scopes = ["openid", "profile", "urn:zitadel:iam:org:project:id:443908873612623899:aud"]

url = "https://so.yio.at/oauth/v2/token"

payload = {
    "client_id": f"{client_id}",
    "client_secret": f"{client_secret}",
    "grant_type": "client_credentials",
    "scope": " ".join(scopes)
}
headers = {
  'Accept': 'application/json, text/plain, */*',
  'Content-Type': 'application/x-www-form-urlencoded'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.json())
print(response.text)

Get Token: JWT

To obtain an access token using a self signed jwt token you only need a private key file.

The private key file is a json file with the following structure:

{
    "type":"serviceaccount",
    "keyId":"130509901696068329",
    "key":"-----BEGIN RSA PRIVATE KEY----- [...] -----END RSA PRIVATE KEY-----\n",
    "userId":"180507859606888466"
}
from jose import jwt
import json
import time
import requests

# Create JWT for client assertion
my_key_file = "path/to/private_key.json"
scopes = ["openid", "profile", "urn:zitadel:iam:org:project:id:443908873612623899:aud"]

def create_client_assertion(key_file):
    iat_offset = -1 * 0     # 0 minutes  (start now)
    exp_offset = 60 * 60    # 60 minutes (max 60 minutes)

    isa_time = int(time.time())

    with open(key_file, "r") as file:
        jwt_key = json.load(file)
        client_id = jwt_key["clientId"]

        # Create JWT for client assertion
        payload = {
            "iss": client_id,
            "sub": client_id,
            "aud": "https://so.yio.at",
            "exp": isa_time + exp_offset,  # Expires in 30 minutes (default; can be changed)
            "iat": isa_time + iat_offset  # Issued at time - 30 minutes (default; can be changed)
        }
        headers = {
            "alg": "RS256",
            "kid": jwt_key["keyId"]
        }
        token = jwt.encode(payload, jwt_key["key"], algorithm="RS256", headers=headers)

    return token


client_assertion = create_client_assertion(my_key_file)

# The next steps are required to obtain the access token using the client assertion
# and are similar to the client credentials example (see slightly modified payload
# to indicate the grant type and the client assertion)
url = "https://so.yio.at/oauth/v2/token"

payload = {
    "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
    "scope": " ".join(scopes),
    "assertion": client_assertion
}
headers = {
  'Accept': 'application/json, text/plain, */*',
  'Content-Type': 'application/x-www-form-urlencoded'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.json())

Use PAT (Personal Access Token)

In case of using a Personal Access Token (PAT) the token is used as a bearer token in the Authorization header.

Gültigkeitsdauer

Der Access-Token ist 300 Sekunden lang gültig und wird für mehrere Requests verwendet.