..
.. SPDX-License-Identifier: Apache-2.0
..

:github_url: https://github.com/IBM-Blockchain/ansible-collection/edit/main/plugins/modules/enrolled_identity.py


enrolled_identity -- Manage an enrolled Hyperledger Fabric identity
===================================================================

.. contents::
   :local:
   :depth: 1


Synopsis
--------

Enroll, re-enroll, or delete an enrolled Hyperledger Fabric identity by using the IBM Blockchain Platform.

This module works with the IBM Blockchain Platform managed service running in IBM Cloud, or the IBM Blockchain Platform software running in a Red Hat OpenShift or Kubernetes cluster.






Parameters
----------

  api_endpoint (required)
    The URL for the IBM Blockchain Platform console.

    | **Type**: str

  api_authtype (required)
    ``ibmcloud`` - Authenticate to the IBM Blockchain Platform console using IBM Cloud authentication. You must provide a valid API key using *api_key*.

    ``basic`` - Authenticate to the IBM Blockchain Platform console using basic authentication. You must provide both a valid API key using *api_key* and API secret using *api_secret*.

    | **Type**: str

  api_key (required)
    The API key for the IBM Blockchain Platform console.

    | **Type**: str

  api_secret
    The API secret for the IBM Blockchain Platform console.

    Only required when *api_authtype* is ``basic``.

    | **Type**: str

  api_timeout
    The timeout, in seconds, to use when interacting with the IBM Blockchain Platform console.

    | **Type**: int
    | **Default value**: ``60``

  api_token_endpoint
    The IBM Cloud IAM token endpoint to use when using IBM Cloud authentication.

    Only required when *api_authtype* is ``ibmcloud``, and you are using IBM internal staging servers for testing.

    | **Type**: str
    | **Default value**: ``https://iam.cloud.ibm.com/identity/token``

  state
    ``absent`` - A certificate authority matching the specified name will be stopped and removed.

    ``present`` - Asserts that a certificate authority matching the specified name and configuration exists. If no certificate authority matches the specified name, a certificate authority will be created. If a certificate authority matches the specified name but the configuration does not match, then the certificate authority will be updated, if it can be. If it cannot be updated, it will be removed and re-created with the specified configuration.

    | **Type**: str
    | **Default value**: ``present``

  certificate_authority
    The certificate authority to use to enroll this identity.

    You can pass a string, which is the display name of a certificate authority registered with the IBM Blockchain Platform console.

    You can also pass a dictionary, which must match the result format of one of the :ref:`certificate_authority_info <certificate_authority_info_module>` or :ref:`certificate_authority <certificate_authority_module>` modules.

    Only required when *state* is ``present``.

    | **Type**: raw

  name
    The name of the enrolled identity.

    Only required when *state* is ``present``.

    | **Type**: str

  enrollment_id
    The enrollment ID, or user name, of an identity registered on the certificate authority for this peer.

    Only required when *state* is ``present``.

    | **Type**: str

  enrollment_secret
    The enrollment secret, or password, of an identity registered on the certificate authority for this peer.

    Only required when *state* is ``present``.

    | **Type**: str

  path (required)
    The path to the JSON file where the enrolled identity will be stored.


  hsm
    The PKCS #11 compliant HSM configuration to use for generating and storing the private key.

    | **Type**: dict

    pkcs11library
      The PKCS #11 library that should be used for generating and storing the private key.

      | **Type**: str

    label
      The HSM label that should be used for generating and storing the private key.

      | **Type**: str

    pin
      The HSM pin that should be used for generating and storing the private key.

      | **Type**: str


  tls
    True if the identity should be enrolled against the TLS certificate authority, false otherwise.

    Cannot be specified at the same time as a PKCS

    | **Type**: bool

  hosts
    The list of host names to add to the certificate as X.509 Subject Alternative Names.

    Can only be specified when enrolling the identity against the TLS certificate authority.

    | **Type**: list
    | **Elements**: str

  force_reenroll
    True if the identity should be re-enrolled, false otherwise.

    If specified, then the identity will be re-enrolled every time that your playbook is run.

    | **Type**: bool

  reenroll_before_expiry
    Use this option to automatically re-enroll the identity before the certificate expires.

    Specified as the maximum time in seconds before the expiration of the certificate.

    For example, to automatically re-enroll the identity when there are less than 30 days remaining before the certificate expires, set this option to ``2592000``.

    | **Type**: int
    | **Default value**: ``-1``








Examples
--------

.. code-block:: yaml+jinja

    
    - name: Enroll an identity
      ibm.blockchain_platform.enrolled_identity:
        state: present
        api_endpoint: https://ibp-console.example.org:32000
        api_authtype: basic
        api_key: xxxxxxxx
        api_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        certificate_authority: Org1 CA
        name: Org1 Admin
        enrollment_id: org1admin
        enrollment_secret: org1adminpw
        path: Org1 Admin.json

    - name: Remove an enrolled identity
      ibm.blockchain_platform.enrolled_identity:
        state: absent
        api_endpoint: https://ibp-console.example.org:32000
        api_authtype: basic
        api_key: xxxxxxxx
        api_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        path: Org1 Admin.json



Return Values
-------------

  enrolled_identity
    The enrolled identity.

    | **Returned**: when *state* is ``present``
    | **Type**: dict

    name
      The name of the enrolled identity.

      | **Type**: str
      | **Sample**: ``Org1 Admin``

    cert
      The base64 encoded certificate of the enrolled identity.

      | **Type**: str
      | **Sample**: ``LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...``

    private_key
      The base64 encoded private key of the enrolled identity.

      | **Type**: str
      | **Sample**: ``LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0t...``

    ca
      The base64 encoded CA certificate chain of the enrolled identity.

      | **Type**: str
      | **Sample**: ``LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...``



