From 96cdf611018cbf4b692cd0c658f26294d71062df Mon Sep 17 00:00:00 2001 From: Ahmad Nassri Date: Thu, 5 Feb 2015 12:19:47 -0500 Subject: [PATCH] allowing all native libcurl authentication methods --- README.md | 71 +++++++++++++++++++++---- src/Unirest/Request.php | 115 ++++++++++++++++++++++++++++------------ 2 files changed, 142 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index ca205d4..c394ccc 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Unirest is a set of lightweight HTTP libraries available in [multiple languages] * Utility methods to call `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `CONNECT`, `OPTIONS`, `TRACE`, `PATCH` requests * Supports form parameters, file uploads and custom body entities * Supports gzip -* Supports Basic Authentication natively +* Supports Basic, Digest, Negotiate, NTLM Authentication natively * Customizable timeout * Customizable default headers for every request (DRY) * Automatic JSON parsing into a native object for JSON responses @@ -110,29 +110,59 @@ $body = json_encode(array("foo" => "hellow", "bar" => "world")); $response = Unirest\Request::post("http://httpbin.org/post", $headers, $body); ``` -### Basic Authentication +### Authentication -Authenticating the request with basic authentication can be done by providing the `username` and `password` arguments: +Passing a username, password *(optional)*, defaults to Basic Authentication: + +```php +// basic auth +Unirest\Request::auth('username', 'password'); +``` + +The third parameter, which is a bitmask, will Unirest which HTTP authentication method(s) you want it to use for your proxy authentication. + +If more than one bit is set, Unirest *(at PHP's libcurl level)* will first query the site to see what authentication methods it supports and then pick the best one you allow it to use. *For some methods, this will induce an extra network round-trip.* + +**Supported Method** + +| Method | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `CURLAUTH_BASIC` | HTTP Basic authentication. This is the default choice | +| `CURLAUTH_DIGEST` | HTTP Digest authentication. as defined in [RFC 2617](http://www.ietf.org/rfc/rfc2617.txt) | +| `CURLAUTH_DIGEST_IE` | HTTP Digest authentication with an IE flavor. *The IE flavor is simply that libcurl will use a special "quirk" that IE is known to have used before version 7 and that some servers require the client to use.* | +| `CURLAUTH_NEGOTIATE` | HTTP Negotiate (SPNEGO) authentication. as defined in [RFC 4559](http://www.ietf.org/rfc/rfc4559.txt) | +| `CURLAUTH_NTLM` | HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. | +| `CURLAUTH_NTLM_WB` | NTLM delegating to winbind helper. Authentication is performed by a separate binary application. *see [libcurl docs](http://curl.haxx.se/libcurl/c/CURLOPT_HTTPAUTH.html) for more info* | +| `CURLAUTH_ANY` | This is a convenience macro that sets all bits and thus makes libcurl pick any it finds suitable. libcurl will automatically select the one it finds most secure. | +| `CURLAUTH_ANYSAFE` | This is a convenience macro that sets all bits except Basic and thus makes libcurl pick any it finds suitable. libcurl will automatically select the one it finds most secure. | +| `CURLAUTH_ONLY` | This is a meta symbol. OR this value together with a single specific auth value to force libcurl to probe for un-restricted auth and if not, only that single auth algorithm is acceptable. | + +```php +// custom auth method +Unirest\Request::proxyAuth('username', 'password', CURLAUTH_DIGEST); +``` + +Previous versions of **Unirest** support *Basic Authentication* by providing the `username` and `password` arguments: ```php $response = Unirest\Request::get("http://httpbin.org/get", null, null, "username", "password"); ``` +**This has been deprecated, and will be completely removed in `v.3.0.0` please use the `Unirest\Request::auth()` method instead** + ### Request Object ```php -Unirest\Request::get($url, $headers = array(), $parameters = null, $username = null, $password = null) -Unirest\Request::post($url, $headers = array(), $body = null, $username = null, $password = null) -Unirest\Request::put($url, $headers = array(), $body = null, $username = null, $password = null) -Unirest\Request::patch($url, $headers = array(), $body = null, $username = null, $password = null) -Unirest\Request::delete($url, $headers = array(), $body = null, $username = null, $password = null) +Unirest\Request::get($url, $headers = array(), $parameters = null) +Unirest\Request::post($url, $headers = array(), $body = null) +Unirest\Request::put($url, $headers = array(), $body = null) +Unirest\Request::patch($url, $headers = array(), $body = null) +Unirest\Request::delete($url, $headers = array(), $body = null) ``` - `url` - Endpoint, address, or uri to be acted upon and requested information from. - `headers` - Request Headers as associative array or object - `body` - Request Body as associative array or object -- `username` - Basic Authentication username -- `password` - Basic Authentication password You can send a request with any [standard](http://www.iana.org/assignments/http-methods/http-methods.xhtml) or custom HTTP Method: @@ -183,7 +213,6 @@ you can also set the proxy type to be one of `CURLPROXY_HTTP`, `CURLPROXY_HTTP_1 *check the [cURL docs](http://curl.haxx.se/libcurl/c/CURLOPT_PROXYTYPE.html) for more info*. ```php - // quick setup with default port: 1080 Unirest\Request::proxy('10.10.10.1'); @@ -194,6 +223,26 @@ Unirest\Request::proxy('10.10.10.1', 8080, CURLPROXY_HTTP); Unirest\Request::proxy('10.10.10.1', 8080, CURLPROXY_HTTP, true); ``` +##### Proxy Authenticaton + +Passing a username, password *(optional)*, defaults to Basic Authentication: + +```php +// basic auth +Unirest\Request::proxyAuth('username', 'password'); +``` + +The third parameter, which is a bitmask, will Unirest which HTTP authentication method(s) you want it to use for your proxy authentication. + +If more than one bit is set, Unirest *(at PHP's libcurl level)* will first query the site to see what authentication methods it supports and then pick the best one you allow it to use. *For some methods, this will induce an extra network round-trip.* + +See [Authentication](#authentication) for more details on methods supported. + +```php +// basic auth +Unirest\Request::proxyAuth('username', 'password', CURLAUTH_DIGEST); +``` + #### Default Request Headers You can set default headers that will be sent on every request: diff --git a/src/Unirest/Request.php b/src/Unirest/Request.php index 91dabde..628471a 100644 --- a/src/Unirest/Request.php +++ b/src/Unirest/Request.php @@ -7,15 +7,29 @@ use Unirest\Response; class Request { - private static $proxyPort = false; - private static $proxyType = CURLPROXY_HTTP; - private static $proxyTunnel = false; - private static $proxyAddress = false; private static $jsonOpts = array(); private static $verifyPeer = true; private static $socketTimeout = null; private static $defaultHeaders = array(); + private static $auth => array ( + 'user' => '', + 'pass' => '', + 'method' => CURLAUTH_BASIC + ); + + private static $proxy = array( + 'port' => false, + 'tunnel' => false, + 'address' => false, + 'type' => CURLPROXY_HTTP, + 'auth' => array ( + 'user' => '', + 'pass' => '', + 'method' => CURLAUTH_BASIC + ) + ); + /** * Set JSON decode mode * @@ -81,6 +95,20 @@ class Request return self::$defaultHeaders = array(); } + /** + * Set authentication method to use + * + * @param string $username authentication username + * @param string $password authentication password + * @param string $method authentication method + */ + public static function auth($username = '', $password = '', $method = CURLAUTH_BASIC) + { + self::$auth['user'] = $username; + self::$auth['pass'] = $password; + self::$auth['method'] = $method; + } + /** * Set proxy to use * @@ -91,10 +119,25 @@ class Request */ public static function proxy($address, $port = 1080, $type = CURLPROXY_HTTP, $tunnel = false) { - self::$proxyType = $type; - self::$proxyPort = $port; - self::$proxyTunnel = $tunnel; - self::$proxyAddress = $address; + self::$proxy['type'] = $type; + self::$proxy['port'] = $port; + self::$proxy['tunnel'] = $tunnel; + self::$proxy['address'] = $address; + } + + /** + * Set proxy authentication method to use + * + * @param string $username authentication username + * @param string $password authentication password + * @param string $method authentication method + * @param string $tunnel enable/disable tunneling + */ + public static function proxyAuth($username = '', $password = '', $method = CURLAUTH_BASIC) + { + self::$proxy['auth']['user'] = $username; + self::$proxy['auth']['pass'] = $password; + self::$proxy['auth']['method'] = $method; } /** @@ -103,8 +146,8 @@ class Request * @param string $url URL to send the GET request to * @param array $headers additional headers to send * @param mixed $parameters parameters to send in the querystring - * @param string $username Basic Authentication username - * @param string $password Basic Authentication password + * @param string $username Authentication username (deprecated) + * @param string $password Authentication password (deprecated) * @return string|stdObj response string or stdObj if response is json-decodable */ public static function get($url, $headers = array(), $parameters = null, $username = null, $password = null) @@ -117,8 +160,8 @@ class Request * @param string $url URL to send the HEAD request to * @param array $headers additional headers to send * @param mixed $parameters parameters to send in the querystring - * @param string $username Basic Authentication username - * @param string $password Basic Authentication password + * @param string $username Basic Authentication username (deprecated) + * @param string $password Basic Authentication password (deprecated) * @return string|stdObj response string or stdObj if response is json-decodable */ public static function head($url, $headers = array(), $parameters = null, $username = null, $password = null) @@ -145,8 +188,8 @@ class Request * @param string $url URL to send the CONNECT request to * @param array $headers additional headers to send * @param mixed $parameters parameters to send in the querystring - * @param string $username Basic Authentication username - * @param string $password Basic Authentication password + * @param string $username Basic Authentication username (deprecated) + * @param string $password Basic Authentication password (deprecated) * @return string|stdObj response string or stdObj if response is json-decodable */ public static function connect($url, $headers = array(), $parameters = null, $username = null, $password = null) @@ -159,8 +202,8 @@ class Request * @param string $url URL to send the POST request to * @param array $headers additional headers to send * @param mixed $body POST body data - * @param string $username Basic Authentication username - * @param string $password Basic Authentication password + * @param string $username Basic Authentication username (deprecated) + * @param string $password Basic Authentication password (deprecated) * @return string|stdObj response string or stdObj if response is json-decodable */ public static function post($url, $headers = array(), $body = null, $username = null, $password = null) @@ -173,8 +216,8 @@ class Request * @param string $url URL to send the DELETE request to * @param array $headers additional headers to send * @param mixed $body DELETE body data - * @param string $username Basic Authentication username - * @param string $password Basic Authentication password + * @param string $username Basic Authentication username (deprecated) + * @param string $password Basic Authentication password (deprecated) * @return string|stdObj response string or stdObj if response is json-decodable */ public static function delete($url, $headers = array(), $body = null, $username = null, $password = null) @@ -187,8 +230,8 @@ class Request * @param string $url URL to send the PUT request to * @param array $headers additional headers to send * @param mixed $body PUT body data - * @param string $username Basic Authentication username - * @param string $password Basic Authentication password + * @param string $username Basic Authentication username (deprecated) + * @param string $password Basic Authentication password (deprecated) * @return string|stdObj response string or stdObj if response is json-decodable */ public static function put($url, $headers = array(), $body = null, $username = null, $password = null) @@ -201,8 +244,8 @@ class Request * @param string $url URL to send the PATCH request to * @param array $headers additional headers to send * @param mixed $body PATCH body data - * @param string $username Basic Authentication username - * @param string $password Basic Authentication password + * @param string $username Basic Authentication username (deprecated) + * @param string $password Basic Authentication password (deprecated) * @return string|stdObj response string or stdObj if response is json-decodable */ public static function patch($url, $headers = array(), $body = null, $username = null, $password = null) @@ -215,8 +258,8 @@ class Request * @param string $url URL to send the TRACE request to * @param array $headers additional headers to send * @param mixed $body TRACE body data - * @param string $username Basic Authentication username - * @param string $password Basic Authentication password + * @param string $username Basic Authentication username (deprecated) + * @param string $password Basic Authentication password (deprecated) * @return string|stdObj response string or stdObj if response is json-decodable */ public static function trace($url, $headers = array(), $body = null, $username = null, $password = null) @@ -259,8 +302,8 @@ class Request * @param string $url URL to send the request to * @param mixed $body request body * @param array $headers additional headers to send - * @param string $username Basic Authentication username - * @param string $password Basic Authentication password + * @param string $username Authentication username (deprecated) + * @param string $password Authentication password (deprecated) * @throws Exception if a cURL error occurs * @return Unirest\Response */ @@ -299,15 +342,21 @@ class Request curl_setopt($ch, CURLOPT_TIMEOUT, self::$socketTimeout); } - if (!empty($username)) { - curl_setopt($ch, CURLOPT_USERPWD, $username . ':' . ((empty($password)) ? '' : $password)); + if (!empty($self::auth['user'])) { + curl_setopt($ch, CURLOPT_USERNAME, self::$auth['user']); + curl_setopt($ch, CURLOPT_PASSWORD, self::$auth['pass']); + curl_setopt($ch, CURLOPT_HTTPAUTH, self::$auth['method']); } - if (self::$proxyAddress) { - curl_setopt($ch, CURLOPT_PROXYTYPE, self::$proxyType); - curl_setopt($ch, CURLOPT_PROXY, self::$proxyAddress); - curl_setopt($ch, CURLOPT_PROXYPORT, self::$proxyPort); - curl_setopt($ch, CURLOPT_HTTPPROXYTUNNEL, self::$proxyTunnel); + if (self::$proxy['address'] !== false) { + curl_setopt($ch, CURLOPT_PROXYTYPE, self::$proxy['type']); + curl_setopt($ch, CURLOPT_PROXY, self::$proxy['address']); + curl_setopt($ch, CURLOPT_PROXYPORT, self::$proxy['port']); + curl_setopt($ch, CURLOPT_HTTPPROXYTUNNEL, self::$proxy['tunnel']); + + curl_setopt($ch, CURLOPT_PROXYAUTH, self::$proxy['auth']['method']); + curl_setopt($ch, CURLOPT_PROXYUSERNAME, self::$proxy['auth']['user']); + curl_setopt($ch, CURLOPT_PROXYPASSWORD, self::$proxy['auth']['pass']); } $response = curl_exec($ch);