ORY Hydra

이 글은 www.ory.sh/hydra/docs/ 에서 발취해와 번역한 글입니다. 다소, 번역이 어색할 수 있는 점 양해 부탁드립니다.

ORY 하이드라

Hydra는 OAuth 2.0 및 OpenID Connect 제공 업체입니다. 즉, OAuth 2.0 인증 프레임 워크와 OpenID Connect Core 1.0 프레임 워크의 구현입니다. 따라서 제 3자가 사용자 이름으로 API에 액세스 할 수 있도록 OAuth 2.0 액세스, 새로 고침 및 ID 토큰을 발급합니다.

유연한 사용자 관리

ORY Hydra의 가장 큰 장점 중 하나는 다른 OAuth 2.0 구현과는 달리 "Hydra 사용자 관리"(로그인, 로그 아웃, 프로필 관리, 등록), 특정 템플릿 엔진 또는 다른 도구를 사용하지 않고도 OAuth 및 OpenID Connect 표준을 구현한다는 것입니다. 미리 정의 된 프런트 엔드.

이를 통해 사용 사례에 필요한 인증 메커니즘 (토큰 기반 2FA, SMS 2FA 등)을 사용하여 기술 스택에서 사용자 관리를 구현하고 로그인 할 수 있습니다. 물론 authboss 또는 auth0.com과 같은 기존 솔루션을 사용할 수 있습니다. OAuth 2.0 및 OpenID Connect의 모든 이점을 제공하는 동시에 비즈니스 로직 및 기술 스택에 최소한의 영향을 미칩니다.

OpenID 인증

ORY Hydra는 Certified OpenID Provider Server이며 OpenID Foundation에서 명시한 모든 요구 사항을 구현합니다. 특히 IETF 및 OpenID Foundation에서 지정한 다양한 OAuth 2.0 및 OpenID Connect 흐름을 올바르게 구현합니다.

암호화 키 저장소

OAuth 2.0 기능 외에도 ORY Hydra는 암호화 키 (예 : JSON 웹 토큰 서명에 사용)를위한 안전한 저장소를 제공하고 OAuth 2.0 클라이언트를 관리 할 수 있습니다.

보안 우선

ORY Hydra의 아키텍처 및 워크 플로는 많은 공통 (OWASP TOP TEN) 및 비정상적인 공격 벡터를 무력화하도록 설계되었습니다.

고성능

Hydra는 CPU 및 메모리 공간이 적고 시작 시간이 짧으며 Heroku, Cloud Foundry, Docker, Google Container Engine 등을 포함한 많은 플랫폼에서 손쉽게 확장 및 축소 할 수 있습니다.

개발자 친화적

Hydra는 Linux, OSX 및 Windows를 포함한 모든 인기있는 플랫폼에서 사용할 수 있습니다. 추가 종속성없이 단일 바이너리로 제공됩니다. 더 단순화하기 위해 Docker 이미지로 사용할 수 있습니다. Hydra는 또한 개발자를 위한 CLI를 제공합니다.

제한 사항

Hydra에는 몇 가지 제한 사항이 있습니다.

1. ORY Hydra는 사용자 계정, 즉 사용자 등록, 비밀번호 재설정, 사용자 로그인, 확인 이메일 전송 등을 관리하지 않습니다. Hydra의 아키텍처에서 ID 공급자는 이에 대한 책임이 있습니다.
2. ORY Hydra는 OAuth 2.0 리소스 소유자 암호 자격 증명 흐름을 지원하지 않습니다. 이는 레거시이고 권장되지 않으며 안전하지 않기 때문입니다.

ORY Hydra가 당신에게 적합합니까?

OAuth 2.0은 다양한 목적으로 다양한 환경에서 사용할 수 있습니다. 이 목록은 OAuth 2.0 및 Hydra가 사용 사례에 적합한 지 결정하는 데 도움이 될 수 있습니다.

1. 타사 솔루션이 API에 액세스 할 수 있도록합니다. 이것이 OAuth2 공급자가하는 일이고 Hydra는 완벽한 솔루션입니다.

2. Google, Facebook 또는 Microsoft와 같은 ID 제공 업체 여야합니다. OpenID Connect이므로 Hydra가 완벽하게 맞습니다.

3. 브라우저, 모바일 또는 웨어러블 애플리케이션이 API에 액세스 할 수 있도록합니다. OAuth2 공급자를 실행하면이 작업에 매우 효과적 일 수 있습니다. 장치에 암호를 저장할 필요가 없으며 언제든지 액세스 토큰을 취소 할 수 있습니다. Gmail 로그인은이 방식으로 작동합니다.

4. 백엔드 서비스가 서로 읽을 수있는 정보 유형을 제한하려고합니다. 예를 들어 댓글 서비스는 사용자 프로필 업데이트 만 가져올 수 있지만 사용자 비밀번호는 읽을 수 없어야합니다. OAuth 2.0이 적합 할 수 있습니다.

로그인 흐름

OAuth2 및 OpenID Connect에는 최종 사용자를 포함하지 않는 client_credentials 흐름을 제외한 모든 OAuth2 / OpenID Connect 흐름에 대해 인증 된 최종 사용자 세션이 필요합니다.

ORY Hydra는 최종 사용자가있는 데이터베이스를 포함하지 않지만 대신 HTTP 리디렉션을 사용하여 로그인 흐름을 다른 앱에 "위임(delegate)"합니다. 이를 로그인 또는 합의 앱이라고합니다.

다음 시퀀스 다이어그램은 OAuth2 흐름을 수행 할 때 다양한 API 호출 및 HTTP 리디렉션을 설명합니다.

OAuth 2.0 / OpenID 연결 흐름 시작

OAuth2 2.0 / OpenID 연결 흐름은 최종 사용자의 브라우저가 / oauth2 / auth 엔드포인트를 가리키도록하여 시작됩니다. 어떤 흐름 ( "코드 흐름 승인", "암시 적 흐름", ...)에 따라 일부 쿼리 매개 변수 (예 : / oauth2 / auth? response_type = code, / oauth2 / auth? response_type = token,. ..)은 변경 될 수 있지만 브라우저를 해당 URL로 보내 전체 시작은 항상 작동합니다.

로그인 엔드 포인트로 리다이렉션 #
ORY Hydra의 다음 작업은 요청 사용자를 아는 것입니다. 이를 위해 ORY Hydra는 이전에 성공한 로그인에 대한 정보를 포함하는 세션 쿠키가 설정되어 있는지 확인합니다. 또한 OpenID Connect 매개 변수 id_token_hint, prompt 및 max_age가 평가되고 처리됩니다. 해당 값과 로그인 상태에 따라 사용자는 다시 인증해야 할 수 있습니다. 그렇지 않으면 흐름이 완전히 실패합니다.

사용자를 인증하기 위해 (사용자에 대한 세션이 존재하는지 여부에 관계없이 발생) ORY Hydra는 브라우저를 구성에 설정된 "로그인 엔드포인트"으로 리다이렉션합니다.

# 환경 변수를 사용하여 설정할 수도 있습니다.
# URLS_LOGIN = https://login-app/login

urls:

login: https://login-app/login

ORY Hydra는 URL에 login_challenge 쿼리 매개 변수를 추가합니다. 이 값은 나중에 로그인 엔드 포인트에서 요청에 대한 중요한 정보를 가져 오는 데 사용해야하는 ID입니다.

https://login-app/login?login_challenge=7bb518c4eec2454dbb289f5fdb4c0ee2

로그인 세션, prompt, max_age, id_token_hint #
ORY Hydra는 사용자 세션을 추적합니다. 사용자 ID가 포함 된 쿠키를 발행하여이를 수행합니다.

후속 OAuth2 / OpenID Connect 흐름에서 세션이 확인되고 로그인 엔드 포인트는 예를 들어 로그인 HTML 양식을 표시하거나 로그인 HTML 양식을 건너 뛰도록 지시합니다.

ORY Hydra는 다음 OpenID Connect 쿼리 매개 변수를 지원합니다.

• prompt(선택 사항). Authorization Server가 최종 사용자에게 재 인증 및 동의를 요청하는지 여부를 지정하는 공백으로 구분 된 대소 문자 구분 ASCII 문자열 값 목록입니다.
  "prompt = none"은 로그인 또는 동의 사용자 인터페이스 페이지를 표시하지 않도록 ORY Hydra에 지시합니다. 최종 사용자가 아직 인증되지 않았거나 클라이언트가 요청 된 클레임에 대해 사전 구성된 동의가 없거나 요청 처리를위한 다른 조건을 충족하지 않는 경우 오류가 반환됩니다. 오류 코드는 일반적으로 login_required, interaction_required 또는 다른 코드입니다. 이는 기존 인증 및 / 또는 동의를 확인하는 방법으로 사용할 수 있습니다.
  "prompt = login"은 ORY Hydra가 최종 사용자가 로그인 엔드포인트에서 로그인 HTML 양식을 사용하여 로그인하도록합니다.
  "prompt = consent"는 ORY Hydra가 최종 사용자가 동의 엔드포인트에서 동의 HTML 양식을 사용하여 OAuth2 클라이언트를 재 인증 (동의)하도록 강제하도록 지시합니다.
  prompt = select_account는 현재 ORY Hydra에서 지원되지 않습니다. [#]을 참조하십시오.
• max_age (선택 사항)는 최종 사용자가 ORY Hydra에 의해 마지막으로 인증 된 이후 허용 가능한 경과 시간 (초)을 지정합니다. 경과 시간이이 값보다 크면 로그인 HTML 양식이 표시되고 최종 사용자가 다시 인증해야합니다.
• id_token_hint (선택 사항)-ORY Hydra에서 이전에 발급 한 ID 토큰이 최종 사용자의 클라이언트와의 현재 또는 과거 인증 세션에 대한 힌트로 전달됩니다. ID 토큰으로 식별 된 최종 사용자가 로그인되었거나 요청에 의해 로그인 된 경우 권한 부여 서버는 긍정적 인 응답을 반환합니다. 그렇지 않으면 일반적으로 login_required 오류를 반환합니다. ID 토큰의 만료 여부는 중요하지 않습니다.

이러한 매개 변수를 지정하려면 OAuth2 인증 엔드포인트 URL 쿼리에 추가합니다.

 

로그인 엔드 포인트 #
로그인 엔드 포인트 (urls.login에서 설정)는 사용자가 작성한 애플리케이션입니다. GitHub에서 예시적인 NodeJS 참조 구현을 찾을 수 있습니다.

로그인 엔드 포인트는 URL의 login_challenge 값을 사용하여 다음에 대한 HTTP GET 요청을 만들어 로그인 요청에 대한 정보를 가져옵니다.

http(s)://<HYDRA_ADMIN_URL>/oauth2/auth/requests/login?login_challenge=<challenge>

응답 (아래 "로그인 질문 응답"탭 참조)에는 로그인 요청에 대한 정보가 포함되어 있습니다. 본문에는 건너 뛰기 값이 있습니다. 값이 false이면 사용자 인터페이스가 표시되어야합니다. skip이 true이면 사용자 인터페이스를 표시하지 말고 대신 로그인 요청을 수락하거나 거부하십시오! 구현에 대한 자세한 내용은 "Implementing the Login Endpoint"안내서를 참조하십시오.

curl "http://127.0.0.1:4445/oauth2/auth/requests/login?login_challenge=7bb518c4eec2454dbb289f5fdb4c0ee2"

{
  "challenge": "7bb518c4eec2454dbb289f5fdb4c0ee2",
  "requested_scope": ["openid", "offline"],
  "requested_access_token_audience": null,
  "skip": false,
  "subject": "",
  "oidc_context": {},
  "client": {
    "client_id": "auth-code-client",
    "client_name": "",
    "redirect_uris": ["http://127.0.0.1:5555/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code", "id_token"],
    "scope": "openid offline",
    "audience": null,
    "owner": "",
    "policy_uri": "",
    "allowed_cors_origins": null,
    "tos_uri": "",
    "client_uri": "",
    "logo_uri": "",
    "contacts": null,
    "client_secret_expires_at": 0,
    "subject_type": "public",
    "token_endpoint_auth_method": "client_secret_basic",
    "userinfo_signed_response_alg": "none",
    "created_at": "2020-07-08T12:31:47Z",
    "updated_at": "2020-07-08T12:31:47Z"
  },
  "request_url": "http://127.0.0.1:4444/oauth2/auth?audience=&client_id=auth-code-client&max_age=0&nonce=hognfveoohhddoralbeygsjg&prompt=&redirect_uri=http%3A%2F%2F127.0.0.1%3A5555%2Fcallback&response_type=code&scope=openid+offline&state=imnweycejbfpyrmnahgqzcmm",
  "session_id": "d3c98aa6-67ae-478b-bc30-f7887b58f630"
}

최종 사용자를 인증하는 방법은 귀하에게 달려 있습니다. 대부분의 경우 다음과 유사한 HTML 양식이 표시됩니다.

<form action="/login" method="post">
  <input type="hidden" name="csrf_token" value="...." />
  <!-- Use CSRF tokens in your HTML forms! -->
  <input
    type="email"
    name="login_email"
    placeholder="Please enter your email address to log in"
  />
  <input type="password" name="login_password" />
  <input type="checkbox" name="remember" value="Remember me on this device" />
  <input type="submit" value="Log in" />
</form>

최종 사용자가 성공적으로 인증되면 로그인 질문을 수락하거나 로그인 질문을 거부합니다 (예 : 사용자가 OAuth2 흐름을 수행 할 수 없음).

 

{
  // Subject is the user ID of the end-user that authenticated.
  "subject": "string", // required!

  // All values below are optional!

  // Remember, if set to true, tells ORY Hydra to remember this user by telling the user agent (browser) to store
  // a cookie with authentication data. If the same user performs another OAuth 2.0 Authorization Request, he/she will not be asked to log in again.
  "remember": true,

  // RememberFor sets how long the authentication should be remembered for in seconds. If set to 0,
  // the authorization will be remembered for the duration of the browser session (using a session cookie).
  "remember_for": 0,

  // ACR sets the Authentication AuthorizationContext Class Reference value for this authentication session. You can use it to express that, for example, a user authenticated using two factor authentication.
  "acr": "string",

  // Context is an optional object which can hold arbitrary data. The data will be made available when fetching the
  // consent request under the "context" field. This is useful in scenarios where login and consent endpoints share
  // data.
  "context": {
    // "foo": "bar"
  },

  // ForceSubjectIdentifier forces the "pairwise" user ID of the end-user that authenticated. The "pairwise"
  // user ID refers to the (Pairwise Identifier Algorithm)[http://openid.net/specs/openid-connect-core-1_0.html#PairwiseAlg]
  // of the OpenID Connect specification. It allows you to set an obfuscated subject ("user") identifier that is unique
  // to the client. Please note that this changes the user ID on endpoint /userinfo and sub claim of the ID Token.
  // It does not change the sub claim in the OAuth 2.0 Introspection. Per default, ORY Hydra handles this value with its own algorithm.
  // In case you want to set this yourself you can use this field. Please note that setting this field has no effect if pairwise is not
  // configured in ORY Hydra or the OAuth 2.0 Client does not expect a pairwise identifier (set via subject_type key in the client's configuration).
  // Please also be aware that ORY Hydra is unable to properly compute this value during authentication. This implies that
  // you have to compute this value on every authentication process (probably depending on the client ID or some other unique value).
  // If you fail to compute the proper value, then authentication processes which have id_token_hint set might fail.
  "force_subject_identifier": "string"
}

 

로그인 흐름 거부 #
로그인 질문을 거부하려면 Content-Type : application / json 및 JSON 페이로드를 사용하여 HTTP PUT 요청을 수행합니다 (Reject Login Request HTTP API 참조 참조).

{
  // The error should follow the OAuth2 error format (e.g. `invalid_request`, `login_required`).
  "error": "user_banned",

  // Description of the error in a human readable format.
  "error_description": "You are banned!",

  // Hint to help resolve the error.
  "error_hint": "Contact the site administrator.",

  // Debug contains information to help resolve the problem as a developer. Usually not exposed
  // to the public but only in the server logs.
  "error_debug": "The user was marked banned in the database.",

  // Represents the HTTP status code of the error (e.g. 401 or 403)
  //
  // Defaults to 400
  "status_code": 403
}

curl을 사용하면 다음 요청과 같이 보일 수 있습니다.

$ curl --location --request PUT 'http://127.0.0.1:4445/oauth2/auth/requests/login/reject?login_challenge=7bb518c4eec2454dbb289f5fdb4c0ee2' \
--header 'Content-Type: application/json' \
--data-raw '{
  "error": "user_banned",
  "error_debug": "The user was marked banned in the database.",
  "error_description": "You are banned!",
  "error_hint": "Contact the site administrator.",
  "status_code": 403
}'

서버는 JSON으로 응답합니다.

{
  "redirect_to": "http://127.0.0.1:4445/oauth2/auth..."
}

애플리케이션이 최종 사용자의 브라우저에 연결해야하는 URL입니다.

다른 언어로 된 ORY Hydra SDK를 사용하는 예제는 "로그인 엔드포인트 구현"가이드를 확인하십시오.

동의 엔드포인트으로 리디렉션 #
동의 흐름으로 가십시오!

ORY Hydra 로그인 세션 취소 #
로그인 세션을 취소하면 ORY Hydra에서 사용자의 모든 쿠키가 제거되며 다음 OAuth 2.0 Authorize Code Flow를 수행 할 때 사용자가 재인증해야합니다. 이 옵션은 모든 장치에서 모든 쿠키를 제거합니다.