community.windows.win_credential_module.rst

community.windows.win_credential

Manages Windows Credentials in the Credential Manager

• Synopsis
• Parameters
• Notes
• See Also
• Examples
• Status

Synopsis

• Used to create and remove Windows Credentials in the Credential Manager.
• This module can manage both standard username/password credentials as well as certificate credentials.

Parameters

Parameter		Choices/Defaults	Comments
alias string			Adds an alias for the credential. Typically this is the NetBIOS name of a host if name is set to the DNS name.
attributes list / elements=dictionary			A list of dicts that set application specific attributes for a credential. When set, existing attributes will be compared to the list as a whole, any differences means all attributes will be replaced.
	data string		The value for the attribute.
	data_format string	Choices: base64 text ←	Controls the input type for data. If text, data is a text string that is UTF-16LE encoded to bytes. If base64, data is a base64 string that is base64 decoded to bytes.
	name string / required		The key for the attribute. This is not a unique identifier as multiple attributes can have the same key.
comment string			A user defined comment for the credential.
name string / required			The target that identifies the server or servers that the credential is to be used for. If the value can be a NetBIOS name, DNS server name, DNS host name suffix with a wildcard character (*), a NetBIOS of DNS domain name that contains a wildcard character sequence, or an asterisk. See TargetName in https://docs.microsoft.com/en-us/windows/desktop/api/wincred/ns-wincred-_credentiala for more details on what this value can be. This is used with type to produce a unique credential.
persistence string		Choices: enterprise local ←	Defines the persistence of the credential. If local, the credential will persist for all logons of the same user on the same host. enterprise is the same as local but the credential is visible to the same domain user when running on other hosts and not just localhost.
secret string			The secret for the credential. When omitted, then no secret is used for the credential if a new credentials is created. When type is a password type, this is the password for username. When type is a certificate type, this is the pin for the certificate.
secret_format string		Choices: base64 text ←	Controls the input type for secret. If text, secret is a text string that is UTF-16LE encoded to bytes. If base64, secret is a base64 string that is base64 decoded to bytes.
state string		Choices: absent present ←	When absent, the credential specified by name and type is removed. When present, the credential specified by name and type is removed.
type string / required		Choices: domain_certificate domain_password generic_certificate generic_password	The type of credential to store. This is used with name to produce a unique credential. When the type is a domain type, the credential is used by Microsoft authentication packages like Negotiate. When the type is a generic type, the credential is not used by any particular authentication package. It is recommended to use a domain type as only authentication providers can access the secret.
update_secret string		Choices: always ← on_create	When always, the secret will always be updated if they differ. When on_create, the secret will only be checked/updated when it is first created. If the secret cannot be retrieved and this is set to always, the module will always result in a change.
username string			When type is a password type, then this is the username to store for the credential. When type is a credential type, then this is the thumbprint as a hex string of the certificate to use. When type=domain_password, this should be in the form of a Netlogon (DOMAIN\Username) or a UPN (username@DOMAIN). If using a certificate thumbprint, the certificate must exist in the CurrentUser\My certificate store for the executing user.

Notes

Note

• This module requires to be run with become so it can access the user's credential store.
• There can only be one credential per host and type. if a second credential is defined that uses the same host and type, then the original credential is overwritten.

See Also

.. seealso::

   :ref:`ansible.windows.win_user_right_module`
      The official documentation on the **ansible.windows.win_user_right** module.
   :ref:`ansible.windows.win_whoami_module`
      The official documentation on the **ansible.windows.win_whoami** module.

Examples

- name: Create a local only credential
  community.windows.win_credential:
    name: server.domain.com
    type: domain_password
    username: DOMAIN\username
    secret: Password01
    state: present

- name: Remove a credential
  community.windows.win_credential:
    name: server.domain.com
    type: domain_password
    state: absent

- name: Create a credential with full values
  community.windows.win_credential:
    name: server.domain.com
    type: domain_password
    alias: server
    username: [email protected]
    secret: Password01
    comment: Credential for server.domain.com
    persistence: enterprise
    attributes:
    - name: Source
      data: Ansible
    - name: Unique Identifier
      data: Y3VzdG9tIGF0dHJpYnV0ZQ==
      data_format: base64

- name: Create a certificate credential
  community.windows.win_credential:
    name: '*.domain.com'
    type: domain_certificate
    username: 0074CC4F200D27DC3877C24A92BA8EA21E6C7AF4
    state: present

- name: Create a generic credential
  community.windows.win_credential:
    name: smbhost
    type: generic_password
    username: smbuser
    secret: smbuser
    state: present

- name: Remove a generic credential
  community.windows.win_credential:
    name: smbhost
    type: generic_password
    state: absent

Status

Authors

• Jordan Borean (@jborean93)