microsoft.iis.authentication module – Configures authentication options in IIS

Note

This module is part of the microsoft.iis collection (version 1.3.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install microsoft.iis.

To use it in a playbook, specify: microsoft.iis.authentication.

New in microsoft.iis 1.3.0

Synopsis

  • Adds or modifies authentication options in IIS, including WindowsAuthentication and its providers.

Parameters

Parameter

Comments

application

string

The name of an application or virtual directory under site to configure.

When omitted the configuration is applied at the site root.

auth_type

string / required

The IIS authentication type to configure.

Each value maps to a child section of system.webServer/security/authentication.

Choices:

  • "AnonymousAuthentication"

  • "BasicAuthentication"

  • "ClientCertificateMappingAuthentication"

  • "DigestAuthentication"

  • "IISClientCertificateMappingAuthentication"

  • "WindowsAuthentication"

enabled

boolean

Whether the authentication type is enabled.

When omitted the current value on the target is preserved.

Choices:

  • false

  • true

providers

list / elements=string

The ordered list of providers for auth_type=WindowsAuthentication.

For example Negotiate and NTLM.

Only valid with auth_type=WindowsAuthentication.

When omitted the current providers on the target are preserved.

site

string / required

The name of the IIS site to configure, for example Default Web Site.

The module resolves the site to the underlying IIS configuration path automatically.

token_checking

string

The TokenChecking value for the auth_type=WindowsAuthentication extended protection setting.

The valid values are None, Allow and Require.

Only valid with auth_type=WindowsAuthentication.

When omitted the current value on the target is preserved.

Choices:

  • "None"

  • "Allow"

  • "Require"

use_kernel_mode

boolean

Whether kernel-mode authentication is enabled for auth_type=WindowsAuthentication.

Only valid with auth_type=WindowsAuthentication.

When omitted the current value on the target is preserved.

Choices:

  • false

  • true

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.

diff_mode

Support: full

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode

platform

Platform: windows

Target OS/families that can be operated against

See Also

See also

microsoft.iis.website

Configures an IIS website.

Examples

- name: Configure Windows Authentication on a site
  microsoft.iis.authentication:
    site: Default Web Site
    auth_type: WindowsAuthentication
    enabled: true
    providers:
      - Negotiate
      - NTLM
    use_kernel_mode: false
    token_checking: None

- name: Enable Anonymous Authentication without changing other settings
  microsoft.iis.authentication:
    site: Default Web Site
    auth_type: AnonymousAuthentication
    enabled: true

- name: Update only the providers and preserve the other Windows Authentication settings
  microsoft.iis.authentication:
    site: Default Web Site
    auth_type: WindowsAuthentication
    providers:
      - Negotiate

- name: Configure Windows Authentication on an application under a site
  microsoft.iis.authentication:
    site: Default Web Site
    application: MyApp
    auth_type: WindowsAuthentication
    enabled: true

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

target

string

The resolved IIS configuration path the authentication configuration was applied to.

Returned: always

Sample: "IIS:\\Sites\\Default Web Site"

Authors

  • Justin Cook (@ch0nx)