Class OAuthService
- Direct Known Subclasses:
FacebookService
,OidcService
public abstract class OAuthService
extends java.lang.Object
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.
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:
OAuthService oauth = ...;
// Creates an icon which prompts for authentication using this OAuth service.
WImage icon = new WImage("css/oauth-" + auth.getName() + ".png", icons);
icon.setToolTip(auth.getDescription());
// Creates a new process for authentication, which is started by a click on the icon
process = oauth.createProcess(oauth.getAuthenticationScope());
process.connectStartAuthenticate(icon.clicked());
// And capture the result in a method.
process.authenticated().addListener(this, new Signal1.Listener<Identity>() {
public void trigger(Identity id) {
MyWidget.this.oAuthDone(id);
}
});
-
Constructor Summary
Constructors Constructor Description OAuthService(AuthService auth)
Constructor. -
Method Summary
Modifier and Type Method Description protected static java.lang.String
configurationProperty(java.lang.String property)
void
configureRedirectEndpoint()
Configures the static resource implementing the redirect endpoint.abstract OAuthProcess
createProcess(java.lang.String scope)
Creates a new authorization process.java.lang.String
decodeState(java.lang.String state)
Validates and decodes a state parameter.java.lang.String
encodeState(java.lang.String url)
Derives a state value from the session ID.abstract java.lang.String
getAuthenticationScope()
Returns the scope needed for authentication.abstract java.lang.String
getAuthorizationEndpoint()
Returns the authorization endpoint URL.AuthService
getBaseAuth()
Returns the basic authentication service.abstract java.lang.String
getClientId()
Returns the client ID.abstract java.lang.String
getClientSecret()
Returns the client secret.abstract ClientSecretMethod
getClientSecretMethod()
Returns the method to transfer the client secret.abstract WString
getDescription()
Returns the provider description.java.lang.String
getGenerateRedirectEndpoint()
abstract java.lang.String
getName()
Returns the provider name.abstract int
getPopupHeight()
Returns the desired height for the popup window.abstract int
getPopupWidth()
Returns the desired width for the popup window.abstract java.lang.String
getRedirectEndpoint()
Returns the redirection endpoint URL.java.lang.String
getRedirectEndpointPath()
Returns the deployment path of the redirection endpoint.java.lang.String
getRedirectInternalPath()
abstract java.lang.String
getTokenEndpoint()
Returns the token endpoint URL.Method
getTokenRequestMethod()
Returns the HTTP method used for the token request.java.lang.String
getUserInfoEndpoint()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Constructor Details
-
OAuthService
Constructor.Creates a new OAuth service.
-
-
Method Details
-
getBaseAuth
Returns the basic authentication service. -
createProcess
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:
getAuthenticationScope()
-
getName
public abstract java.lang.String getName()Returns the provider name.This is a short identifier.
- See Also:
getDescription()
-
getDescription
Returns the provider description.This returns a description useful for e.g. tool tips on a login icon.
- See Also:
getName()
-
getPopupWidth
public abstract int getPopupWidth()Returns the desired width for the popup window.- See Also:
getPopupHeight()
-
getPopupHeight
public abstract int getPopupHeight()Returns the desired height for the popup window.- See Also:
getPopupWidth()
-
getAuthenticationScope
public abstract java.lang.String getAuthenticationScope()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.
-
getRedirectEndpoint
public abstract java.lang.String getRedirectEndpoint()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.
-
getRedirectEndpointPath
public java.lang.String getRedirectEndpointPath()Returns the deployment path of the redirection endpoint.This returns the path at which the static resource is deployed that corresponds to the
getRedirectEndpoint()
.The default implementation will derive this path from the
getRedirectEndpoint()
URL. -
getAuthorizationEndpoint
public abstract java.lang.String getAuthorizationEndpoint()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.
-
getTokenEndpoint
public abstract java.lang.String getTokenEndpoint()Returns the token endpoint URL.This is a remote URL which hosts a web-service that generates access tokens.
-
getUserInfoEndpoint
public java.lang.String getUserInfoEndpoint() -
getClientId
public abstract java.lang.String getClientId()Returns the client ID.This is the identification for this web application with the OAuth authorization server.
-
getClientSecret
public abstract java.lang.String getClientSecret()Returns the client secret.This is the secret credentials for this web application with the OAuth authorization server.
-
encodeState
public java.lang.String encodeState(java.lang.String url)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 indecodeState()
. -
decodeState
public java.lang.String decodeState(java.lang.String state)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()
. -
getTokenRequestMethod
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::Post (corresponding to the current draft).
-
getClientSecretMethod
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).
-
getGenerateRedirectEndpoint
public java.lang.String getGenerateRedirectEndpoint() -
getRedirectInternalPath
public java.lang.String getRedirectInternalPath() -
configureRedirectEndpoint
public void configureRedirectEndpoint()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).
-
configurationProperty
protected static java.lang.String configurationProperty(java.lang.String property)
-