OAuth 2.0

소개

Casdoor는 Access Token을 사용하여 클라이언트를 인증하는 것을 지원합니다. 이 섹션에서는 Access Token을 얻는 방법, Access Token을 검증하는 방법, 그리고 Access Token을 사용하는 방법에 대해 보여드리겠습니다.

Access Token을 얻는 방법

Access Token을 얻는 두 가지 방법이 있습니다: Casdoor SDKs를 사용할 수 있습니다. 자세한 정보는 SDK 문서를 참조하십시오. 여기에서는 주로 API를 사용하여 Access Token을 얻는 방법을 보여드릴 것입니다.

Casdoor는 네 가지 OAuth 부여 유형을 지원합니다: Authorization Code Grant, Implicit Grant, Resource Owner Password Credentials Grant, 그리고 Client Credentials Grant.

보안상의 이유로, Casdoor 앱은 기본적으로 권한 코드 모드가 켜져 있습니다. 다른 모드를 사용해야 한다면 적절한 앱으로 이동하여 설정하십시오.

부여 유형

Authorization Code Grant

먼저, 사용자를 다음으로 리디렉션하십시오:

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

사용 가능한 범위

이름	설명
openid (no scope)	sub (사용자의 id), iss (발행자), 그리고 aud (청중)
profile	사용자 프로필 정보, 이름, displayName, 그리고 아바타를 포함합니다.
email	사용자의 이메일 주소
address	사용자의 주소
phone	사용자의 전화번호

정보

당신의 OAuth 애플리케이션은 초기 리디렉션에서 범위를 요청할 수 있습니다. %20을 사용하여 공백으로 구분하여 여러 범위를 지정할 수 있습니다:

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

자세한 내용은 OIDC 표준을 참조하십시오.

사용자가 Casdoor로 인증한 후, Casdoor는 그들을 다음으로 리디렉션할 것입니다:

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

이제 권한 코드를 얻었으니 다음에 POST 요청을 하세요:

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

백엔드 애플리케이션에서:

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

다음과 같은 응답을 받게 됩니다:

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

:::노트

Casdoor는 또한 PKCE 기능을 지원합니다. 인증 코드를 얻을 때, PKCE를 활성화하기 위해 두 개의 매개변수를 추가할 수 있습니다:

&code_challenge_method=S256&code_challenge=YOUR_CHANNELLENGE

토큰을 얻을 때, PKCE를 검증하기 위해 code_verifier 매개변수를 전달해야 합니다. PKCE가 활성화된 상태에서는 Client_Secret이 필요하지 않지만, 전달하면 올바른 값이어야 합니다.

:::

Implicit Grant

어쩌면 당신의 애플리케이션에는 백엔드가 없고 Implicit Grant를 사용해야 할 수도 있습니다. 먼저, Implicit Grant가 활성화되어 있는지 확인한 다음 사용자를 다음으로 리디렉션하십시오:

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

사용자가 Casdoor로 인증한 후, Casdoor는 그들을 다음으로 리디렉션할 것입니다:

https://REDIRECT_URI/#access_token=ACCESS_TOKEN

Casdoor는 또한 id_token을 response_type으로 지원하는데, 이는 OpenID의 기능입니다.

Resource Owner Password Credentials Grant

당신의 애플리케이션이 사용자를 Casdoor로 리디렉션하는 프론트엔드가 없다면 이것이 필요할 수 있습니다.

먼저, Password Credentials Grant가 활성화되어 있는지 확인하고 다음으로 POST 요청을 보내야 합니다:

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

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

다음과 같은 응답을 받게 됩니다:

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

Client Credentials Grant

당신의 애플리케이션이 프론트엔드가 없을 때 Client Credentials Grant를 사용할 수도 있습니다.

먼저, Client Credentials Grant가 활성화되어 있는지 확인하고 https://<CASDOOR_HOST>/api/login/oauth/access_token으로 POST 요청을 보내야 합니다:

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

다음과 같은 응답을 받게 됩니다:

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

이 방식으로 얻은 AccessToken이 처음 세 가지와 다른 점은 이것이 사용자가 아닌 애플리케이션에 해당한다는 것입니다.

Refresh Token

아마도 Access Token을 업데이트하고 싶을 수 있습니다, 그런 다음 위에서 얻은 refreshToken을 사용할 수 있습니다.

먼저, 애플리케이션에서 Refresh Token의 만료 시간을 설정해야 합니다(기본값은 0시간), 그리고 https://<CASDOOR_HOST>/api/login/oauth/refresh_token으로 POST 요청을 보내야 합니다.

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

다음과 같은 응답을 받게 될 것입니다:

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

Access Token을 검증하는 방법

Casdoor는 현재 토큰 검사 엔드포인트를 지원합니다. 이 엔드포인트는 기본 인증 (ClientId:ClientSecret)에 의해 보호됩니다.

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

다음과 같은 응답을 받게 될 것입니다:

{
    "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"
}

`AccessToken` 사용 방법

AccessToken을 사용하여 인증이 필요한 Casdoor API에 액세스할 수 있습니다.

예를 들어, /api/userinfo를 요청하는 두 가지 다른 방법이 있습니다.

유형 1: 쿼리 매개변수

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

유형 2: HTTP Bearer 토큰

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

Casdoor는 access_token을 분석하고 scope에 따라 해당 사용자 정보를 반환합니다. 다음과 같이 보이는 동일한 응답을 받게 됩니다:

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

더 많은 사용자 정보를 기대하는 경우, Authorization Code Grant 단계에서 AccessToken을 얻을 때 scope를 추가하세요.

`userinfo`와 `get-account` API 사이의 차이점

/api/userinfo: 이 API는 OIDC 프로토콜의 일부로 사용자 정보를 반환합니다. OIDC 표준에 정의된 기본 정보만 포함하는 제한된 정보를 제공합니다. Casdoor에서 지원하는 사용 가능한 scope 목록은 available scopes 섹션을 참조하십시오.
/api/get-account: 이 API는 현재 로그인된 계정의 사용자 객체를 검색합니다. Casdoor의 user의 모든 정보를 얻을 수 있게 해주는 Casdoor 특정 API입니다.

소개​

Access Token을 얻는 방법​

Authorization Code Grant​

사용 가능한 범위​

Implicit Grant​

Resource Owner Password Credentials Grant​

Client Credentials Grant​

Refresh Token​

Access Token을 검증하는 방법​

AccessToken 사용 방법​

userinfo와 get-account API 사이의 차이점​

소개

Access Token을 얻는 방법

Authorization Code Grant

사용 가능한 범위

Implicit Grant

Resource Owner Password Credentials Grant

Client Credentials Grant

Refresh Token

Access Token을 검증하는 방법

`AccessToken` 사용 방법

`userinfo`와 `get-account` API 사이의 차이점