Email-based User Invitation, Acceptance, and Confirmation flow for automated deployments
  • 22 Jan 2021
  • 2 Minutes To Read
  • Print
  • Share
  • Dark
    Light

Email-based User Invitation, Acceptance, and Confirmation flow for automated deployments

  • Print
  • Share
  • Dark
    Light

For organizations which do not leverage Active Directory, an alternative method of deployment is available . Users can be invited to Circles using their email address. This allows users whose devices are not bound to an Active Directory Domain to interact with protected data in a Circle. This process can be manual, as described in the “Step 3 - Invite Users and Confirm Devices” section of the https://securecircle-knowledge-base.document360.io/v1/docs/rapid-deployment article. In some cases, such as when provisioning systems that are not bound to an Active Directory Domain, it may be desirable to automate this process. In these cases, the SecureCircle Server API and command line utilities can be used to silently invite and provision users and their devices.

Automated Flow Steps

The following steps describe the underlying mechanisms that the SecureCircle Server and command line utilities use to invite an email-based user, accept the invitation during agent installation, and confirm the newly-registered device.

  1. (Server API) Retrieve an invitationId for a user by inviting a user by email address retrieving the invitationId from the success response's body.

Invite a new user using /v2/rootMembers/invite API. Set “sendNotifications”: false to prevent an invitation email from being sent. Make sure to specify a Circle’s itemId and memberRoleItemId in the circles list.
https:///api/swagger-ui.html#/root%20members/inviteUsingPOST_1

    [
    {
        "circles": [
            {
                "itemId": "string",
                "memberRoleItemId": "string"
            }
        ],
        "email": "string",
        "message": "string",
        "name": "string",
        "sendNotifications": false
    }
]

circles->itemId can be determined through https:///web/index.html#/circles (select one or more Circles to see a Circle's itemId) or by using the https:///api/swagger-ui.html#/circles/getPageUsingPOST_6 API

circles->memberRoleItemId can be determined through https:///web/index.html#/configuration/user-roles (select one or more User Roles to see the Role's memberRoleItemId) or by using the https:///api/swagger-ui.html#/memberRoles/getPageUsingPOST_14

Retrieve the invitationId from the success response's body.

  1. (On endpoint) The invitationId can be used in two ways:
  • Download the installation package and rename it to .pkg or .exe, then run the installer (with the silent install option). This automatically accepts the invitation during installation.

  • Download the installation package, run the installer with the silent install option, then use the fhtools command line utility to accept the invitation.

  1. (Server API) Confirm the endpoint in one of two ways:
  • (Recommended) Confirm the newly-added endpoint by determining its ID and passing it in the https:///api/swagger-ui.html#/root%20endpoints/confirmUsingPOST API.

  • Determine the newly-added endpoint ID by retrieving the itemId field in the result of a query to the https:///api/swagger-ui.html#/root%20endpoints/getPageUsingPOST_17. The query is formed as follows:

{
    "from": 0,
    "limit": 1,
    "orderBy": "name",
    "searchBy": "confirmed EQ '0' AND name LIKE '<hostname>'"
}

...where is the hostname of the endpoint on which the invitation was accepted (or the value passed into the --alias parameter in the fhtools command)

  • Confirm the newly-added endpoint by passing it's ID to the https:///api/swagger-ui.html#/root%20endpoints/confirmUsingPOST API. For example:
[
  "<endpointId>"
]
  • (Not recommended) Call the https:///api/swagger-ui.html#/operations/root%20endpoints/confirmAllUsingPOST API, confirming all unconfirmed endpoints.

Automated Flow Example Script

PowerShell (Windows)

Install-SecureCircle.ps1

example execution: powershell.exe Install-SecureCircle.ps1 -fqdn REPLACE_WITH_SECURECIRCLE_SERVER_URL -ApiKey REPLACE_WITH_API_KEY -circleid REPLACE_WITH_CIRCLE_ID -MemberRoleId REPLACE_WITH_ROLE_ID -Proxy user:pass@host:port

Was This Article Helpful?