Class Poco::Net::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

bool empty() const;

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

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.

getHost

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

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 an Authorization header with Basic credentials is present in the request.

hasDigestCredentials

static bool hasDigestCredentials(
const HTTPRequest & request
);

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

hasNTLMCredentials

static bool hasNTLMCredentials(
const HTTPRequest & request
);

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

hasProxyBasicCredentials

static bool hasProxyBasicCredentials(
const HTTPRequest & request
);

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

hasProxyDigestCredentials

static bool hasProxyDigestCredentials(
const HTTPRequest & request
);

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

hasProxyNTLMCredentials

static bool hasProxyNTLMCredentials(
const HTTPRequest & request
);

Returns true if a Proxy-Authorization header with Digest credentials 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.

isNTLMCredentials

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.