Library: Net
Package: HTTP
Header: Poco/Net/HTTPCredentials.h
Description
This is a utility class for working with HTTP authentication (basic or digest) in HTTPRequest objects.
Usage is as follows: First, create a HTTPCredentials object containing the username and password.
Poco::Net::HTTPCredentials creds("user", "s3cr3t");
Second, send the HTTP request with Poco::Net::HTTPClientSession.
Poco::Net::HTTPClientSession session("pocoproject.org"); Poco::Net::HTTPRequest request(HTTPRequest::HTTP_GET, "/index.html", HTTPMessage::HTTP_1_1); session.sendRequest(request); Poco::Net::HTTPResponse; std::istream& istr = session.receiveResponse(response);
If the server responds with a 401 status, authenticate the request and resend it:
if (response.getStatus() == Poco::Net::HTTPResponse::HTTP_UNAUTHORIZED) { creds.authenticate(request, response); session.sendRequest(request); ... }
To perform multiple authenticated requests, call updateAuthInfo() instead of authenticate() on subsequent requests.
creds.updateAuthInfo(request); session.sendRequest(request); ...
Note: Do not forget to read the entire response stream from the 401 response before sending the authenticated request, otherwise there may be problems if a persistent connection is used.
Member Summary
Member Functions: authenticate, extractCredentials, fromURI, fromUserInfo, getPassword, getUsername, hasBasicCredentials, hasDigestCredentials, hasProxyBasicCredentials, hasProxyDigestCredentials, isBasicCredentials, isDigestCredentials, proxyAuthenticate, setPassword, setUsername, updateAuthInfo, updateProxyAuthInfo
Constructors
HTTPCredentials
Creates an empty HTTPCredentials object.
HTTPCredentials
HTTPCredentials(
const std::string & username,
const std::string & password
);
Creates an HTTPCredentials object with the given username and password.
Destructor
~HTTPCredentials
~HTTPCredentials();
Destroys the HTTPCredentials.
Member Functions
authenticate
void authenticate(
HTTPRequest & request,
const HTTPResponse & response
);
Inspects WWW-Authenticate header of the response, initializes the internal state (in case of digest authentication) and adds required information to the given HTTPRequest.
Does nothing if there is no WWW-Authenticate header in the HTTPResponse.
extractCredentials
static void extractCredentials(
const std::string & userInfo,
std::string & username,
std::string & password
);
Extracts username and password from user:password information string.
extractCredentials
static void extractCredentials(
const Poco::URI & uri,
std::string & username,
std::string & password
);
Extracts username and password from the given URI (e.g.: "http://user:pass@sample.com/secret").
fromURI
void fromURI(
const URI & uri
);
Extracts username and password from the given URI and sets username and password of the credentials object. Does nothing if URI has no user info part.
fromUserInfo
void fromUserInfo(
const std::string & userInfo
);
Parses username:password string and sets username and password of the credentials object. Throws SyntaxException on invalid user information.
getPassword
const std::string & getPassword() const;
Returns the password.
getUsername
const std::string & getUsername() const;
Returns the username.
hasBasicCredentials
static bool hasBasicCredentials(
const HTTPRequest & request
);
Returns true if Authorization with Basic credentials header is present in the request.
hasDigestCredentials
static bool hasDigestCredentials(
const HTTPRequest & request
);
Returns true if Authorization with Digest credentials header is present in the request.
hasProxyBasicCredentials
static bool hasProxyBasicCredentials(
const HTTPRequest & request
);
Returns true if Authorization with Basic credentials header is present in the request.
hasProxyDigestCredentials
static bool hasProxyDigestCredentials(
const HTTPRequest & request
);
Returns true if Authorization with Digest credentials header is present in the request.
isBasicCredentials
static bool isBasicCredentials(
const std::string & header
);
Returns true if authentication header is for Basic authentication.
isDigestCredentials
static bool isDigestCredentials(
const std::string & header
);
Returns true if authentication header is for Digest authentication.
proxyAuthenticate
void proxyAuthenticate(
HTTPRequest & request,
const HTTPResponse & response
);
Inspects Proxy-Authenticate header of the response, initializes the internal state (in case of digest authentication) and adds required information to the given HTTPRequest.
Does nothing if there is no Proxy-Authenticate header in the HTTPResponse.
setPassword
void setPassword(
const std::string & password
);
Sets the password.
setUsername
void setUsername(
const std::string & username
);
Sets the username.
updateAuthInfo
void updateAuthInfo(
HTTPRequest & request
);
Updates internal state (in case of digest authentication) and replaces authentication information in the request accordingly.
updateProxyAuthInfo
void updateProxyAuthInfo(
HTTPRequest & request
);
Updates internal state (in case of digest authentication) and replaces proxy authentication information in the request accordingly.