class Poco::Net::HTTPCredentials

Overview

This is a utility class for working with HTTP authentication (basic or digest) in HTTPRequest objects. More…

#include <HTTPCredentials.h>

class HTTPCredentials
{
public:
    // construction

    HTTPCredentials();

    HTTPCredentials(
        const std::string& username,
        const std::string& password
        );

    // methods

    void
    fromUserInfo(const std::string& userInfo);

    void
    fromURI(const URI& uri);

    void
    setUsername(const std::string& username);

    const std::string&
    getUsername() const;

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

    const std::string&
    getPassword() const;

    void
    authenticate(
        HTTPRequest& request,
        const HTTPResponse& response
        );

    void
    updateAuthInfo(HTTPRequest& request);

    void
    proxyAuthenticate(
        HTTPRequest& request,
        const HTTPResponse& response
        );

    void
    updateProxyAuthInfo(HTTPRequest& request);

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

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

    static
    bool
    hasBasicCredentials(const HTTPRequest& request);

    static
    bool
    hasDigestCredentials(const HTTPRequest& request);

    static
    bool
    hasProxyBasicCredentials(const HTTPRequest& request);

    static
    bool
    hasProxyDigestCredentials(const HTTPRequest& request);

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

    static
    void
    extractCredentials(
        const Poco::URI& uri,
        std::string& username,
        std::string& password
        );
};

Detailed Documentation

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.

Construction

HTTPCredentials()

Creates an empty HTTPCredentials object.

HTTPCredentials(
    const std::string& username,
    const std::string& password
    )

Creates an HTTPCredentials object with the given username and password.

Methods

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.

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
setUsername(const std::string& username)

Sets the username.

const std::string&
getUsername() const

Returns the username.

void
setPassword(const std::string& password)

Sets the password.

const std::string&
getPassword() const

Returns the password.

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.

void
updateAuthInfo(HTTPRequest& request)

Updates internal state (in case of digest authentication) and replaces authentication information in the request accordingly.

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
updateProxyAuthInfo(HTTPRequest& request)

Updates internal state (in case of digest authentication) and replaces proxy authentication information in the request accordingly.

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.

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
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”).