# Poco::Net

# class HTTPCredentials

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.

### setHost

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

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

Sets the password.

### setUsername

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.