diff --git a/configuration/authorization-storage.html b/configuration/authorization-storage.html index ff2bd00..8a151cd 100644 --- a/configuration/authorization-storage.html +++ b/configuration/authorization-storage.html @@ -173,7 +173,28 @@ When using the OpenI removed from the database after a short period of time (14 days by default). Unlike ad-hoc authorizations, permanent authorizations never removed from the database.

- +

Enabling authorization entry validation at the API level

+

For performance reasons, OpenIddict 3.0 doesn't check, by default, the status of an authorization entry when receiving an API request: access tokens are considered +valid even if the attached authorization was revoked. For scenarios that require immediate authorization revocation, the OpenIddict validation handler can be configured +to enforce authorization entry validation for each API request:

+

[!INFO] +Enabling authorization entry validation requires that the OpenIddict validation handler have a direct access to the server database where authorizations are stored, which makes it +better suited for APIs located in the same application as the authorization server. For external applications, consider using introspection instead of local validation.

+

In both cases, additional latency – caused by the additional DB request and the HTTP call for introspection – is expected.

+
+
services.AddOpenIddict()
+    .AddValidation(options =>
+    {
+        options.EnableAuthorizationEntryValidation();
+    });
+

Disabling authorization storage

+

While STRONGLY discouraged, authorization storage can be disabled in the server options:

+
services.AddOpenIddict()
+    .AddServer(options =>
+    {
+        options.DisableAuthorizationStorage();
+    });
+
diff --git a/configuration/toc.html b/configuration/toc.html index 2f709e6..ce33cbf 100644 --- a/configuration/toc.html +++ b/configuration/toc.html @@ -18,11 +18,14 @@
  • Application permissions
  • +
  • + Authorization storage +
  • Token formats
  • - Authorization storage + Token storage
  • diff --git a/configuration/token-formats.html b/configuration/token-formats.html index 0a18197..8f8490a 100644 --- a/configuration/token-formats.html +++ b/configuration/token-formats.html @@ -68,6 +68,11 @@

    Token formats

    +

    [!INFO] +In OpenIddict 3.0, being able to revoke a token is not tied to the token format and doesn't require enabling reference tokens: +regular JWT or ASP.NET Core Data Protection tokens can be revoked as long as token storage is not explicitly disabled by the developer

    +

    For more information about reference tokens, read Token storage.

    +

    JSON Web Token

    OpenIddict 3.0 implements the JSON Web Token, JSON Web Signature and JSON Web Encryption standards and relies on the diff --git a/configuration/token-storage.html b/configuration/token-storage.html new file mode 100644 index 0000000..3d085d1 --- /dev/null +++ b/configuration/token-storage.html @@ -0,0 +1,161 @@ + + + + + + + + Token storage + + + + + + + + + + + + + + + +

    +
    + +
    +
    +
    + + + + +
    +
    +
    +
    + +
    +
    +
    +
    +
    + +
    +
    +
      +
    • +
    +
    +
    +
    +
    + +
    + Show / Hide Table of Contents +
    +
    +
    +
    +
    +
    +
    +

    Token storage

    + +

    To keep track of all the tokens produced by its server services, OpenIddict 3.0 creates a token entry in the database for each generated token. +A token entry contains metadata like the subject of the token, the client identifier of the application it was issued to or its creation and expiration dates.

    +

    By default, the token payload – generated using either the +Azure Active Directory IdentityModel Extensions for .NET library for JWT tokens or +ASP.NET Core Data Protection for Data Protection tokens – is never stored in the database, +except for authorization codes (that are short-lived), device and user codes (exclusively used in the device code flow).

    +

    Such tokens – called reference tokens – are not returned as-is to the caller: instead, their payload is stored in the database entry and a crypto-secure random 256-bit identifier +– called reference identifier – is returned as a base64url-encoded string and serves as the "final" token used by the client application when communicating with OpenIddict's endpoints +or with resource servers (if reference access tokens are enabled in the server options).

    +

    [!INFO] +In OpenIddict 3.0, being able to revoke a token is not tied to the token format and doesn't require enabling reference tokens: +regular JWT or ASP.NET Core Data Protection tokens can be revoked as long as token storage is not explicitly disabled by the developer.

    +
    +

    Enabling reference access and/or refresh tokens

    +

    Reference access and refresh tokens can be manually enabled in the server options for developers who prefer returning +shorter access and/or refresh tokens or need to deal with limits that would prevent sending large tokens over the wire.

    +
    Caution

    When enabling reference access and/or refresh tokens support, it is STRONGLY recommended to either:

    +
      +
    • Use the ASP.NET Core Data Protection format for access and refresh tokens, as they benefit from additional security measures that would prevent them from being sent as-is if +they were stolen from the database. For more information on how to enable ASP.NET Core Data Protection, read Token formats.
    • +
    • Enable column encryption/data at rest encryption to protect the Payload column of token entries.
    • +
    +
    +
    services.AddOpenIddict()
    +    .AddServer(options =>
    +    {
    +        options.UseReferenceAccessTokens()
    +               .UseReferenceRefreshTokens();
    +    });
    +

    Enabling token entry validation at the API level

    +

    For performance reasons, OpenIddict 3.0 doesn't check, by default, the status of a token entry when receiving an API request: access tokens are considered valid until they expire. +For scenarios that require immediate access token revocation, the OpenIddict validation handler can be configured to enforce token entry validation for each API request:

    +

    [!INFO] +Enabling token entry validation requires that the OpenIddict validation handler have a direct access to the server database where tokens are stored, which makes it +better suited for APIs located in the same application as the authorization server. For external applications, consider using introspection instead of local validation.

    +

    In both cases, additional latency – caused by the additional DB request and the HTTP call for introspection – is expected.

    +
    +
    services.AddOpenIddict()
    +    .AddValidation(options =>
    +    {
    +        options.EnableTokenEntryValidation();
    +    });
    +

    Disabling token storage

    +

    While STRONGLY discouraged, token storage can be disabled in the server options:

    +
    services.AddOpenIddict()
    +    .AddServer(options =>
    +    {
    +        options.DisableTokenStorage();
    +    });
    +
    Warning

    Disabling token storage prevents reference access or refresh tokens support from being enabled, as this requires storing the tokens in the database.

    +
    +
    +
    + +
    +
    +
    +
      +
    • + Improve this Doc +
    • +
    +
    +
    +
    In This Article
    +
    +
    +
    +
    +
    +
    + +
    +
    +
    +
    + + Back to top + + + Generated by DocFX +
    +
    +
    +
    + + + + + + diff --git a/manifest.json b/manifest.json index 629bdea..7e1227d 100644 --- a/manifest.json +++ b/manifest.json @@ -9861,7 +9861,7 @@ "output": { ".html": { "relative_path": "configuration/authorization-storage.html", - "hash": "OFSAAR/675OwAhhWVsS24w==" + "hash": "Hd7zZtB6quLlA6PuvtaxWA==" } }, "is_incremental": false, @@ -9885,7 +9885,7 @@ "output": { ".html": { "relative_path": "configuration/toc.html", - "hash": "xW+gHghpmAoEGBDFX0tdAQ==" + "hash": "UPFXOaji27N3tvRcJTgSow==" } }, "is_incremental": false, @@ -9897,7 +9897,19 @@ "output": { ".html": { "relative_path": "configuration/token-formats.html", - "hash": "qsPzTXi/sPCUwwXKdhcF5w==" + "hash": "eAWnxe/vobBoHyPOHuKRmQ==" + } + }, + "is_incremental": false, + "version": "" + }, + { + "type": "Conceptual", + "source_relative_path": "configuration/token-storage.md", + "output": { + ".html": { + "relative_path": "configuration/token-storage.html", + "hash": "Ld32xASqmME3EFn+1T/RrQ==" } }, "is_incremental": false, @@ -10694,7 +10706,7 @@ "ConceptualDocumentProcessor": { "can_incremental": false, "incrementalPhase": "build", - "total_file_count": 8, + "total_file_count": 9, "skipped_file_count": 0 }, "ManagedReferenceDocumentProcessor": {