Poco::Net

class HTTPCredentials

File Information

Library: Net
Package: HTTP
Header: Poco/Net/HTTPCredentials.h

Description

This is a utility class for working with HTTP authentication (Basic, Digest or NTLM) 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, clear, empty, extractCredentials, fromURI, fromUserInfo, getHost, getPassword, getUsername, hasBasicCredentials, hasDigestCredentials, hasNTLMCredentials, hasProxyBasicCredentials, hasProxyDigestCredentials, hasProxyNTLMCredentials, isBasicCredentials, isDigestCredentials, isNTLMCredentials, proxyAuthenticate, setHost, setPassword, setUsername, updateAuthInfo, updateProxyAuthInfo

Constructors

HTTPCredentials

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.

clear

void clear();

Clears username, password and host.

empty inline

bool empty() const;

Returns true if both username and password are empty, otherwise false.

extractCredentials static

static void extractCredentials(
    const std::string & userInfo,
    std::string & username,
    std::string & password
);

Extracts username and password from user:password information string.

extractCredentials static

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.

getHost inline

const std::string & getHost() const;

Returns the target host. Only used for SSPI-based NTLM authentication using the credentials of the currently logged-in user on Windows.

getPassword inline

const std::string & getPassword() const;

Returns the password.

getUsername inline

const std::string & getUsername() const;

Returns the username.

hasBasicCredentials static

static bool hasBasicCredentials(
    const HTTPRequest & request
);

Returns true if an Authorization header with Basic credentials is present in the request.

hasDigestCredentials static

static bool hasDigestCredentials(
    const HTTPRequest & request
);

Returns true if an Authorization header with Digest credentials is present in the request.

hasNTLMCredentials static

static bool hasNTLMCredentials(
    const HTTPRequest & request
);

Returns true if an Authorization header with NTLM credentials is present in the request.

hasProxyBasicCredentials static

static bool hasProxyBasicCredentials(
    const HTTPRequest & request
);

Returns true if a Proxy-Authorization header with Basic credentials is present in the request.

hasProxyDigestCredentials static

static bool hasProxyDigestCredentials(
    const HTTPRequest & request
);

Returns true if a Proxy-Authorization header with Digest credentials is present in the request.

hasProxyNTLMCredentials static

static bool hasProxyNTLMCredentials(
    const HTTPRequest & request
);

Returns true if a Proxy-Authorization header with Digest credentials is present in the request.

isBasicCredentials static

static bool isBasicCredentials(
    const std::string & header
);

Returns true if authentication header is for Basic authentication.

isDigestCredentials static

static bool isDigestCredentials(
    const std::string & header
);

Returns true if authentication header is for Digest authentication.

isNTLMCredentials static

static bool isNTLMCredentials(
    const std::string & header
);

Returns true if authentication header is for NTLM 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.

setHost inline

void setHost(
    const std::string & host
);

Sets the target host. Only used for SSPI-based NTLM authentication using the credentials of the currently logged-in user on Windows.

setPassword inline

void setPassword(
    const std::string & password
);

Sets the password.

setUsername inline

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.