mirror of https://github.com/ansible/ansible.git
Windows - Add common util for web requests (#54759)
* Windows - Add common util for web requests * Use different method of retrieving options from module arg spec * Added proper version_added for module options * Fix linting errors * Fix proxy issues and updated cred docs * Fix FTP usage with proxy settings * Removed uneeded function added in bad rebase * Fix up client certificate auth * fix new sanity checks * Edit http agent code and update porting guidepull/59359/head
parent
1f3a3fdd3e
commit
015119df8c
@ -0,0 +1,500 @@
|
|||||||
|
# Copyright (c) 2019 Ansible Project
|
||||||
|
# Simplified BSD License (see licenses/simplified_bsd.txt or https://opensource.org/licenses/BSD-2-Clause)
|
||||||
|
|
||||||
|
Function Get-AnsibleWebRequest {
|
||||||
|
<#
|
||||||
|
.SYNOPSIS
|
||||||
|
Creates a System.Net.WebRequest object based on common URL module options in Ansible.
|
||||||
|
|
||||||
|
.DESCRIPTION
|
||||||
|
Will create a WebRequest based on common input options within Ansible. This can be used manually or with
|
||||||
|
Invoke-WithWebRequest.
|
||||||
|
|
||||||
|
.PARAMETER Uri
|
||||||
|
The URI to create the web request for.
|
||||||
|
|
||||||
|
.PARAMETER Method
|
||||||
|
The protocol method to use, if omitted, will use the default value for the URI protocol specified.
|
||||||
|
|
||||||
|
.PARAMETER FollowRedirects
|
||||||
|
Whether to follow redirect reponses. This is only valid when using a HTTP URI.
|
||||||
|
all - Will follow all redirects
|
||||||
|
none - Will follow no redirects
|
||||||
|
safe - Will only follow redirects when GET or HEAD is used as the Method
|
||||||
|
|
||||||
|
.PARAMETER Headers
|
||||||
|
A hashtable or dictionary of header values to set on the request. This is only valid for a HTTP URI.
|
||||||
|
|
||||||
|
.PARAMETER HttpAgent
|
||||||
|
A string to set for the 'User-Agent' header. This is only valid for a HTTP URI.
|
||||||
|
|
||||||
|
.PARAMETER MaximumRedirection
|
||||||
|
The maximum number of redirections that will be followed. This is only valid for a HTTP URI.
|
||||||
|
|
||||||
|
.PARAMETER Timeout
|
||||||
|
The timeout in seconds that defines how long to wait until the request times out.
|
||||||
|
|
||||||
|
.PARAMETER ValidateCerts
|
||||||
|
Whether to validate SSL certificates, default to True.
|
||||||
|
|
||||||
|
.PARAMETER ClientCert
|
||||||
|
The path to PFX file to use for X509 authentication. This is only valid for a HTTP URI. This path can either
|
||||||
|
be a filesystem path (C:\folder\cert.pfx) or a PSPath to a credential (Cert:\CurrentUser\My\<thumbprint>).
|
||||||
|
|
||||||
|
.PARAMETER ClientCertPassword
|
||||||
|
The password for the PFX certificate if required. This is only valid for a HTTP URI.
|
||||||
|
|
||||||
|
.PARAMETER ForceBasicAuth
|
||||||
|
Whether to set the Basic auth header on the first request instead of when required. This is only valid for a
|
||||||
|
HTTP URI.
|
||||||
|
|
||||||
|
.PARAMETER UrlUsername
|
||||||
|
The username to use for authenticating with the target.
|
||||||
|
|
||||||
|
.PARAMETER UrlPassword
|
||||||
|
The password to use for authenticating with the target.
|
||||||
|
|
||||||
|
.PARAMETER UseDefaultCredential
|
||||||
|
Whether to use the current user's credentials if available. This will only work when using Become, using SSH with
|
||||||
|
password auth, or WinRM with CredSSP or Kerberos with credential delegation.
|
||||||
|
|
||||||
|
.PARAMETER UseProxy
|
||||||
|
Whether to use the default proxy defined in IE (WinINet) for the user or set no proxy at all. This should not
|
||||||
|
be set to True when ProxyUrl is also defined.
|
||||||
|
|
||||||
|
.PARAMETER ProxyUrl
|
||||||
|
An explicit proxy server to use for the request instead of relying on the default proxy in IE. This is only
|
||||||
|
valid for a HTTP URI.
|
||||||
|
|
||||||
|
.PARAMETER ProxyUsername
|
||||||
|
An optional username to use for proxy authentication.
|
||||||
|
|
||||||
|
.PARAMETER ProxyPassword
|
||||||
|
The password for ProxyUsername.
|
||||||
|
|
||||||
|
.PARAMETER ProxyUseDefaultCredential
|
||||||
|
Whether to use the current user's credentials for proxy authentication if available. This will only work when
|
||||||
|
using Become, using SSH with password auth, or WinRM with CredSSP or Kerberos with credential delegation.
|
||||||
|
|
||||||
|
.PARAMETER Module
|
||||||
|
The AnsibleBasic module that can be used as a backup parameter source or a way to return warnings back to the
|
||||||
|
Ansible controller.
|
||||||
|
|
||||||
|
.EXAMPLE
|
||||||
|
$spec = @{
|
||||||
|
options = @{}
|
||||||
|
}
|
||||||
|
$spec.options += $ansible_web_request_options
|
||||||
|
$module = Ansible.Basic.AnsibleModule]::Create($args, $spec)
|
||||||
|
|
||||||
|
$web_request = Get-AnsibleWebRequest -Module $module
|
||||||
|
#>
|
||||||
|
[CmdletBinding()]
|
||||||
|
[OutputType([System.Net.WebRequest])]
|
||||||
|
Param (
|
||||||
|
[Alias("url")]
|
||||||
|
[System.Uri]
|
||||||
|
$Uri,
|
||||||
|
|
||||||
|
[System.String]
|
||||||
|
$Method,
|
||||||
|
|
||||||
|
[Alias("follow_redirects")]
|
||||||
|
[ValidateSet("all", "none", "safe")]
|
||||||
|
[System.String]
|
||||||
|
$FollowRedirects = "safe",
|
||||||
|
|
||||||
|
[System.Collections.IDictionary]
|
||||||
|
$Headers,
|
||||||
|
|
||||||
|
[Alias("http_agent")]
|
||||||
|
[System.String]
|
||||||
|
$HttpAgent = "ansible-httpget",
|
||||||
|
|
||||||
|
[Alias("maximum_redirection")]
|
||||||
|
[System.Int32]
|
||||||
|
$MaximumRedirection = 50,
|
||||||
|
|
||||||
|
[System.Int32]
|
||||||
|
$Timeout = 30,
|
||||||
|
|
||||||
|
[Alias("validate_certs")]
|
||||||
|
[System.Boolean]
|
||||||
|
$ValidateCerts = $true,
|
||||||
|
|
||||||
|
# Credential params
|
||||||
|
[Alias("client_cert")]
|
||||||
|
[System.String]
|
||||||
|
$ClientCert,
|
||||||
|
|
||||||
|
[Alias("client_cert_password")]
|
||||||
|
[System.String]
|
||||||
|
$ClientCertPassword,
|
||||||
|
|
||||||
|
[Alias("force_basic_auth")]
|
||||||
|
[Switch]
|
||||||
|
$ForceBasicAuth,
|
||||||
|
|
||||||
|
[Alias("url_username")]
|
||||||
|
[System.String]
|
||||||
|
$UrlUsername,
|
||||||
|
|
||||||
|
[Alias("url_password")]
|
||||||
|
[System.String]
|
||||||
|
$UrlPassword,
|
||||||
|
|
||||||
|
[Alias("use_default_credential")]
|
||||||
|
[Switch]
|
||||||
|
$UseDefaultCredential,
|
||||||
|
|
||||||
|
# Proxy params
|
||||||
|
[Alias("use_proxy")]
|
||||||
|
[System.Boolean]
|
||||||
|
$UseProxy = $true,
|
||||||
|
|
||||||
|
[Alias("proxy_url")]
|
||||||
|
[System.String]
|
||||||
|
$ProxyUrl,
|
||||||
|
|
||||||
|
[Alias("proxy_username")]
|
||||||
|
[System.String]
|
||||||
|
$ProxyUsername,
|
||||||
|
|
||||||
|
[Alias("proxy_password")]
|
||||||
|
[System.String]
|
||||||
|
$ProxyPassword,
|
||||||
|
|
||||||
|
[Alias("proxy_use_default_credential")]
|
||||||
|
[Switch]
|
||||||
|
$ProxyUseDefaultCredential,
|
||||||
|
|
||||||
|
[ValidateScript({ $_.GetType().FullName -eq 'Ansible.Basic.AnsibleModule' })]
|
||||||
|
[System.Object]
|
||||||
|
$Module
|
||||||
|
)
|
||||||
|
|
||||||
|
# Set module options for parameters unless they were explicitly passed in.
|
||||||
|
if ($Module) {
|
||||||
|
foreach ($param in $PSCmdlet.MyInvocation.MyCommand.Parameters.GetEnumerator()) {
|
||||||
|
if ($PSBoundParameters.ContainsKey($param.Key)) {
|
||||||
|
# Was set explicitly we want to use that value
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
|
||||||
|
foreach ($alias in @($Param.Key) + $param.Value.Aliases) {
|
||||||
|
if ($Module.Params.ContainsKey($alias)) {
|
||||||
|
$var_value = $Module.Params.$alias -as $param.Value.ParameterType
|
||||||
|
Set-Variable -Name $param.Key -Value $var_value
|
||||||
|
break
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
# Disable certificate validation if requested
|
||||||
|
# FUTURE: set this on ServerCertificateValidationCallback of the HttpWebRequest once .NET 4.5 is the minimum
|
||||||
|
if (-not $ValidateCerts) {
|
||||||
|
[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }
|
||||||
|
}
|
||||||
|
|
||||||
|
# Enable TLS1.1/TLS1.2 if they're available but disabled (eg. .NET 4.5)
|
||||||
|
$security_protocols = [System.Net.ServicePointManager]::SecurityProtocol -bor [System.Net.SecurityProtocolType]::SystemDefault
|
||||||
|
if ([System.Net.SecurityProtocolType].GetMember("Tls11").Count -gt 0) {
|
||||||
|
$security_protocols = $security_protocols -bor [System.Net.SecurityProtocolType]::Tls11
|
||||||
|
}
|
||||||
|
if ([System.Net.SecurityProtocolType].GetMember("Tls12").Count -gt 0) {
|
||||||
|
$security_protocols = $security_protocols -bor [System.Net.SecurityProtocolType]::Tls12
|
||||||
|
}
|
||||||
|
[System.Net.ServicePointManager]::SecurityProtocol = $security_protocols
|
||||||
|
|
||||||
|
$web_request = [System.Net.WebRequest]::Create($Uri)
|
||||||
|
if ($Method) {
|
||||||
|
$web_request.Method = $Method
|
||||||
|
}
|
||||||
|
$web_request.Timeout = $Timeout * 1000
|
||||||
|
|
||||||
|
if ($UseDefaultCredential -and $web_request -is [System.Net.HttpWebRequest]) {
|
||||||
|
$web_request.UseDefaultCredentials = $true
|
||||||
|
} elseif ($UrlUsername) {
|
||||||
|
if ($ForceBasicAuth) {
|
||||||
|
$auth_value = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $UrlUsername, $UrlPassword)))
|
||||||
|
$web_request.Headers.Add("Authorization", "Basic $auth_value")
|
||||||
|
} else {
|
||||||
|
$credential = New-Object -TypeName System.Net.NetworkCredential -ArgumentList $UrlUsername, $UrlPassword
|
||||||
|
$web_request.Credentials = $credential
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if ($ClientCert) {
|
||||||
|
# Expecting either a filepath or PSPath (Cert:\CurrentUser\My\<thumbprint>)
|
||||||
|
$cert = Get-Item -LiteralPath $ClientCert -ErrorAction SilentlyContinue
|
||||||
|
if ($null -eq $cert) {
|
||||||
|
Write-Error -Message "Client certificate '$ClientCert' does not exist" -Category ObjectNotFound
|
||||||
|
return
|
||||||
|
}
|
||||||
|
|
||||||
|
$crypto_ns = 'System.Security.Cryptography.X509Certificates'
|
||||||
|
if ($cert.PSProvider.Name -ne 'Certificate') {
|
||||||
|
try {
|
||||||
|
$cert = New-Object -TypeName "$crypto_ns.X509Certificate2" -ArgumentList @(
|
||||||
|
$ClientCert, $ClientCertPassword
|
||||||
|
)
|
||||||
|
} catch [System.Security.Cryptography.CryptographicException] {
|
||||||
|
Write-Error -Message "Failed to read client certificate at '$ClientCert'" -Exception $_.Exception -Category SecurityError
|
||||||
|
return
|
||||||
|
}
|
||||||
|
}
|
||||||
|
$web_request.ClientCertificates = New-Object -TypeName "$crypto_ns.X509Certificate2Collection" -ArgumentList @(
|
||||||
|
$cert
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
if (-not $UseProxy) {
|
||||||
|
$proxy = $null
|
||||||
|
} elseif ($ProxyUrl) {
|
||||||
|
$proxy = New-Object -TypeName System.Net.WebProxy -ArgumentList $ProxyUrl, $true
|
||||||
|
} else {
|
||||||
|
$proxy = $web_request.Proxy
|
||||||
|
}
|
||||||
|
|
||||||
|
# $web_request.Proxy may return $null for a FTP web request. We only set the credentials if we have an actual
|
||||||
|
# proxy to work with, otherwise just ignore the credentials property.
|
||||||
|
if ($null -ne $proxy) {
|
||||||
|
if ($ProxyUseDefaultCredential) {
|
||||||
|
# Weird hack, $web_request.Proxy returns an IWebProxy object which only gurantees the Credentials
|
||||||
|
# property. We cannot set UseDefaultCredentials so we just set the Credentials to the
|
||||||
|
# DefaultCredentials in the CredentialCache which does the same thing.
|
||||||
|
$proxy.Credentials = [System.Net.CredentialCache]::DefaultCredentials
|
||||||
|
} elseif ($ProxyUsername) {
|
||||||
|
$proxy.Credentials = New-Object -TypeName System.Net.NetworkCredential -ArgumentList @(
|
||||||
|
$ProxyUsername, $ProxyPassword
|
||||||
|
)
|
||||||
|
} else {
|
||||||
|
$proxy.Credentials = $null
|
||||||
|
}
|
||||||
|
|
||||||
|
$web_request.Proxy = $proxy
|
||||||
|
}
|
||||||
|
|
||||||
|
# Some parameters only apply when dealing with a HttpWebRequest
|
||||||
|
if ($web_request -is [System.Net.HttpWebRequest]) {
|
||||||
|
if ($Headers) {
|
||||||
|
foreach ($header in $Headers.GetEnumerator()) {
|
||||||
|
switch ($header.Key) {
|
||||||
|
Accept { $web_request.Accept = $header.Value }
|
||||||
|
Connection { $web_request.Connection = $header.Value }
|
||||||
|
Content-Length { $web_request.ContentLength = $header.Value }
|
||||||
|
Content-Type { $web_request.ContentType = $header.Value }
|
||||||
|
Expect { $web_request.Expect = $header.Value }
|
||||||
|
Date { $web_request.Date = $header.Value }
|
||||||
|
Host { $web_request.Host = $header.Value }
|
||||||
|
If-Modified-Since { $web_request.IfModifiedSince = $header.Value }
|
||||||
|
Range { $web_request.AddRange($header.Value) }
|
||||||
|
Referer { $web_request.Referer = $header.Value }
|
||||||
|
Transfer-Encoding {
|
||||||
|
$web_request.SendChunked = $true
|
||||||
|
$web_request.TransferEncoding = $header.Value
|
||||||
|
}
|
||||||
|
User-Agent { continue }
|
||||||
|
default { $web_request.Headers.Add($header.Key, $header.Value) }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
# For backwards compatibility we need to support setting the User-Agent if the header was set in the task.
|
||||||
|
# We just need to make sure that if an explicit http_agent module was set then that takes priority.
|
||||||
|
if ($Headers -and $Headers.ContainsKey("User-Agent")) {
|
||||||
|
if ($HttpAgent -eq $ansible_web_request_options.http_agent.default) {
|
||||||
|
$HttpAgent = $Headers['User-Agent']
|
||||||
|
} elseif ($null -ne $Module) {
|
||||||
|
$Module.Warn("The 'User-Agent' header and the 'http_agent' was set, using the 'http_agent' for web request")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
$web_request.UserAgent = $HttpAgent
|
||||||
|
|
||||||
|
switch ($FollowRedirects) {
|
||||||
|
none { $web_request.AllowAutoRedirect = $false }
|
||||||
|
safe {
|
||||||
|
if ($web_request.Method -in @("GET", "HEAD")) {
|
||||||
|
$web_request.AllowAutoRedirect = $false
|
||||||
|
} else {
|
||||||
|
$web_request.AllowAutoRedirect = $true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
all { $web_request.AllowAutoRedirect = $true }
|
||||||
|
}
|
||||||
|
|
||||||
|
if ($MaximumRedirection -eq 0) {
|
||||||
|
$web_request.AllowAutoRedirect = $false
|
||||||
|
} else {
|
||||||
|
$web_request.MaximumAutomaticRedirections = $MaximumRedirection
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
return $web_request
|
||||||
|
}
|
||||||
|
|
||||||
|
Function Invoke-WithWebRequest {
|
||||||
|
<#
|
||||||
|
.SYNOPSIS
|
||||||
|
Invokes a ScriptBlock with the WebRequest.
|
||||||
|
|
||||||
|
.DESCRIPTION
|
||||||
|
Invokes the ScriptBlock and handle extra information like accessing the response stream, closing those streams
|
||||||
|
safely as well as setting common module return values.
|
||||||
|
|
||||||
|
.PARAMETER Module
|
||||||
|
The Ansible.Basic module to set the return values for. This will set the following return values;
|
||||||
|
elapsed - The total time, in seconds, that it took to send the web request and process the response
|
||||||
|
msg - The human readable description of the response status code
|
||||||
|
status_code - An int that is the response status code
|
||||||
|
|
||||||
|
.PARAMETER Request
|
||||||
|
The System.Net.WebRequest to call. This can either be manually crafted or created with Get-AnsibleWebRequest.
|
||||||
|
|
||||||
|
.PARAMETER Script
|
||||||
|
The ScriptBlock to invoke during the web request. This ScriptBlock should take in the params
|
||||||
|
Param ([System.Net.WebResponse]$Response, [System.IO.Stream]$Stream)
|
||||||
|
|
||||||
|
This scriptblock should manage the response based on what it need to do.
|
||||||
|
|
||||||
|
.PARAMETER Body
|
||||||
|
An optional Stream to send to the target during the request.
|
||||||
|
|
||||||
|
.PARAMETER IgnoreBadResponse
|
||||||
|
By default a WebException will be raised for a non 2xx status code and the Script will not be invoked. This
|
||||||
|
parameter can be set to process all responses regardless of the status code.
|
||||||
|
|
||||||
|
.EXAMPLE Basic module that downloads a file
|
||||||
|
$spec = @{
|
||||||
|
options = @{
|
||||||
|
path = @{ type = "path"; required = $true }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
$spec.options += $ansible_web_request_options
|
||||||
|
$module = Ansible.Basic.AnsibleModule]::Create($args, $spec)
|
||||||
|
|
||||||
|
$web_request = Get-AnsibleWebRequest -Module $module
|
||||||
|
|
||||||
|
Invoke-WithWebRequest -Module $module -Request $web_request -Script {
|
||||||
|
Param ([System.Net.WebResponse]$Response, [System.IO.Stream]$Stream)
|
||||||
|
|
||||||
|
$fs = [System.IO.File]::Create($module.Params.path)
|
||||||
|
try {
|
||||||
|
$Stream.CopyTo($fs)
|
||||||
|
$fs.Flush()
|
||||||
|
} finally {
|
||||||
|
$fs.Dispose()
|
||||||
|
}
|
||||||
|
}
|
||||||
|
#>
|
||||||
|
[CmdletBinding()]
|
||||||
|
param (
|
||||||
|
[Parameter(Mandatory=$true)]
|
||||||
|
[System.Object]
|
||||||
|
[ValidateScript({ $_.GetType().FullName -eq 'Ansible.Basic.AnsibleModule' })]
|
||||||
|
$Module,
|
||||||
|
|
||||||
|
[Parameter(Mandatory=$true)]
|
||||||
|
[System.Net.WebRequest]
|
||||||
|
$Request,
|
||||||
|
|
||||||
|
[Parameter(Mandatory=$true)]
|
||||||
|
[ScriptBlock]
|
||||||
|
$Script,
|
||||||
|
|
||||||
|
[AllowNull()]
|
||||||
|
[System.IO.Stream]
|
||||||
|
$Body,
|
||||||
|
|
||||||
|
[Switch]
|
||||||
|
$IgnoreBadResponse
|
||||||
|
)
|
||||||
|
|
||||||
|
$start = Get-Date
|
||||||
|
if ($null -ne $Body) {
|
||||||
|
$request_st = $Request.GetRequestStream()
|
||||||
|
try {
|
||||||
|
$Body.CopyTo($request_st)
|
||||||
|
$request_st.Flush()
|
||||||
|
} finally {
|
||||||
|
$request_st.Close()
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
try {
|
||||||
|
try {
|
||||||
|
$web_response = $Request.GetResponse()
|
||||||
|
} catch [System.Net.WebException] {
|
||||||
|
# A WebResponse with a status code not in the 200 range will raise a WebException. We check if the
|
||||||
|
# exception raised contains the actual response and continue on if IgnoreBadResponse is set. We also
|
||||||
|
# make sure we set the status_code return value on the Module object if possible
|
||||||
|
|
||||||
|
if ($_.Exception.PSObject.Properties.Name -match "Response") {
|
||||||
|
$web_response = $_.Exception.Response
|
||||||
|
|
||||||
|
if (-not $IgnoreBadResponse -or $null -eq $web_response) {
|
||||||
|
$Module.Result.msg = $_.Exception.StatusDescription
|
||||||
|
$Module.Result.status_code = $_.Exception.Response.StatusCode
|
||||||
|
throw $_
|
||||||
|
}
|
||||||
|
} else {
|
||||||
|
throw $_
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if ($Request.RequestUri.IsFile) {
|
||||||
|
# A FileWebResponse won't have these properties set
|
||||||
|
$Module.Result.msg = "OK"
|
||||||
|
$Module.Result.status_code = 200
|
||||||
|
} else {
|
||||||
|
$Module.Result.msg = $web_response.StatusDescription
|
||||||
|
$Module.Result.status_code = $web_response.StatusCode
|
||||||
|
}
|
||||||
|
|
||||||
|
$response_stream = $web_response.GetResponseStream()
|
||||||
|
try {
|
||||||
|
# Invoke the ScriptBlock and pass in WebResponse and ResponseStream
|
||||||
|
&$Script -Response $web_response -Stream $response_stream
|
||||||
|
} finally {
|
||||||
|
$response_stream.Dispose()
|
||||||
|
}
|
||||||
|
} finally {
|
||||||
|
if ($web_response) {
|
||||||
|
$web_response.Close()
|
||||||
|
}
|
||||||
|
$Module.Result.elapsed = ((Get-date) - $start).TotalSeconds
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
$ansible_web_request_options = @{
|
||||||
|
url = @{ type="str"; required=$true }
|
||||||
|
method = @{ type="str" }
|
||||||
|
follow_redirects = @{ type="str"; choices=@("all","none","safe"); default="safe" }
|
||||||
|
headers = @{ type="dict" }
|
||||||
|
http_agent = @{ type="str"; default="ansible-httpget" }
|
||||||
|
maximum_redirection = @{ type="int"; default=50 }
|
||||||
|
timeout = @{ type="int"; default=30 } # Was defaulted to 10 in win_get_url but 30 in win_uri so we use 30
|
||||||
|
validate_certs = @{ type="bool"; default=$true }
|
||||||
|
|
||||||
|
# Credential options
|
||||||
|
client_cert = @{ type="str" }
|
||||||
|
client_cert_password = @{ type="str"; no_log=$true }
|
||||||
|
force_basic_auth = @{ type="bool"; default=$false }
|
||||||
|
url_username = @{ type="str"; aliases=@("user", "username") } # user was used in win_uri
|
||||||
|
url_password = @{ type="str"; aliases=@("password"); no_log=$true }
|
||||||
|
use_default_credential = @{ type="bool"; default=$false }
|
||||||
|
|
||||||
|
# Proxy options
|
||||||
|
use_proxy = @{ type="bool"; default=$true }
|
||||||
|
proxy_url = @{ type="str" }
|
||||||
|
proxy_username = @{ type="str" }
|
||||||
|
proxy_password = @{ type="str"; no_log=$true }
|
||||||
|
proxy_use_default_credential = @{ type="bool"; default=$false }
|
||||||
|
}
|
||||||
|
|
||||||
|
$export_members = @{
|
||||||
|
Function = "Get-AnsibleWebRequest", "Invoke-WithWebRequest"
|
||||||
|
Variable = "ansible_web_request_options"
|
||||||
|
}
|
||||||
|
Export-ModuleMember @export_members
|
@ -0,0 +1,164 @@
|
|||||||
|
# -*- coding: utf-8 -*-
|
||||||
|
|
||||||
|
# Copyright (c) 2019 Ansible Project
|
||||||
|
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
|
||||||
|
|
||||||
|
from __future__ import (absolute_import, division, print_function)
|
||||||
|
__metaclass__ = type
|
||||||
|
|
||||||
|
|
||||||
|
class ModuleDocFragment(object):
|
||||||
|
|
||||||
|
# Standard files documentation fragment
|
||||||
|
DOCUMENTATION = r'''
|
||||||
|
options:
|
||||||
|
url:
|
||||||
|
description:
|
||||||
|
- The URL to make the request with.
|
||||||
|
required: yes
|
||||||
|
type: str
|
||||||
|
method:
|
||||||
|
description:
|
||||||
|
- The HTTP Method of the request.
|
||||||
|
type: str
|
||||||
|
follow_redirects:
|
||||||
|
description:
|
||||||
|
- Whether or the module should follow redirects.
|
||||||
|
- C(all) will follow all redirect.
|
||||||
|
- C(none) will not follow any redirect.
|
||||||
|
- C(safe) will follow only "safe" redirects, where "safe" means that the
|
||||||
|
client is only doing a C(GET) or C(HEAD) on the URI to which it is being
|
||||||
|
redirected.
|
||||||
|
choices:
|
||||||
|
- all
|
||||||
|
- none
|
||||||
|
- safe
|
||||||
|
default: safe
|
||||||
|
type: str
|
||||||
|
headers:
|
||||||
|
description:
|
||||||
|
- Extra headers to set on the request.
|
||||||
|
- This should be a dictionary where the key is the header name and the
|
||||||
|
value is the value for that header.
|
||||||
|
type: dict
|
||||||
|
http_agent:
|
||||||
|
description:
|
||||||
|
- Header to identify as, generally appears in web server logs.
|
||||||
|
- This is set to the C(User-Agent) header on a HTTP request.
|
||||||
|
default: ansible-httpget
|
||||||
|
type: str
|
||||||
|
version_added: "2.9"
|
||||||
|
maximum_redirection:
|
||||||
|
description:
|
||||||
|
- Specify how many times the module will redirect a connection to an
|
||||||
|
alternative URI before the connection fails.
|
||||||
|
- If set to C(0) or I(follow_redirects) is set to C(none), or C(safe) when
|
||||||
|
not doing a C(GET) or C(HEAD) it prevents all redirection.
|
||||||
|
default: 50
|
||||||
|
type: int
|
||||||
|
timeout:
|
||||||
|
description:
|
||||||
|
- Specifies how long the request can be pending before it times out (in
|
||||||
|
seconds).
|
||||||
|
- Set to C(0) to specify an infinite timeout.
|
||||||
|
default: 30
|
||||||
|
type: int
|
||||||
|
version_added: "2.4"
|
||||||
|
validate_certs:
|
||||||
|
description:
|
||||||
|
- If C(no), SSL certificates will not be validated.
|
||||||
|
- This should only be used on personally controlled sites using self-signed
|
||||||
|
certificates.
|
||||||
|
default: yes
|
||||||
|
type: bool
|
||||||
|
version_added: "2.4"
|
||||||
|
client_cert:
|
||||||
|
description:
|
||||||
|
- The path to the client certificate (.pfx) that is used for X509
|
||||||
|
authentication. This path can either be the path to the C(pfx) on the
|
||||||
|
filesystem or the PowerShell certificate path
|
||||||
|
C(Cert:\CurrentUser\My\<thumbprint>).
|
||||||
|
- The WinRM connection must be authenticated with C(CredSSP) or C(become)
|
||||||
|
is used on the task if the certificate file is not password protected.
|
||||||
|
- Other authentication types can set I(client_cert_password) when the cert
|
||||||
|
is password protected.
|
||||||
|
type: str
|
||||||
|
client_cert_password:
|
||||||
|
description:
|
||||||
|
- The password for I(client_cert) if the cert is password protected.
|
||||||
|
type: str
|
||||||
|
force_basic_auth:
|
||||||
|
description:
|
||||||
|
- By default the authentication header is only sent when a webservice
|
||||||
|
responses to an initial request with a 401 status. Since some basic auth
|
||||||
|
services do not properly send a 401, logins will fail.
|
||||||
|
- This option forces the sending of the Basic authentication header upon
|
||||||
|
the original request.
|
||||||
|
default: no
|
||||||
|
type: bool
|
||||||
|
version_added: "2.5"
|
||||||
|
url_username:
|
||||||
|
description:
|
||||||
|
- The username to use for authentication.
|
||||||
|
type: str
|
||||||
|
aliases:
|
||||||
|
- user
|
||||||
|
- username
|
||||||
|
url_password:
|
||||||
|
description:
|
||||||
|
- The password for I(url_username).
|
||||||
|
type: str
|
||||||
|
aliases:
|
||||||
|
- password
|
||||||
|
use_default_credential:
|
||||||
|
description:
|
||||||
|
- Uses the current user's credentials when authenticating with a server
|
||||||
|
protected with C(NTLM), C(Kerberos), or C(Negotiate) authentication.
|
||||||
|
- Sites that use C(Basic) auth will still require explicit credentials
|
||||||
|
through the I(url_username) and I(url_password) options.
|
||||||
|
- The module will only have access to the user's credentials if using
|
||||||
|
C(become) with a password, you are connecting with SSH using a password,
|
||||||
|
or connecting with WinRM using C(CredSSP) or C(Kerberos with delegation).
|
||||||
|
- If not using C(become) or a different auth method to the ones stated
|
||||||
|
above, there will be no default credentials available and no
|
||||||
|
authentication will occur.
|
||||||
|
default: no
|
||||||
|
type: bool
|
||||||
|
version_added: "2.9"
|
||||||
|
use_proxy:
|
||||||
|
description:
|
||||||
|
- If C(no), it will not use the proxy defined in IE for the current user.
|
||||||
|
default: yes
|
||||||
|
type: bool
|
||||||
|
proxy_url:
|
||||||
|
description:
|
||||||
|
- An explicit proxy to use for the request.
|
||||||
|
- By default, the request will use the IE defined proxy unless I(use_proxy)
|
||||||
|
is set to C(no).
|
||||||
|
type: str
|
||||||
|
proxy_username:
|
||||||
|
description:
|
||||||
|
- The username to use for proxy authentication.
|
||||||
|
type: str
|
||||||
|
proxy_password:
|
||||||
|
description:
|
||||||
|
- The password for I(proxy_username).
|
||||||
|
type: str
|
||||||
|
proxy_use_default_credential:
|
||||||
|
description:
|
||||||
|
- Uses the current user's credentials when authenticating with a proxy host
|
||||||
|
protected with C(NTLM), C(Kerberos), or C(Negotiate) authentication.
|
||||||
|
- Proxies that use C(Basic) auth will still require explicit credentials
|
||||||
|
through the I(proxy_username) and I(proxy_password) options.
|
||||||
|
- The module will only have access to the user's credentials if using
|
||||||
|
C(become) with a password, you are connecting with SSH using a password,
|
||||||
|
or connecting with WinRM using C(CredSSP) or C(Kerberos with delegation).
|
||||||
|
- If not using C(become) or a different auth method to the ones stated
|
||||||
|
above, there will be no default credentials available and no proxy
|
||||||
|
authentication will occur.
|
||||||
|
default: no
|
||||||
|
type: bool
|
||||||
|
version_added: "2.9"
|
||||||
|
seealso:
|
||||||
|
- module: win_inet_proxy
|
||||||
|
'''
|
Loading…
Reference in New Issue