Interface OAuth2AuthorizationService

All Known Implementing Classes:
InMemoryOAuth2AuthorizationService, JdbcOAuth2AuthorizationService
public interface OAuth2AuthorizationService

Where an authorization server keeps the grants it has made and the secrets it issued under them.

A secret -- an authorization code, a refresh token, a device code, a user code -- is never stored: its SHA-256 is, see OAuth2Parameters.sha256(String). And a secret that works once is used up by consumeToken(String, String, long), which an implementation must make one conditional statement on one row, never a read followed by a write: several processes may share the store, and of two that present the same code at the same moment exactly one may be told yes.

This is not the interface of Spring Authorization Server's service of the same name, whose save and findByToken leave that atomicity to the caller.

  • Field Details

  • Method Details

    • save

      void save(OAuth2Authorization authorization)
      Stores authorization, in place of the one with its id if there is one.

    • findById

      OAuth2Authorization findById(String id)
      The grant with this id, or null: one that was removed is revoked.

    • remove

      void remove(String id)
      Removes the grant and every secret issued under it.

    • addToken

      void addToken(String authorizationId, String kind, String tokenHash, long expiresAt)
      Records a secret issued under a grant.
      Parameters:
      kind - CODE, REFRESH_TOKEN, DEVICE_CODE or USER_CODE
      tokenHash - the SHA-256 of the secret
      expiresAt - epoch milliseconds

    • issueTokens

      default boolean issueTokens(String authorizationId, long now, long expiresAt, String refreshTokenHash, boolean reuse)
      Issues tokens only while an active, unexpired grant still exists. Extending the grant and adding or extending its refresh token must be one atomic operation with respect to remove(String), including across server processes. A removed grant must never be recreated. Custom stores must implement this operation before issuing user tokens; the default fails closed.
      Parameters:
      refreshTokenHash - null when no refresh token is issued
      reuse - whether the hash names an existing unused, unexpired refresh token
      Returns:
      false when the grant or reused refresh token is no longer valid

    • findToken

      OAuth2AuthorizationService.StoredToken findToken(String kind, String tokenHash)
      What is stored for a secret, whatever its state; null when nothing is.

    • consumeToken

      boolean consumeToken(String kind, String tokenHash, long now)
      Uses a secret up, if it is there, unused and has not expired at now, and records now as when.
      Returns:
      whether THIS call used it up

    • extendToken

      default boolean extendToken(String kind, String tokenHash, long now, long expiresAt)
      Extends an unused, unexpired token to at least expiresAt, atomically. Returns false if it is missing, used or expired at now. Custom stores must implement this before enabling refresh token reuse.

    • touchToken

      void touchToken(String kind, String tokenHash, long now)
      Records that a secret was presented at now, without checking its previous timestamp. Use pollToken(String, String, long, long) to enforce a polling interval.

    • pollToken

      default boolean pollToken(String kind, String tokenHash, long now, long intervalMillis)
      Claims a polling interval on an unused, unexpired token. Checking the previous poll and recording now must be one atomic operation, including across processes sharing a database. Rejected polls do not claim an interval. Custom stores must implement this before enabling the device grant.
      Parameters:
      intervalMillis - the minimum time between accepted polls, greater than zero
      Returns:
      whether this call claimed the interval

    • decide

      boolean decide(String id, boolean approved, String principalName, Map<String,Object> attributes)
      Answers a device grant that is OAuth2Authorization.PENDING: makes it OAuth2Authorization.ACTIVE for principalName, or OAuth2Authorization.DENIED.
      Parameters:
      attributes - what to remember of the user who approved, merged into the grant's own
      Returns:
      whether THIS call answered it

    • purgeExpired

      int purgeExpired(long now, int limit)
      Forgets up to limit grants and secrets that expired before now.
      Returns:
      how many were forgotten