Package co.ankatech.ankasecure.sdk.auth

Interface ExternalTokenProvider

All Known Implementing Classes:
ClientCredentialsExternalTokenProvider, CommandExternalTokenProvider, ExplicitExternalTokenProvider, FileExternalTokenProvider
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface ExternalTokenProvider
Supplies an externally minted token that some OTHER authorization server issued to this workload.

There are two shapes of provider here, and the distinction is worth keeping straight because the security properties differ. Three of them READ a token the environment already produced - ExternalTokenSourceKind.EXPLICIT_VALUE, ExternalTokenSourceKind.FILE, ExternalTokenSourceKind.COMMAND - and hold no credential at the external server at all. ClientCredentialsExternalTokenProvider OBTAINS one, by holding the workload's own client secret at its own authorization server and performing the client-credentials grant against it.

The SDK still ships no vendor code and still needs none. What the fetching provider knows about an authorization server it reads from that server's own discovery document, so a deployment on a vendor nobody tested works for the same reason a tested one does. A consumer with a fourth way to produce a token supplies this interface directly, and the SDK learns nothing about their provider.

The token is opaque

Nothing downstream parses it, validates its issuer, checks its audience or fetches a JWKS to verify it. Those are the relying party's job and the relying party is the server. A client that pre-validated would be reimplementing a decision it does not own, would disagree with the server the day either side changed, and would leak - through the shape of its local failures - which of the server's checks would have failed.

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    close()
    Releases whatever credential material this provider retains.
    default String
    describe()
    A short operator-facing description of WHERE the token comes from - a path, a command name, an issuer - for diagnostics.
    SecretChars
    fetchExternalToken()
    Produces the current external token.
    default void
    invalidate()
    Discards anything this provider has cached, so the next call produces a fresh token.
    default ExternalTokenSourceKind
    kind()
    Which of the configured source kinds this provider is, or null for a consumer-supplied provider that is none of them.

  • Method Details

    • fetchExternalToken

      SecretChars fetchExternalToken()
      Produces the current external token.

      How current it is belongs to the implementation, and the two answers are both correct for their case. A provider that READS an out-of-band token re-reads on every call, because something else refreshes it and a copy held here is a copy that expires without anyone noticing. A provider that OBTAINS the token itself knows the lifetime its issuer stated for it, so it may reuse one inside that lifetime - and when the issuer states no lifetime, it falls back to fetching per call rather than guessing one.

      Returns:
      the token; the caller takes ownership and closes it
      Throws:
      ExternalTokenException - if the source cannot produce a token. The message names the source, never the token.

    • kind

      default ExternalTokenSourceKind kind()
      Which of the configured source kinds this provider is, or null for a consumer-supplied provider that is none of them.
      Returns:
      the kind, or null when the provider is the consumer's own

    • describe

      default String describe()
      A short operator-facing description of WHERE the token comes from - a path, a command name, an issuer - for diagnostics. It must never contain the token.
      Returns:
      the description; never null

    • invalidate

      default void invalidate()
      Discards anything this provider has cached, so the next call produces a fresh token.

      Called when ANKASecure refuses the assertion a token produced. A provider that caches has to be reachable by this, or a client clock behind the issuer's holds a server-dead token for the rest of its stated lifetime - twenty-four hours on some defaults - and re-presents it on every attempt, against a refusal that names no cause. A provider that does not cache has nothing to discard, which is why the default does nothing.

    • close

      default void close()
      Releases whatever credential material this provider retains.

      Idempotent, and after it fetchExternalToken() is not expected to work. A provider that holds a secret at an external authorization server, or a token it minted with one, must zeroize both here: the session that owns it is closed, and material outliving it would sit in the heap for the life of the JVM. A provider holding nothing does nothing, which is why the default is empty.