# win_credential – Manages Windows Credentials in the Credential Manager

New in version 2.8.

- 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 - |  | 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

See also

win_user_right – Manage Windows User Rights

  The official documentation on the win_user_right module.

win_whoami – Get information about the current user and process

  The official documentation on the win_whoami module.

## Examples

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

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

    - name: Create a credential with full values
      win_credential:
        name: server.domain.com
        type: domain_password
        alias: server
        username: username@DOMAIN.COM
        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
      win_credential:
        name: '*.domain.com'
        type: domain_certificate
        username: 0074CC4F200D27DC3877C24A92BA8EA21E6C7AF4
        state: present

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

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

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Jordan Borean (@jborean93)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.