OAuth 2.0

Einführung

Casdoor unterstützt die Verwendung von Access Token zur Authentifizierung von Clients. In diesem Abschnitt zeigen wir Ihnen, wie Sie ein Access Token erhalten, wie Sie ein Access Token überprüfen und wie Sie ein Access Token verwenden.

Wie man ein Access Token erhält

Es gibt zwei Möglichkeiten, ein Access Token zu erhalten: Sie können die Casdoor SDKs verwenden. Weitere Informationen finden Sie in der SDK-Dokumentation. Hier zeigen wir Ihnen hauptsächlich, wie Sie das Access Token über die API erhalten.

Casdoor unterstützt vier OAuth-Erteilungstypen: Authorization Code Grant, Implicit Grant, Resource Owner Password Credentials Grant und Client Credentials Grant.

Aus Sicherheitsgründen ist der Autorisierungscode-Modus in der Casdoor-App standardmäßig aktiviert. Wenn Sie andere Modi verwenden müssen, gehen Sie bitte zur entsprechenden App, um dies einzustellen.

Authorization Code Grant

Zuerst leiten Sie Ihre Benutzer um zu:

https://<CASDOOR_HOST>/login/oauth/authorize?
client_id=CLIENT_ID&
redirect_uri=REDIRECT_URI&
response_type=code&
scope=openid&
state=STATE

Verfügbare Bereiche

Name	Beschreibung
openid (no scope)	sub (Benutzer-ID), iss (Aussteller) und aud (Publikum)
profile	Benutzerprofilinformationen, einschließlich Name, Anzeigename und Avatar
email	E-Mail-Adresse des Benutzers
address	Adresse des Benutzers
phone	Telefonnummer des Benutzers

Info

Ihre OAuth-Anwendung kann die Bereiche in der anfänglichen Umleitung anfordern. Sie können mehrere Bereiche angeben, indem Sie sie mit einem Leerzeichen trennen und %20 verwenden:

https://<CASDOOR_HOST>/login/oauth/authorize?
client_id=...&
scope=openid%20email

Weitere Details finden Sie im OIDC-Standard

Nachdem sich Ihr Benutzer bei Casdoor authentifiziert hat, wird Casdoor ihn umleiten zu:

https://REDIRECT_URI?code=CODE&state=STATE

Nachdem Sie den Autorisierungscode erhalten haben, machen Sie eine POST-Anfrage an:

https://<CASDOOR_HOST>/api/login/oauth/access_token

in Ihrer Backend-Anwendung:

{
    "grant_type": "authorization_code",
    "client_id": ClientId,
    "client_secret": ClientSecret,
    "code": Code,
}

Sie erhalten die folgende Antwort:

{
    "access_token": "eyJhb...",
    "id_token": "eyJhb...",
    "refresh_token": "eyJhb...",
    "token_type": "Bearer",
    "expires_in": 10080,
    "scope": "openid"
}

Notiz

Casdoor unterstützt auch die PKCE-Funktion. Beim Erhalten des Autorisierungscodes können Sie zwei Parameter hinzufügen, um PKCE zu aktivieren:

&code_challenge_method=S256&code_challenge=IHRE_HERAUSFORDERUNG

Beim Erhalten des Tokens müssen Sie den code_verifier-Parameter übergeben, um PKCE zu überprüfen. Es ist erwähnenswert, dass mit aktiviertem PKCE Client_Secret nicht erforderlich ist, aber wenn Sie es übergeben, muss es der korrekte Wert sein.

Implicit Grant

Möglicherweise hat Ihre Anwendung kein Backend, und Sie müssen Implicit Grant verwenden. Zuerst müssen Sie sicherstellen, dass Sie Implicit Grant aktiviert haben, dann leiten Sie Ihre Benutzer um zu:

https://<CASDOOR_HOST>/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=token&scope=openid&state=STATE

Nachdem sich Ihr Benutzer bei Casdoor authentifiziert hat, wird Casdoor ihn umleiten zu:

https://REDIRECT_URI/#access_token=ACCESS_TOKEN

Casdoor unterstützt auch das id_token als response_type, was ein Merkmal von OpenID ist.

Resource Owner Password Credentials Grant

Wenn Ihre Anwendung kein Frontend hat, das Benutzer zu Casdoor umleitet, dann benötigen Sie dies möglicherweise.

Zuerst müssen Sie sicherstellen, dass Sie Password Credentials Grant aktiviert haben und senden eine POST-Anfrage an:

https://<CASDOOR_HOST>/api/login/oauth/access_token

{
    "grant_type": "password",
    "client_id": ClientId,
    "client_secret": ClientSecret,
    "username": Username,
    "password": Password,
}

Sie erhalten die folgende Antwort:

{
    "access_token": "eyJhb...",
    "id_token": "eyJhb...",
    "refresh_token": "eyJhb...",
    "token_type": "Bearer",
    "expires_in": 10080,
    "scope": "openid"
}

Client Credentials Grant

Sie können auch Client Credentials Grant verwenden, wenn Ihre Anwendung kein Frontend hat.

Zuerst müssen Sie sicherstellen, dass Sie Client Credentials Grant aktiviert haben und senden eine POST-Anfrage an https://<CASDOOR_HOST>/api/login/oauth/access_token:

{
    "grant_type": "client_credentials",
    "client_id": ClientId,
    "client_secret": ClientSecret,
}

Sie erhalten die folgende Antwort:

{
    "access_token": "eyJhb...",
    "id_token": "eyJhb...",
    "refresh_token": "eyJhb...",
    "token_type": "Bearer",
    "expires_in": 10080,
    "scope": "openid"
}

Es ist wichtig zu beachten, dass der auf diese Weise erhaltene AccessToken sich von den ersten drei unterscheidet, da er der Anwendung und nicht dem Benutzer entspricht.

Refresh Token

Vielleicht möchten Sie Ihr Access Token aktualisieren, dann können Sie den oben erhaltenen refreshToken verwenden.

Zuerst müssen Sie die Ablaufzeit des Refresh Tokens in der Anwendung festlegen (Standard ist 0 Stunden) und eine POST-Anfrage an https://<CASDOOR_HOST>/api/login/oauth/refresh_token senden

{
    "grant_type": "refresh_token",
    "refresh_token": REFRESH_TOKEN,
    "scope": SCOPE,
    "client_id": ClientId,
    "client_secret": ClientSecret,
}

Sie erhalten eine Antwort wie diese:

{
    "access_token": "eyJhb...",
    "id_token": "eyJhb...",
    "refresh_token": "eyJhb...",
    "token_type": "Bearer",
    "expires_in": 10080,
    "scope": "openid"
}

Wie man Access Token überprüft

Casdoor unterstützt derzeit den Token-Introspektions-Endpunkt. Dieser Endpunkt ist durch Basic Authentication (ClientId:ClientSecret) geschützt.

POST /api/login/oauth/introspect HTTP/1.1
Host: CASDOOR_HOST
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

token=ACCESS_TOKEN&token_type_hint=access_token

Sie erhalten die folgende Antwort:

{
    "active": true,
    "client_id": "c58c...",
    "username": "admin",
    "token_type": "Bearer",
    "exp": 1647138242,
    "iat": 1646533442,
    "nbf": 1646533442,
    "sub": "7a6b4a8a-b731-48da-bc44-36ae27338817",
    "aud": [
        "c58c..."
    ],
    "iss": "http://localhost:8000"
}

Wie man AccessToken verwendet

Sie können AccessToken verwenden, um auf Casdoor-APIs zuzugreifen, die eine Authentifizierung erfordern.

Zum Beispiel gibt es zwei verschiedene Möglichkeiten, /api/userinfo anzufordern.

Typ 1: Query-Parameter

https://<CASDOOR_HOST>/api/userinfo?accessToken=<your_access_token>

Typ 2: HTTP Bearer-Token

https://<CASDOOR_HOST>/api/userinfo with the header: "Authorization: Bearer <your_access_token>"

Casdoor wird das access_token analysieren und entsprechende Benutzerinformationen gemäß dem scope zurückgeben. Sie erhalten dieselbe Antwort, die so aussieht:

{
    "sub": "7a6b4a8a-b731-48da-bc44-36ae27338817",
    "iss": "http://localhost:8000",
    "aud": "c58c..."
}

Wenn Sie mehr Benutzerinformationen erwarten, fügen Sie scope hinzu, wenn Sie das AccessToken in Schritt Authorization Code Grant erhalten.

Unterschiede zwischen den APIs userinfo und get-account

• /api/userinfo: Diese API gibt Benutzerinformationen als Teil des OIDC-Protokolls zurück. Sie bietet begrenzte Informationen, einschließlich nur der grundlegenden Informationen, die in den OIDC-Standards definiert sind. Eine Liste der von Casdoor unterstützten verfügbaren Bereiche finden Sie im Abschnitt verfügbare Bereiche.

• /api/get-account: Diese API ruft das Benutzerobjekt für das derzeit eingeloggte Konto ab. Es handelt sich um eine spezifische API von Casdoor, die es Ihnen ermöglicht, alle Informationen des Benutzers in Casdoor zu erhalten.