ansible.posix.authorized_key module – Adds or removes an SSH authorized key

ansible.posix.authorized_key module – Adds or removes an SSH authorised key

https://docs.ansible.com/projects/ansible/latest/collections/ansible/posix/authorized_key_module.html

Note

This module is part of the ansible.posix collection (version 2.1.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 ansible.posix.

To use it in a playbook, specify: ansible.posix.authorized_key.

New in ansible.posix 1.0.0

Synopsis

Parameters

Examples

Return Values

Synopsis Adds or removes SSH authorised keys for particular user accounts.

Parameters Parameter

Comments

comment string

Change the comment on the public key.

Rewriting the comment is useful in cases such as fetching it from GitHub or GitLab.

If no comment is specified, the existing comment will be kept.

exclusive boolean

Whether to remove all other non-specified keys from the authorized_keys file.

Multiple keys can be specified in a single key string value by separating them by newlines.

This option is not loop aware, so if you use with_ , it will be exclusive per iteration of the loop.

If you want multiple keys in the file you need to pass them all to key in a single batch as mentioned above.

Choices:

false ← (default)

true

follow boolean

Follow path symlink instead of replacing it.

Choices:

false ← (default)

true

key string / required

The SSH public key(s), as a string or (since Ansible 1.9) url (https://github.com/username.keys).

You can also use file:// prefix to search remote for a file with SSH key(s).

key_options string

A string of ssh key options to be prepended to the key in the authorized_keys file.

manage_dir boolean

Whether this module should manage the directory of the authorised key file.

If set to true, the module will create the directory, as well as set the owner and permissions of an existing directory.

Be sure to set manage_dir=false if you are using an alternate directory for authorized_keys, as set with path, since you could lock yourself out of SSH access.

See the example below.

Choices:

false

true ← (default)

path path

Alternative path to the authorized_keys file.

The default value is the .ssh/authorized_keys of the home of the user specified in the user parameter.

Most of the time, it is not necessary to set this key.

Use the path to your target authorized_keys if you need to explicitly point on it.

state string

Whether the given key (with the given key_options) should or should not be in the file.

Choices:

“absent”

“present” ← (default)

user string / required

The username on the remote host whose authorized_keys file will be modified.

validate_certs boolean

This only applies if using a https url as the source of the keys.

If set to false, the SSL certificates will not be validated.

This should only set to false used on personally controlled sites using self-signed certificates as it avoids verifying the source site.

Prior to 2.1 the code worked as if this was set to true.

Choices:

false

true ← (default)

Examples

• name: Set authorised key taken from file ansible.posix.authorized_key: user: charlie state: present key: “{{ lookup(‘file’, ‘/home/charlie/.ssh/id_rsa.pub’) }}”

• name: Set authorised keys taken from url ansible.posix.authorized_key: user: charlie state: present key: https://github.com/charlie.keys

• name: Set authorised keys taken from path on controller node ansible.posix.authorized_key: user: charlie state: present key: file:///home/charlie/.ssh/id_rsa.pub

• name: Set authorised keys taken from url using lookup ansible.posix.authorized_key: user: charlie state: present key: “{{ lookup(‘url’, ‘https://github.com/charlie.keys’, split_lines=False) }}”

• name: Set authorised key in alternate location ansible.posix.authorized_key: user: charlie state: present key: “{{ lookup(‘file’, ‘/home/charlie/.ssh/id_rsa.pub’) }}” path: /etc/ssh/authorized_keys/charlie manage_dir: false

• name: Set up multiple authorised keys ansible.posix.authorized_key: user: deploy state: present key: ‘{{ item }}’ with_file:
  • public_keys/doe-jane
  • public_keys/doe-john

• name: Set authorised key defining key options ansible.posix.authorized_key: user: charlie state: present key: “{{ lookup(‘file’, ‘/home/charlie/.ssh/id_rsa.pub’) }}” key_options: ‘no-port-forwarding,from=”10.0.1.1”’

• name: Set authorised key without validating the TLS/SSL certificates ansible.posix.authorized_key: user: charlie state: present key: https://github.com/user.keys validate_certs: false

• name: Set authorised key, removing all the authorised keys already set ansible.posix.authorized_key: user: root key: “{{ lookup(‘file’, ‘public_keys/doe-jane’) }}” state: present exclusive: true

• name: Set authorised key for user ubuntu copying it from current user ansible.posix.authorized_key: user: ubuntu state: present key: “{{ lookup(‘file’, lookup(‘env’,’HOME’) + ‘/.ssh/id_rsa.pub’) }}” Return Values Common return values are documented here, the following are the fields unique to this module:

Key

Description

exclusive boolean

If the key has been forced to be exclusive or not.

Returned: success

Sample: false

key string

The key that the module was running against.

Returned: success

Sample: “https://github.com/user.keys”

key_option string

Key options related to the key.

Returned: success

keyfile string

Path for authorised key file.

Returned: success

Sample: “/home/user/.ssh/authorized_keys”

manage_dir boolean

Whether this module managed the directory of the authorised key file.

Returned: success

Sample: true

path string

Alternate path to the authorized_keys file

Returned: success

state string

Whether the given key (with the given key_options) should or should not be in the file

Returned: success

Sample: “present”

unique boolean

Whether the key is unique

Returned: success

Sample: false

user string

The username on the remote host whose authorized_keys file will be modified

Returned: success

Sample: “user”

validate_certs boolean

This only applies if using a https url as the source of the keys. If set to false, the SSL certificates will not be validated.

Returned: success

Sample: true

Authors Ansible Core Team

Collection links Issue Tracker Repository (Sources) © Copyright Ansible project contributors. Last updated on Dec 29, 2025.