Library: Net
Package: HTTP
Header: Poco/Net/HTTPCredentials.h
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 Functions: authenticate, extractCredentials, fromURI, fromUserInfo, getPassword, getUsername, hasBasicCredentials, hasDigestCredentials, hasProxyBasicCredentials, hasProxyDigestCredentials, isBasicCredentials, isDigestCredentials, proxyAuthenticate, setPassword, setUsername, updateAuthInfo, updateProxyAuthInfo
Creates an empty HTTPCredentials object.
HTTPCredentials(
const std::string & username,
const std::string & password
);
Creates an HTTPCredentials object with the given username and password.
~HTTPCredentials();
Destroys the HTTPCredentials.
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.
static void extractCredentials(
const std::string & userInfo,
std::string & username,
std::string & password
);
Extracts username and password from user:password information string.
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").
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.
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.
const std::string & getPassword() const;
Returns the password.
const std::string & getUsername() const;
Returns the username.
static bool hasBasicCredentials(
const HTTPRequest & request
);
Returns true if Authorization with Basic credentials header is present in the request.
static bool hasDigestCredentials(
const HTTPRequest & request
);
Returns true if Authorization with Digest credentials header is present in the request.
static bool hasProxyBasicCredentials(
const HTTPRequest & request
);
Returns true if Authorization with Basic credentials header is present in the request.
static bool hasProxyDigestCredentials(
const HTTPRequest & request
);
Returns true if Authorization with Digest credentials header is present in the request.
static bool isBasicCredentials(
const std::string & header
);
Returns true if authentication header is for Basic authentication.
static bool isDigestCredentials(
const std::string & header
);
Returns true if authentication header is for Digest authentication.
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.
void setPassword(
const std::string & password
);
Sets the password.
void setUsername(
const std::string & username
);
Sets the username.
void updateAuthInfo(
HTTPRequest & request
);
Updates internal state (in case of digest authentication) and replaces authentication information in the request accordingly.
void updateProxyAuthInfo(
HTTPRequest & request
);
Updates internal state (in case of digest authentication) and replaces proxy authentication information in the request accordingly.