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, isBasicCredentials, isDigestCredentials, setPassword, setUsername, updateAuthInfo
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 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 authentication 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 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 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.