DOCSEARCHbyAlgolia
Submit Docs

Ory Hydra

repository·master·Indexed 12 days ago

https://github.com/ory/hydra

A hardened, OpenID Certified OAuth 2.0 and OpenID Connect server designed as a standalone authorization server. It delegates user authentication and consent to external applications, allowing developers to maintain full control over the user experience without managing users directly within the server.

Tokens
104.3K
Snippets
266
Records
383
Agent score
96%

What's inside Ory Hydra

  1. Deployment options for Ory Hydra

    master

    You can deploy Ory Hydra in two primary ways:

    1. Ory Network (Managed Service): The fastest way to use Ory services in production. It is API-compatible with the open-source Hydra server and provides managed identity, credential management, and scaling.
    2. Self-hosted: You can run Hydra on your own infrastructure (Linux, macOS, Windows, Docker, or Kubernetes). You can use the open-source distribution or the Ory Enterprise License (OEL) for business-critical systems requiring CVE patches, SLAs, and advanced enterprise features.

  2. Manage JSON Web Keys via JwkAPI

    master

    The JwkAPI provides administrative endpoints to manage JSON Web Key Sets (JWKS) and individual JSON Web Keys (JWK). All URIs are relative to http://localhost. These operations typically target the /admin/keys path.

    Available Methods:

    • CreateJsonWebKeySet: Create a new JWK Set.
    • DeleteJsonWebKeySet: Delete an entire JWK Set.
    • GetJsonWebKeySet: Retrieve a JWK Set.
    • SetJsonWebKeySet: Update an existing JWK Set.
    • GetJsonWebKey: Retrieve a specific key from a set.
    • SetJsonWebKey: Set/Update a specific key within a set.
    • DeleteJsonWebKey: Delete a specific key from a set.

  3. Understand Ory security SLAs by deployment model

    master

    Ory provides different security Service Level Agreements (SLAs) and support models depending on how you use the software:

    Ory Network Users

    • Security SLA: Vulnerabilities are addressed according to severity (Critical: ~14 days, High: ~30 days, Medium: ~90 days, Low: ~180 days).
    • Release Schedule: Updates are deployed to the network as vulnerabilities are resolved.
    • Version Support: The Ory Network always runs the latest version.

    Ory Enterprise License Customers

    • Security SLA: Follows the same severity-based timelines as the Ory Network (Critical: ~14 days, High: ~30 days, Medium: ~90 days, Low: ~180 days).
    • Release Schedule: Updates are made available as vulnerabilities are resolved, coordinated with enterprise operational needs.
    • Version Support: Security support for multiple versions may be provided based on specific enterprise agreement terms.

    Apache 2.0 License Users (Self-hosted)

    • Security SLA: No formal SLA is provided.
    • Release Schedule: Releases prioritize new functionality and include fixes for known vulnerabilities at the time of release. There is no guaranteed fixed schedule.
    • Version Support: Security patches are only provided for the latest release version.

  4. What is Ory Hydra?

    master

    Ory Hydra is a hardened, OpenID Certified OAuth 2.0 Server and OpenID Connect Provider. It is designed for low-latency, high-throughput, and low resource consumption.

    Unlike traditional identity providers, Hydra is a standalone OAuth 2.0 and OpenID Connect server that does not manage users. Instead, it connects to your existing identity provider (such as Ory Kratos, Authboss, or a proprietary system) through a separate login and consent application. This architecture gives you absolute control over the user interface and the authentication/consent flows.

  5. Understand TokenPaginationResponseHeaders properties

    master

    When interacting with paginated endpoints in the Ory Hydra HTTP client, the TokenPaginationResponseHeaders object represents the metadata returned in HTTP headers. It contains two primary properties:

    1. Link: The Link HTTP header. This is a comma-delimited list of links for navigating pages. The following relations (rel) are supported:

      • first: The first page of results.
      • next: The next page of results.
      • prev: The previous page of results.
      • last: The last page of results. Note: Links are omitted if they do not exist (e.g., if there is no next page, the next link is omitted). Example format: </clients?page_size=5&page_token=0>; rel="first",</clients?page_size=5&page_token=15>; rel="next"

    2. XTotalCount: The X-Total-Count HTTP header. This contains the total number of items in the entire collection.

  6. New User Login and Consent Flow (v1.0.0)

    master

    The consent flow has been refactored to support OpenID Connect parameters (like prompt and max_age) and to separate authentication from authorization.

    Key Concept: Authentication (user login) and scope authorization (user consent) are now handled by two separate endpoints/providers:

    1. User Login Provider: Handles user authentication.
    2. User Consent Provider: Handles scope authorization.

    If you implement both in a single application, it is referred to as the User Login and Consent Provider.

  7. Use JsonWebKeySet to manage JSON Web Keys

    master
    The JsonWebKeySet type is used to represent a collection of JSON Web Keys (JWK). It contains a Keys property, which is a pointer to a slice of JsonWebKey objects. The order of keys in the array does not imply a preference order unless specifically handled by the application logic.

  8. Understand the split between Public and Administrative endpoints (v1.0.0-beta.8)

    master

    Starting with version 1.0.0-beta.8, Ory Hydra separates administrative APIs from public OAuth2/OpenID Connect endpoints by using two different ports. This allows for better security by isolating privileged management tasks.

    Administrative Endpoints

    Accessible via the administrative port (default :4445). Configurable via ADMIN_PORT and ADMIN_POST.

    • All /clients endpoints
    • All /jwks endpoints
    • /health, /metrics, /version endpoints
    • /oauth2/auth/requests endpoints
    • /oauth2/introspect
    • /oauth2/flush

    Public Endpoints

    Accessible via the public port (default :4444). Configurable via PUBLIC_PORT and PUBLIC_HOST.

    • ./well-known/jwks.json
    • ./well-known/openid-configuration
    • /oauth2/auth
    • /oauth2/token
    • /oauth2/revoke
    • /oauth2/fallbacks/consent
    • /oauth2/fallbacks/error
    • /userinfo

    Running the services

    • Both ports: Use hydra serve all (formerly hydra serve) to start both listeners. They will share settings like CORS, database, and TLS.
    • Separate configuration: To configure listeners differently (e.g., different CORS settings), run hydra serve public and hydra serve admin as separate processes.
      • Note: This requires both services to use the same secrets and does not work with DATABASE=memory.
    # Start both public and admin ports
hydra serve all

# Or start them separately for custom configuration
hydra serve public
hydra serve admin

  9. How the OAuth2 flow object is cached

    master

    To improve scalability and reduce database load, Ory Hydra uses a flow cache mechanism. Instead of storing the entire state of an OAuth2 exchange (the 'flow object') in a central database for every step, the state is moved to the client side.

    Key Mechanisms

    • AEAD Encrypted Cookies: The complete flow object is stored in a client cookie that is encrypted using Authenticated Encryption with Associated Data (AEAD). This ensures the state is secure and tamper-proof. The cookie is keyed by the state parameter to allow multiple parallel flows within the same browser session.
    • URL Verifiers: Partial flow information is passed through URLs using 'verifiers' (e.g., login_verifier or consent_verifier). These verifiers act as pointers or encoded segments that allow Hydra to resume the flow without constant database lookups.
    • Security: The architecture relies on HTTPS to protect the transmission of these cookies and URL parameters.

  10. Understand the OidcUserInfo structure

    master
    The OidcUserInfo structure represents the OpenID Connect (OIDC) user information claims returned by an Identity Provider. It contains various identity attributes about an end-user, such as name, email, and profile details. Most fields are optional and are represented as pointers to their respective types (e.g., *string, *bool, *int64) to allow for null/omitted values in the JSON payload.

  11. OAuth2 Flow Sequence with Flow Caching

    master

    The following sequence describes how the Client, Hydra, Login UI, and Consent UI interact when using the flow cache mechanism:

    1. Initialization: Client requests /oauth2/auth. Hydra redirects to the Login UI with a login_challenge (which is the AEAD-encrypted flow).
    2. Login Phase:
      • Login UI retrieves the flow via Hydra's admin API (/admin/oauth2/auth/requests/login).
      • Login UI performs an accept or reject via a PUT request.
      • Hydra responds with oAuth2RedirectTo, encoding the flow into the URL as a login_verifier.
    3. Consent Phase:
      • Client hits Hydra with the login_verifier. Hydra updates the flow and redirects to the Consent UI with a consent_challenge.
      • Consent UI retrieves the flow via /admin/oauth2/auth/requests/consent.
      • Consent UI performs an accept or reject via a PUT request.
      • Hydra responds with oAuth2RedirectTo, encoding the flow into the URL as a consent_verifier.
    4. Completion:
      • Client hits Hydra with the consent_verifier. Hydra updates the flow, writes the final state to the database, and redirects the client to the callback URL with the AUTH_CODE.
    sequenceDiagram
    actor Client
    participant Hydra
    participant LoginUI as Login UI
    participant ConsentUI as Consent UI

    autonumber

    Client->>+Hydra: GET /oauth2/auth?client_id=CLIENT_ID&response_type=code&scope=SCOPES&state=STATE
    Hydra->>-Client: Redirect to <br> http://login.local/?login_challenge=LOGIN_CHALLENGE

    Client->>+LoginUI: GET /?login_challenge=LOGIN_CHALLENGE
    LoginUI->>Hydra: GET /admin/oauth2/auth/requests/login
    Hydra->>LoginUI: oAuth2LoginRequest
    alt accept login
      LoginUI->>Hydra: PUT /admin/oauth2/auth/requests/login/accept
    else reject login
      LoginUI->>Hydra: PUT /admin/oauth2/auth/requests/login/reject
    end
    Hydra->>LoginUI: oAuth2RedirectTo
    LoginUI->>-Client: Redirect to <br> http://hydra.local/oauth2/auth?client_id=CLIENT_ID&login_verifier=LOGIN_VERIFIER&response_type=code&scope=SCOPES&state=STATE

    Client->>+Hydra: GET /oauth2/auth?client_id=CLIENT_ID&login_verifier=LOGIN_VERIFIER&response_type=code&scope=SCOPES&state=STATE
    Hydra->>-Client: Redirect to <br> http://consent.local/?consent_challenge=CONSENT_CHALLENGE

    Client->>+ConsentUI: GET /?consent_challenge=CONSENT_CHALLENGE
    ConsentUI->>Hydra: GET /admin/oauth2/auth/requests/consent
    Hydra->>ConsentUI: oAuth2ConsentRequest
    alt accept login
      ConsentUI->>Hydra: PUT /admin/oauth2/auth/requests/consent/accept
    else reject login
      ConsentUI->>Hydra: PUT /admin/oauth2/auth/requests/consent/reject
    end
    Hydra->>ConsentUI: oAuth2RedirectTo
    ConsentUI->>-Client: Redirect to <br> http://hydra.local/oauth2/auth?client_id=CLIENT_ID&consent_verifier=CONSENT_VERIFIER&response_type=code&scope=SCOPES&state=STATE

    Client->>+Hydra: GET /oauth2/auth?client_id=CLIENT_ID&consent_verifier=CONSENT_VERIFIER&response_type=code&scope=SCOPES&state=STATE
    Hydra->>-Client: Redirect to <br> http://callback.local/callback?code=AUTH_CODE&scope=SCOPES&state=STATE

  12. Understand the RFC6749ErrorJson model

    master

    The RFC6749ErrorJson struct is used to represent OAuth2 error responses in accordance with RFC 6749. It encapsulates error details returned by the API, including the error type, human-readable descriptions, debugging information, and HTTP status codes.

    Properties

    NameTypeDescription
    Error*string[optional] The error code (e.g., invalid_request).
    ErrorDebug*string[optional] Detailed debugging information.
    ErrorDescription*string[optional] A human-readable description of the error.
    ErrorHint*string[optional] A hint to help the user resolve the error.
    StatusCode*int64[optional] The associated HTTP status code.