Wt: Wt::Auth::OAuthService Class Reference

Wt 4.10.4

Loading...
Searching...
No Matches
Public Member Functions | List of all members
Wt::Auth::OAuthService Class Referenceabstract

An OAuth authorization (and authentication) service provider. More...

`#include <Wt/Auth/OAuthService.h>`

Inheritance diagram for Wt::Auth::OAuthService:
[legend]

## Public Member Functions
| OAuthService (const AuthService &baseAuth)
| Constructor.
virtual | ~OAuthService ()
| Destructor.
const AuthService & | baseAuth () const
| Returns the basic authentication service.
virtual std::unique_ptr< OAuthProcess > | createProcess (const std::string &scope) const =0
| Creates a new authorization process.
void | setPopupEnabled (bool enable)
| Configure if a popup should be used for the login.
bool | popupEnabled () const
| Returns if a popup is used for the login.
virtual std::string | name () const =0
| Returns the provider name.
virtual WString | description () const =0
| Returns the provider description.
virtual int | popupWidth () const =0
| Returns the desired width for the popup window.
virtual int | popupHeight () const =0
| Returns the desired height for the popup window.
virtual std::string | authenticationScope () const =0
| Returns the scope needed for authentication.
virtual std::string | redirectEndpoint () const =0
| Returns the redirection endpoint URL.
virtual std::string | redirectEndpointPath () const
| Returns the deployment path of the redirection endpoint.
virtual std::string | authorizationEndpoint () const =0
| Returns the authorization endpoint URL.
virtual std::string | tokenEndpoint () const =0
| Returns the token endpoint URL.
virtual std::string | clientId () const =0
| Returns the client ID.
virtual std::string | clientSecret () const =0
| Returns the client secret.
virtual std::string | encodeState (const std::string &sessionId) const
| Derives a state value from the session ID.
virtual std::string | decodeState (const std::string &state) const
| Validates and decodes a state parameter.
virtual Http::Method | tokenRequestMethod () const
| Returns the HTTP method used for the token request.
virtual ClientSecretMethod | clientSecretMethod () const =0
| Returns the method to transfer the client secret.
void | configureRedirectEndpoint () const
| Configures the static resource implementing the redirect endpoint.

## Detailed Description

An OAuth authorization (and authentication) service provider.

This class implements an OAuth client (2.0 draft), which can be used to allow the user to authorize access to information provided by a third-party OAuth service provider. This allows, among other things, for a user to safely authenticate with your web application without needing to store or even handle his authorization credentials (such as a password), a pattern called "OAuth2 connect".

The OAuth protocol provides a standard for a user to authorize access to protected resources made available by a third party service. The process starts with the user authenticating on an "authorization page" and authorizing access. This results eventually in an access token for the web application. The actual use of this token, to obtain certain information (such as an authenticated identity) from the third party is however not standardized, and there are many other uses of OAuth besides authentication.

Because the focus of the Wt::Auth library is authentication, the OAuth class also contains the implementation for using the access token for authentication (OAuthProcess::getIdentity()).

Like all service classes, this class holds only configuration state. Thus, once configured, it can be safely shared between multiple sessions since its state (the configuration) is read-only. A "const OAuthService" object is thus thread-safe.

The OAuth authorization protocol, including the subsequent use for authentication, consists of a number of consecutive steps, some of which require user interaction, and some which require the use of remote web services. The state machine for this process is implemented in an OAuthProcess. To use OAuth, you need to create such a process and listen for state changes.

Usage example:

const OAuthService *oauth = ...;
// Creates an icon which prompts for authentication using this OAuth service.
WImage *icon = icons->addWidget(std::make_unique<WImage>("css/oauth-" + auth->name() + ".png"));
icon->setToolTip(auth->description());
// Creates a new process for authentication, which is started by a click on the icon
process = oauth->createProcess(oauth->authenticationScope());
icon->clicked().connect(process_, &OAuthProcess::startAuthenticate);
// And capture the result in a method.
process_->authenticated().connect(this, &MyWidget::oauthDone);
Wt::Auth::OAuthProcess::startAuthenticate
virtual void startAuthenticate()
Starts an authorization and authentication process.
Wt::Auth::OAuthService
An OAuth authorization (and authentication) service provider.
Definition OAuthService.h:439
Wt::Auth::OAuthService::authenticationScope
virtual std::string authenticationScope() const =0
Returns the scope needed for authentication.
Wt::Auth::OAuthService::createProcess
virtual std::unique_ptr< OAuthProcess > createProcess(const std::string &scope) const =0
Creates a new authorization process.
Wt::WImage
A widget that displays an image.
Definition WImage.h:54
Wt::WInteractWidget::clicked
EventSignal< WMouseEvent > & clicked()
Event signal emitted when the primary mouse button was clicked on this widget.
Wt::WWebWidget::setToolTip
virtual void setToolTip(const WString &text, TextFormat textFormat=TextFormat::Plain) override
Sets a tooltip.

## Constructor & Destructor Documentation

## ◆ OAuthService()

Wt::Auth::OAuthService::OAuthService | ( | const AuthService & | baseAuth | ) |

Constructor.

Creates a new OAuth service.

## Member Function Documentation

## ◆ authenticationScope()

virtual std::string Wt::Auth::OAuthService::authenticationScope | ( |  | ) | const
| pure virtual

Returns the scope needed for authentication.

This returns the scope that is needed (and sufficient) for obtaining identity information, and thus to authenticate the user.

See also
  OAuthProcess::getIdentity(), OAuthProcess::startAuthenticate()

Implemented in Wt::Auth::FacebookService, and Wt::Auth::OidcService.

## ◆ authorizationEndpoint()

virtual std::string Wt::Auth::OAuthService::authorizationEndpoint | ( |  | ) | const
| pure virtual

Returns the authorization endpoint URL.

This is a remote URL which hosts the OAuth authorization user interface. This URL is loaded in the popup window at the start of an authorization process.

Implemented in Wt::Auth::FacebookService, and Wt::Auth::OidcService.

## ◆ clientId()

virtual std::string Wt::Auth::OAuthService::clientId | ( |  | ) | const
| pure virtual

Returns the client ID.

This is the identification for this web application with the OAuth authorization server.

Implemented in Wt::Auth::FacebookService, and Wt::Auth::OidcService.

## ◆ clientSecret()

virtual std::string Wt::Auth::OAuthService::clientSecret | ( |  | ) | const
| pure virtual

Returns the client secret.

This is the secret credentials for this web application with the OAuth authorization server.

Implemented in Wt::Auth::FacebookService, and Wt::Auth::OidcService.

## ◆ clientSecretMethod()

virtual ClientSecretMethod Wt::Auth::OAuthService::clientSecretMethod | ( |  | ) | const
| pure virtual

Returns the method to transfer the client secret.

Some implementations (like Facebook) encode the secret in the GET request parameters, while this is explicitly not allowed in the OAuth 2.0 specification.

The default implementation returns HttpAuthorizationBasic (the recommended method).

Implemented in Wt::Auth::FacebookService, and Wt::Auth::OidcService.

## ◆ configureRedirectEndpoint()

void Wt::Auth::OAuthService::configureRedirectEndpoint | ( |  | ) | const

Configures the static resource implementing the redirect endpoint.

By default, this endpoint is configured whenever it's necessary, but one may also configure it in advance, for example in a multi-process deployment (FastCGI).

## ◆ createProcess()

virtual std::unique_ptr< OAuthProcess > Wt::Auth::OAuthService::createProcess | ( | const std::string & | scope | ) | const
| pure virtual

Creates a new authorization process.

This creates a new authorization process for the indicated scope. Valid names for the scope are service provider dependent.

See also
  authenticationScope()

Implemented in Wt::Auth::FacebookService, and Wt::Auth::OidcService.

## ◆ decodeState()

virtual std::string Wt::Auth::OAuthService::decodeState | ( | const std::string & | state | ) | const
| virtual

Validates and decodes a state parameter.

This function returns the sessionId that is encoded in the state, if the signature validates that it is an authentic state generated by encodeState().

## ◆ description()

virtual WString Wt::Auth::OAuthService::description | ( |  | ) | const
| pure virtual

Returns the provider description.

This returns a description useful for e.g. tool tips on a login icon.

See also
  name()

Implemented in Wt::Auth::FacebookService, and Wt::Auth::OidcService.

## ◆ encodeState()

virtual std::string Wt::Auth::OAuthService::encodeState | ( | const std::string & | sessionId | ) | const
| virtual

Derives a state value from the session ID.

The state value protects the authorization protocol against misuse, and is used to connect an authorization code response with a particular request.

In the default implementation the state is the `sessionId`, crytpographically signed. This signature is verified in decodeState().

## ◆ name()

virtual std::string Wt::Auth::OAuthService::name | ( |  | ) | const
| pure virtual

Returns the provider name.

This is a short identifier.

See also
  description()

Implemented in Wt::Auth::FacebookService, and Wt::Auth::OidcService.

## ◆ popupHeight()

virtual int Wt::Auth::OAuthService::popupHeight | ( |  | ) | const
| pure virtual

Returns the desired height for the popup window.

See also
  popupWidth()

Implemented in Wt::Auth::FacebookService, and Wt::Auth::OidcService.

## ◆ popupWidth()

virtual int Wt::Auth::OAuthService::popupWidth | ( |  | ) | const
| pure virtual

Returns the desired width for the popup window.

See also
  popupHeight()

Implemented in Wt::Auth::FacebookService, and Wt::Auth::OidcService.

## ◆ redirectEndpoint()

virtual std::string Wt::Auth::OAuthService::redirectEndpoint | ( |  | ) | const
| pure virtual

Returns the redirection endpoint URL.

This is the local URL to which the browser is redirect from the service provider, after the authorization process. You need to configure this URL with the third party authentication service.

A static resource will be deployed at this URL.

See also
  WServer::addResource()

Implemented in Wt::Auth::FacebookService, and Wt::Auth::OidcService.

## ◆ redirectEndpointPath()

virtual std::string Wt::Auth::OAuthService::redirectEndpointPath | ( |  | ) | const
| virtual

Returns the deployment path of the redirection endpoint.

This returns the path at which the static resource is deployed that corresponds to the redirectEndpoint().

The default implementation will derive this path from the redirectEndpoint() URL.

Reimplemented in Wt::Auth::FacebookService, and Wt::Auth::GoogleService.

## ◆ setPopupEnabled()

void Wt::Auth::OAuthService::setPopupEnabled | ( | bool | enable | ) |

Configure if a popup should be used for the login.

When set to false, the session will be suspended when the login starts, allowing the state to be restored when it completes. A timeout can be configured in wt_config.xml (see `oauth2-redirect-timeout`).

The default value is false. When JavaScript is not available, a redirect without popup is always used.

Note
  In Wt 4.8.0 the default value changed from true to false

## ◆ tokenEndpoint()

virtual std::string Wt::Auth::OAuthService::tokenEndpoint | ( |  | ) | const
| pure virtual

Returns the token endpoint URL.

This is a remote URL which hosts a web-service that generates access tokens.

Implemented in Wt::Auth::FacebookService, and Wt::Auth::OidcService.

## ◆ tokenRequestMethod()

virtual Http::Method Wt::Auth::OAuthService::tokenRequestMethod | ( |  | ) | const
| virtual

Returns the HTTP method used for the token request.

While the current OAuth 2.0 draft mandates the use of POST, some implementations (like Facebook) use URL-encoding and a GET request.

The default implementation returns Http::Method::Post (corresponding to the current draft).

Reimplemented in Wt::Auth::FacebookService.