10Duke Scale C++ Client
|
#include <OIDCSession.h>
Stateful service to manage OIDC-session.
NOTE: Try to avoid excessive use of reEstablish()
, refresh()
or heartbeat()
. It is usually enough to call ensureValidSession()
before an API request. We trust that usually the local state is in sync with the backend. Excessive use of reEstablish()
, refresh()
or heartbeat()
cause increased latency and consume unnecessary backend resources. Only use those methods, if there is a evidence or reasonable doubt that the local state is out-of-sync with the backend.
Public Member Functions | |
virtual void | ensureValidSession ()=0 |
Checks that the OIDC session is valid, but if it is NOT, either refreshes the access token or authenticates the user. | |
virtual std::string | getAccessToken ()=0 |
Returns access token of the session. | |
virtual std::shared_ptr< const tenduke::oidc::OIDCState > | getOIDCState ()=0 |
Returns the current OIDC-state for inspection. | |
virtual bool | heartbeat ()=0 |
Executes a heartbeat with the backend, checking that the current access token really works. | |
virtual void | invalidate ()=0 |
Invalidates the session. | |
virtual bool | isValid ()=0 |
Checks that local session is valid. | |
virtual void | refresh ()=0 |
Forces refresh of the session. | |
virtual void | reEstablish ()=0 |
Re-establishes the session: Tries first to refresh the state, if it fails, re-authenticates the user. | |
|
pure virtual |
Checks that the OIDC session is valid, but if it is NOT, either refreshes the access token or authenticates the user.
Call this method before doing request which uses the access token (method getAccessToken()
). You do not need call this method unless you want to use access token: E.g. it is unnecessary to schedule a task for this.
Valid OIDC session requires a non-expired access token. If the access token has expired, this method tries to refresh the access token. If the refresh fails because the the refresh token has expired or if there is no valid session in the first place (i.e. there is no access token), the service starts login flow.
Note that this method cannot guarantee that the next request with the access token does not fail. For possible reasons, see method isValid()
.
Because of this, requests using the access token should prepare to handle HTTP 401 errors by calling this method again.
tenduke::InterruptedException | when e.g. login was aborted |
tenduke::TimedOut | when login times out or concurrent thread times out waiting to execute this method |
Implemented in tenduke::oidc::OIDCSessionImpl, and tenduke::oidc::SerializedOIDCSession.
|
pure virtual |
Returns access token of the session.
std::string::empty()
if the user has not authenticated. Note that the returned value might not be working access token if the token has expired. tenduke::TimedOut | when concurrent access times out |
Implemented in tenduke::oidc::OIDCSessionImpl, and tenduke::oidc::SerializedOIDCSession.
|
pure virtual |
Returns the current OIDC-state for inspection.
The state MUST NOT be modified.
nullptr
if there is no current state tenduke::TimedOut | when concurrent access times out |
Implemented in tenduke::oidc::OIDCSessionImpl, and tenduke::oidc::SerializedOIDCSession.
|
pure virtual |
Executes a heartbeat with the backend, checking that the current access token really works.
The heartbeat does not modify the state, even if the credentials are defunct. Typical reaction after false
is to call reEstablish()
.
IMPORTANT: Do not call this repeatedly (e.g. schedule a task to execute heart beats). Also, you don't need to call this just before executing an API call. We trust that normally the local state is in sync with the backend and using OIDCSession::ensureValidSession()
is usually enough. This method should only be used when there is doubt that the local session state is not in sync with the backend.
true
if the check was OK and local state is still valid. Returns false
otherwise. tenduke::TimedOut | when concurrent access times out |
tenduke::http::HTTPRequestException | if the HTTP-status code indicates error |
tenduke::http::HTTPException | in other HTTP-related issues |
tenduke::net::NetworkingException | e.g. host not found, network connection issues |
Implemented in tenduke::oidc::OIDCSessionImpl, and tenduke::oidc::SerializedOIDCSession.
|
pure virtual |
Invalidates the session.
tenduke::TimedOut | when concurrent access times out |
Implemented in tenduke::oidc::OIDCSessionImpl, and tenduke::oidc::SerializedOIDCSession.
|
pure virtual |
Checks that local session is valid.
This method checks that there is a session and it has not expired.
Note that this method only checks the local session information, it does not verify the state from the backend. This means that requests using the access token might fail even if this method returns true
, because .e.g.
tenduke::TimedOut | when concurrent access times out |
Implemented in tenduke::oidc::IdTokenSession, tenduke::oidc::OIDCSessionImpl, and tenduke::oidc::SerializedOIDCSession.
|
pure virtual |
Re-establishes the session: Tries first to refresh the state, if it fails, re-authenticates the user.
IMPORTANT: Do not call this method "just in case". Read the class documentation and heartbeat()
.
tenduke::TimedOut | when concurrent access times out |
Implemented in tenduke::oidc::OIDCSessionImpl, and tenduke::oidc::SerializedOIDCSession.
|
pure virtual |
Forces refresh of the session.
Does nothing if a) there is no session or b) the session is not refreshable.
IMPORTANT: Do not call this unless you really know what you are doing. Use ensureValidSession()
instead. This method only does refresh, it never logs in.
tenduke::TimedOut | when concurrent access times out |
Implemented in tenduke::oidc::OIDCSessionImpl, and tenduke::oidc::SerializedOIDCSession.