xtr_security_oauth2_server_core.exception ¶
The errors this library raises, one family under one base.
Every error derives from :class:OAuth2Error, so one except OAuth2Error
catches anything this library raises. The bundle that wires this library into an
application adds its own errors beside these, each deriving from the same base.
- :class:
OAuth2Error— the base of them all. - :class:
InvalidArgumentError— one of this library's own objects used wrongly, which is a caller's mistake and nobody's answer. - :class:
OAuthServerError— a refusal the protocol has a name for, and the answer that carries it. - :class:
UniqueTokenIdentifierConstraintViolationError— a token identifier that was already taken, which a grant retries past.
InvalidArgumentError ¶
Bases: OAuth2Error, ValueError
A call into this library was malformed, and no client caused it.
An access token asked for its string form before it was handed a signer, an extra claim taking a name the token mints itself, an authorization request read before the server had understood it, an encryption key that is not a key — mistakes caught where they are made.
Deliberately not an OAuthServerError: that one is the answer a client
gets, and there is no answer to give here, because nothing a client sent
caused it. Whoever catches one has a wiring or an ordering mistake to fix,
so it derives from :class:OAuth2Error — one except OAuth2Error still
catches everything this library raises — and from nothing of the security
family, which only answers failed authentication.
Also a :class:ValueError, so code guarding a call with except
ValueError keeps working, the same reason the security family's error of
this name is one.
OAuth2Error ¶
Bases: Exception
Base class for every error raised by this library.
Catch this to handle anything the authorization server, the resource server or their wiring can go wrong with; catch a subclass to handle one cause. Every subclass carries the data a caller needs as typed attributes and composes its own message from them.
It derives from :class:Exception rather than from the security family's
base, because most of what this library raises is a protocol answer — a
request naming an unknown grant, a code that was already redeemed — not a
failure of the family's authentication machinery. The errors the firewall
will have to answer will be the exception: they will mix the family's
AuthenticationError in beside this base, so one except
SecurityError will still catch those while one except OAuth2Error
catches everything from here.
OAuthServerError ¶
OAuthServerError(message: str, code: int, error_type: str, http_status_code: int = 400, hint: str | None = None, redirect_uri: str | None = None)
Bases: OAuth2Error
A refusal the protocol has a name for, carrying everything needed to answer it.
Raised wherever a request cannot be honoured: an unknown grant type, a
client that failed authentication, a code that was already redeemed. The
error is not only a message — it is the answer, so whoever catches it asks
for one with :meth:generate_http_response and sends it.
Raise it through one of the named constructors, never by naming a number:
each one fixes the error name the protocol uses, the status the answer
carries and the number the error is catalogued under, and that triple is
the contract a client reads. Chain the cause the usual way —
raise OAuthServerError.invalid_refresh_token() from cause — so the
traceback keeps what actually went wrong without the answer naming it.
An error carrying a redirect URI is answered as a redirect rather than as a document: an authorization request that named a redirect gets its refusal delivered there, because that is where the client is waiting.
Record one answer: what went wrong, what to call it, and how to send it.
message and error_type become the error_description and the
error of the payload, and code is the number the error is
catalogued under — stable across versions, so a caller may switch on
it. A hint is sent when there is one, and an empty string counts as
one: only None leaves the field out. A redirect_uri is where
the refusal is to be delivered, when the request named anywhere.
unsupported_grant_type
classmethod
¶
The request named a grant this server does not run.
invalid_request
classmethod
¶
A parameter is missing, repeated or unusable.
Names parameter in the hint unless the caller has something more
useful to say about it.
invalid_client
classmethod
¶
The client could not be authenticated.
Takes the request because the answer depends on how the client tried:
one that sent an Authorization header is told which scheme to try
again with. The message says no more than that authentication failed —
which client, and why, is never told to the caller.
invalid_scope
classmethod
¶
The request asked for a scope this server does not know.
The scope is repeated back in the hint, escaped: it came from the request, and an application may well render the hint in a page.
invalid_credentials
classmethod
¶
The user's own credentials were wrong.
server_error
classmethod
¶
Something broke that the request could have done nothing about.
The reason goes into the description rather than the hint, because there is nothing the client can change about it.
invalid_refresh_token
classmethod
¶
The refresh token could not be read, or is no longer usable.
One answer for every reason — unreadable, another client's, expired, revoked, already spent — so a client learns nothing about a token it should not hold; the reason stays in the server's traceback.
access_denied
classmethod
¶
The user, or the server itself, refused the request.
invalid_grant
classmethod
¶
The grant presented is not one this client can redeem now.
The catch-all for a code or refresh token that is unknown, expired, revoked, bound to another redirect URI or issued to another client — deliberately one answer for all of them, with no hint, so a client cannot tell which.
expired_token
classmethod
¶
The device code polled for has expired and its session is over.
authorization_pending
classmethod
¶
The user has not finished approving the device yet; keep polling.
slow_down
classmethod
¶
The device polled too soon; it must wait five seconds longer from now on.
unauthorized_client
classmethod
¶
The client authenticated, but is not allowed this grant.
unsupported_token_type
classmethod
¶
The client named a kind of token this server cannot act on.
This server issues two kinds of token — access tokens and refresh tokens — and withdraws either. A token read as a third kind, which only a deployment that reads tokens of its own can produce, is refused rather than answered as though it had been withdrawn (RFC 7009, Section 2.2.1).
get_http_status_code ¶
Return the status a document answer carries.
It is never 302, even for an error that redirects: the status of the
refusal and the fact that it is delivered by redirect are two different
things, so an application overriding error pages can let the redirects
through — see :meth:has_redirect.
get_hint ¶
Return what the client could change, or None when there is nothing.
has_redirect ¶
Tell whether this refusal is to be delivered to a redirect URI.
get_redirect_uri ¶
Return where the refusal is to be delivered, if anywhere.
carry_issuer ¶
Have a redirected refusal name issuer as iss, as every redirect does.
RFC 9207 puts the issuer on refusals as on successes, so a client talking to several servers can tell which one sent the browser back. A refusal a grant built already names it and is left as it is; one answered as a document goes to no redirect and carries nothing.
get_payload ¶
Return what the answer says, as a read-only view.
error and error_description always, hint when there is one.
Use :meth:set_payload to change it; the view answers the payload as
it stood when it was asked for.
set_payload ¶
Replace what the answer says.
For a caller that has to shape the answer itself — adding a field an extension defines, or dropping the hint from a public error.
set_server_request ¶
Record the request this refusal answers.
Only the client-authentication answer reads it, to name back the scheme the client tried.
get_http_headers ¶
Return the headers a document answer carries, their names lowercased.
A client that tried to authenticate with an Authorization header
and failed is told which scheme to try again with: RFC 6749 §5.2 has
the 401 answering such a request carry WWW-Authenticate for the
scheme the client used. A client that put its credentials in the form
instead attempted no scheme, so none is named — and a header handed on
empty, as some servers do when the client sent none, counts as no
attempt either.
generate_http_response
async
¶
generate_http_response(response: ResponseInterface, use_fragment: bool = False) -> ResponseInterface
Build the answer to this error on top of response.
With a redirect URI, the answer is a 302 whose Location carries the
payload — in the query, or in the fragment when use_fragment is
set, as a refusal to an implicit-grant request needs. Nothing else is
added to it: a browser is going to follow the redirect, and a content
type would only describe a body that is not there.
Without a redirect URI, the answer is the payload as a JSON document, carrying this error's status and headers.
Asking twice answers the same thing: the error is left as it was, so the redirect target does not grow a separator each time.
UniqueTokenIdentifierConstraintViolationError ¶
UniqueTokenIdentifierConstraintViolationError(message: str, code: int, error_type: str, http_status_code: int = 400, hint: str | None = None, redirect_uri: str | None = None)
Bases: OAuthServerError
Storing a token failed because its identifier was already in use.
A repository raises this when the identifier a grant generated collides with one already stored. It is the one error of this library that is normally never answered: a grant catches it and mints a new identifier, and only a run of collisions long enough to exhaust its retries lets it out — which is why it is a 500 rather than a refusal the client could do anything about.