Configuring Ansible

To configure Ansible for the integration, you must create an Ansible playbook (a YAML file). In the playbook, you provide the information need to connect to Secret Server or the Delinea Platform and the information that specifies the secret data (credentials) that you want to retrieve from Secret Server or Secret Server on the Delinea Platform.

The following sections detail how to perform the sequential steps involved in creating an Ansible playbook for your use case:

  1. Create a playbook (a YAML file).

  2. Modify the playbook for your use case.

Creating a Playbook

The following procedure describes how to create an Ansible playbook (a YAML file) for the different supported use cases. The "Examples" section of the tss document in the Ansible Galaxy repository or the "Examples" section of the tss.py file in the Ansible Community General Collection GitHub repository provides an example of a playbook that includes plays for the different use cases. The procedure specifies which play to use for which use case.

To create a playbook:

  1. Create a YAML file for your playbook (for example, playbook.yaml).

  2. Depending on your use case and whether you integrate Ansible with Secret Server or the Delinea Platform, copy the appropriate play from the example playbook into your YAML file.

    Ansible-Secret Server integration

    Use Case Copy This Play from the Example Playbook
    Retrieve credentials from Secret Server by secret ID (if using application account credentials for authentication) The first play under # Using Secret Server Authentication in the "Examples" section.
    Retrieve credentials from Secret Server by secret ID (if using application account credentials for authentication, and using a domain user) The second play under # Using Secret Server Authentication in the "Examples" section.
    Retrieve credentials from Secret Server by secret ID (if using an access token for authentication) The third play under # Using Secret Server Authentication in the "Examples" section.
    Retrieve the secret IDs from a folder in Secret Server by folder ID (if using an access token for authentication) The play under #If fetch_secret_ids_from_folder=true then secret IDs are in a folder is fetched based on folder ID in the "Examples" section.
    Retrieve credentials from Secret Server by secret path (if using application account credentials for authentication) The play under # If secret ID is 0 and secret_path has value then secret is fetched by secret path in the "Examples" section.

    Ansible-Delinea Platform integration

    Use Case Copy This Play from the Example Playbook
    Retrieve credentials from the Delinea Platform by secret ID (if using service user credentials for authentication) The first play under # Using Platform Authentication in the "Examples" section.
    Retrieve credentials from the Delinea Platform by secret ID (if using an access token for authentication) The second play under # Using Platform Authentication in the "Examples" section.

Modifying the Playbook for Your Use Case

After you create a playbook for this integration, you must modify the parameters in the playbook for your use case. The following procedure describes how to set the parameters in the playbook for the different supported use cases.

To modify the playbook:

  1. Open the playbook YAML file.

  2. Set the parameters in vars for your use case as follows:

    Use case: Retrieve credentials from Secret Server or Secret Server on the Delinea Platform by secret ID

    Parameter Required? Parameter Value
    'delinea.ss.tss' Yes

    This is a reference to the Delinea Ansible collection. Don't change this parameter.
    <secret ID> | <folder ID> * Yes

    Set the parameter to the ID of the secret from which you want to retrieve the credentials.
    base_url Yes

    Secret Server

    The URL of your Secret Server instance (for example, https://secretserver.domain.com/SecretServer/).

    Delinea Platform

    The URL of your Delinea Platform instance (for example, https://platform.delinea.app/)

    username No

    If you use token-based authentication, omit this parameter.

    Secret Server

    The username of the Secret Server application account.

    Delinea Platform

    The username of the Delinea Platform service user.
    password No

    If you use token-based authentication, omit this parameter.

    Secret Server

    The password of the Secret Server application account.

    Delinea Platform

    The password of the Delinea Platform service user.
    domain No

    Omit this parameter if:

    • You integrate Ansible with Secret Server and don't use a domain user.

    • You integrate Ansible with the Delinea Platform.

    • If you use an access token to authenticate with Secret Server or the Delinea Platform.

    If you use a domain user in Secret Server for authentication, set this parameter to the domain name.
    token No

    If you don't use token-based authentication, omit this parameter.

    If you use an access token to authenticate with Secret Server or the Delinea Platform, set this parameter to an access token.
    secret_path No

    Omit this parameter.
    fetch_secret_ids_from_folder No

    Omit this parameter.

     
    comment No A comment to provide when retrieving the secret. The comment will be logged as an audit trail entry for tracking acess to the secret. If the Require comment setting is enabled for the secret in Secret Server, provide a comment. If Require comment is disabled for the secret, omit this parameter.

    Use case: Retrieve credentials from Secret Server or Secret Server on the Delinea Platform by secret path

    Parameter Required? Parameter Value
    'delinea.ss.tss' Yes

    This is a reference to the Delinea Ansible collection. Don't change this parameter.
    <secret ID> | <folder ID> * Yes

    Set the parameter to 0.
    base_url Yes

    Secret Server

    The URL of your Secret Server instance (for example, https://secretserver.domain.com/SecretServer/).

    Delinea Platform

    The URL of your Delinea Platform instance (for example, https://platform.delinea.app/).
    username No

    If you use token-based authentication, omit this parameter.

    Secret Server

    The username of the Secret Server application account.

    Delinea Platform

    The username of the Delinea Platform service user.
    password No

    If you use token-based authentication, omit this parameter.

    Secret Server

    The password of the Secret Server application account.

    Delinea Platform

    The password of the Delinea Platform service user.
    domain No

    Omit this parameter if:

    • You integrate Ansible with Secret Server and don't use a domain user.

    • You integrate Ansible with the Delinea Platform.

    • If you use an access token to authenticate with Secret Server or the Delinea Platform.

    If you use a domain user in Secret Server for authentication, set this parameter to the domain name.
    token No

    If you don't use token-based authentication, omit this parameter.

    If you use an access token to authenticate with Secret Server or the Delinea Platform, set this parameter to an access token.
    secret_path No

    Set this parameter to the full path of the secret in Secret Server or the Delinea Platform.
    fetch_secret_ids_from_folder No

    Omit this parameter.
    comment No A comment to provide when retrieving the secret. The comment will be logged as an audit trail entry for tracking acess to the secret. If the Require comment setting is enabled for the secret in Secret Server, provide a comment. If Require comment is disabled for the secret, omit this parameter.

    Use case: Retrieve secret IDs from a folder in Secret Server or Secret Server on the Delinea Platform by folder ID

    Parameter Required? Parameter Value
    'delinea.ss.tss' Yes

    This is a reference to the Delinea Ansible collection. Don't change this parameter.
    <secret ID> | <folder ID> * Yes

    Set the parameter to the ID of the folder from which you want to retrieve the secret IDs.
    base_url Yes

    Secret Server

    The URL of your Secret Server instance (for example, https://secretserver.domain.com/SecretServer/).

    Delinea Platform

    The URL of your Delinea Platform instance (for example, https://platform.delinea.app/) .
    username No

    If you use token-based authentication, omit this parameter.

    Secret Server

    The username of the Secret Server application account.

    Delinea Platform

    The username of the Delinea Platform service user.
    password No

    If you use token-based authentication, omit this parameter.

    Secret Server

    The password of the Secret Server application account.

    Delinea Platform

    The password of the Delinea Platform service user.
    domain No

    Omit this parameter if:

    • You integrate Ansible with Secret Server and don't use a domain user.

    • You integrate Ansible with the Delinea Platform.

    • If you use an access token to authenticate with Secret Server or the Delinea Platform.

    If you use a domain user in Secret Server for authentication, set this parameter to the domain name.
    token No

    If you don't use token-based authentication, omit this parameter.

    If you use an access token to authenticate with Secret Server or the Delinea Platform, set this parameter to an access token.
    secret_path No

    Omit this parameter.
    fetch_secret_ids_from_folder No

    Set the parameter to true.

    comment No A comment to provide when retrieving the secret. The comment will be logged as an audit trail entry for tracking acess to the secret. If the Require comment setting is enabled for the secret in Secret Server, provide a comment. If Require comment is disabled for the secret, omit this parameter.
    * Tips:

    • To find the secret ID, navigate to the secret details page and note the secret ID in the URL at the top (it appears after secrets/ in the URL).

    • To find the folder ID, navigate to the folder details page and note the folder ID in the URL at the top (it appears after detail/ in the URL).

    For a complete list of the parameters available for your playbooks from the Delinea Ansible collection and their descriptions, see the "Parameters" section in the tss document in Ansible Galaxy or the "Parameters" section in the tss.py file in the Ansible Community General Collection repository.

  3. Under tasks, add a task to specify the type of secret data that you want to retrieve from Secret Server for your use case as follows.

    Use case Type of secret data to retrieve How to modify tasks in the playbook
    Retrieve credentials by secret ID Username, password, or both user name and password

    Include password, username, or both password and username in the module referenced by the task.

    For example, if your task references the ansible.builtin.debug module and you include password in the msg parameter, the password retrieved from the specified secret will be printed in a message after the task is executed. See this example of tasks under # Using Secret Server Authentication in the "Examples" section of the example playbook in the tss document.
    Retrieve credentials by secret path Username, password, or both user name and password

    Include password, username, or both password and username in the module referenced by the task.

    For example, if your task references the ansible.builtin.debug module and you include password in the msg parameter, the password retrieved from the secret in the specified secret path will be printed in a message after the task is executed. See this example of tasks under # If secret ID is 0 and secret_path has value then secret is fetched by secret path in the "Examples" section of the example playbook in the tss document.
    Retrieve secret IDs from a folder by folder ID Secret IDs

    Include secret in the module referenced by the task.

    For example, if your task references the ansible.builtin.debug module and you include secret in the msg parameter, the secret IDs from the specified folder will be printed in a message after the task is executed. See this example of tasks under # If fetch_secret_ids_from_folder=true then secret IDs are in a folder is fetched based on folder ID in the "Examples" section of the example playbook in the tss document.