Manage AD Bridge Licenses

There are two options to manage the assignment of AD Bridge licenses:

• Globally using the License Management page in the BeyondTrust Management Console on a Windows administrative workstation connected to Microsoft Active Directory.

  

We recommend that you manage your licenses through the BeyondTrust Management Console.

• Locally using an AD Bridge command-line utility (setkey-cli) on a Unix or Linux computer.

  

License types

Evaluation licenses and permanent licenses

When you install the AD Bridge agent without a permanent license on a Unix or Linux computer, a 90-day product evaluation key is automatically generated. If a permanent license key or an extended evaluation license key is unavailable, AD Bridge will stop authenticating users and applying Group Policy settings after 90 days. The expiration date of an evaluation license applies only to the computer on which the license is installed.

ℹ️

Note

To obtain a permanent license or to convert a trial license to a full license, contact a BeyondTrust sales representative at www.beyondtrust.com/contact.

You can upgrade an evaluation license to a permanent license by importing the permanent license key into the BeyondTrust Management Console, and applying it to a client computer. If the automatic assignment feature is in use, the AD Bridge agent will automatically apply a permanent license when you log on a client with an AD account, restart the AD Bridge authentication service, or run the command-line utility for managing licenses.

Single-computer licenses

BeyondTrust offers single-computer licenses for each of its agents.

If there are multiple domains, a different license file is required for each domain. To spread a set of single-computer licenses across two or more domains, you can request BeyondTrust sales to distribute the licenses in two or more license files.

The number of concurrent logins is unlimited.

Parent-level licensing

AD Bridge supports parent-level licensing, a feature where AD Bridge agents running in child domains can obtain license keys from a license container in the root of the domain. This simplifies license management by eliminating the need for license containers in child domains. License containers in child domains are still supported and are useful in restricting the number of license keys issued to agents joined to that domain.

AD Bridge agents obtain license keys by first looking for a license container in the organizational unit (OU) the computer is joined to:

• If it obtains a license from that container, it assigns it to the agent machine. If the agent does not obtain a license, an evaluation license is issued.
• If it does not find a license container, it will start going up through the AD tree, repeating the process until it reaches the root of the domain. If no license containers are found in the domain the agent is joined to, it then looks in the root of the parent domain for a license container. Once a license container is found, whether a license key is obtained from it or not, the agent does not look for further license containers.

For child domains to acquire and delete licenses that are applied to the agent machines, you must add Permissions to licenses in the root of the domain's license container.

1. At the root of the domain, right-click the License object within the License Container.
2. Add the child/domain computers account and allow Create all child objects and Delete all child objects. This allows the child domain computers group to acquire and delete licenses from the parent domain.

When you leave the domain using --deleteAccount, the credentials used to leave that domain must also be added to each of the license objects so that the license can be freed.

License feature codes

Licenses contain codes that can include or exclude features. When a license is displayed in the console, the codes in the Features column indicate the entitlements that the license covers.

The following table describes each feature code:

Search for a license in AD Bridge

Obtain a license key

An AD Bridge agent obtains a license key by first looking for a license container in the organizational unit (OU) the computer is joined to. If it obtains a license from that container, it will assign it to the agent machine.

If an AD Bridge agent does not find a license container, it will start to search higher in the hierarchy of the AD Bridge tree, repeating the process, until it reaches the root of the domain.

Once the agent discovers a license container, and whether or not a license key can be found, the agent will not look for additional license containers.

Verify a license key

The AD Bridge agent verifies a license in the following instances:

• When you run the setkey-cli utility
• When you start the AD Bridge authentication service
• When you log in

To verify a license, the setkey-cli utility uses the computer's Active Directory account to search for licenses in the computer's OU hierarchy up to the top of the domain. When the computer’s domain controller is down, the utility loads the license from the disk without verifying its assignment in Active Directory.

The AD Bridge Group Policy service also checks for a license when it refreshes the computer's Group Policy Objects (GPOs). If the license is invalid, the service ignores the GPOs. Once the license becomes permanent and valid, the service applies the GPOs when it restarts.

ℹ️

Note

If the message "Invalid computer!" is displayed in the Assigned To column, revoke the license and return it to the pool of available licenses. Right-click the license you want to revoke and click Revoke License.

Create an AD Bridge license container

You can install AD Bridge licenses manually on each client, or you can install the licenses in Active Directory and manage them from a central location. In Active Directory, you must create a license container before you can import an AD Bridge license key file.

Recommendations

Review the following recommendations for creating a license container.

• Manage licenses in Active Directory and create your license container in a common location at the highest level of the organizational unit (OU) hierarchy to which you have write access.

  For instance, if you have separate OUs for your Linux computers, creating the licensing container in a common location above the OUs for the Linux computers can simplify license management.

• If you have a Default Cell, create the license container at the level of the domain.

Any OU may have a license container. The container need not be in the same OU as an AD Bridge Cell. The AD Bridge agent searches the OU hierarchy for a license container in the same way that it searches for a cell. When a license container is found, the agent stops trying to find a key in another container (even if the container it finds is empty) and checks whether the license is assigned to the computer. When the agent finds a license in Active Directory, it marks it as assigned to the computer.

When you create a license container, computers can automatically acquire a license. You can turn off automatic licensing depending on your requirements. However, after you create the license container you must assign a license to each computer manually.

ℹ️

Note

For more information, see Assign a license to a computer in Active Directory.

If there is no license container in Active Directory, the agent verifies the license locally. This is a scenario reserved for licenses set with setkey-cli.

⚠️

Important

You must be a member of the Domain Administrators security group or have privileges sufficient to create and modify containers where you want to create the licensing container. We recommend that you do not create a license container in the Domain Controllers OU.

To create a license container:

1. In the BeyondTrust Management Console, expand the Enterprise Console node, right-click the License Management node, and then click Create License Container.

2. Clear the Allow Computers to Acquire Licenses Automatically box to prevent computers from obtaining a license (Optional).

   

   If you clear the box, you must manually assign a license to each computer.

3. Select the location where you want to create a container and then click OK.

You are now ready to import a license file, which will populate the AD Bridge licenses container in Active Directory with licenses for your Unix and Linux computers.

Add license permissions

Add permissions to licenses in the root of the domain's license container in order for child domains to acquire and delete licenses.

To add permissions for child domains:

1. At the root of the domain, right-click the license object within the license container.
2. Add the child or domain computer's account.
3. Allow Create all child objects and Delete all child objects.

ℹ️

Note

Enabling Create all child objects and Delete all child objects will allow the child domain computers group to acquire and delete licenses from the parent domain.

When you leave the domain with --deleteAccount, the credentials used to leave that domain must also be added to each of the license objects with the intention that the license will be freed.

Import an AD Bridge license file

AD Bridge license keys are distributed in an XML file.Using the BeyondTrust Management Console on your Windows administrative workstation, you can import a license key file containing licenses.

ℹ️

Note

When you import a license file an Active Directory object is created for every license. For example, if your license XML file contains 100 licenses, then 100 Active Directory objects are created.

You must create a license container in Active Directory before you can import a license key file.

1. Make sure the XML file containing the licenses is available on your Windows administrative workstation that is running the BeyondTrust Management Console.
2. Under Enterprise Console, right-click License Management, and then click Import License File.
3. Locate the XML file that contains the licenses, and then click Open.

Turn on automatic licensing

If you turned off automatic licensing when you created the license container, you can turn on the feature at any time.

To turn on automatic licensing:

1. In the BeyondTrust Management Console, expand the Enterprise Console node, right-click the License Management node, and then click Assign Policy.

   

2. Check the box to allow automatic licensing and click OK.

Assign a license to a computer in Active Directory

By default, AD Bridge automatically assigns licenses to computers running the AD Bridge agent when the computers connect to the domain. If you turn off the default setting, then a computer cannot automatically obtain a license. However, you can manually assign a license using the BeyondTrust Management Console.

To manually assign a license:

1. In the BeyondTrust Management Console, expand Enterprise Console, and then click License Management.
2. Right-click the license that you want to assign, and then click Assign License.
3. In the Select Computer dialog box, click Locations, select the location that contains the computer you want, and then click OK.
4. In the Enter the object names to select box, type the name of one or more computers. For example, AppSrvSeattle-1. Separate multiple entries with semicolons. For a list of examples, click examples.
5. Click Check Names, and then click OK.

Manage a license key from the command line

Although we recommend that you manage licenses in the BeyondTrust Management Console, you can also manage a license locally from the command line on a Linux or Unix computer.

From the command line of an AD Bridge client, you can check the computer's license, set a license key, release a license, and adjust the type of license that you want the computer to obtain.

ℹ️

Note

For more information, run the following command:

/opt/pbis/bin/setkey-cli --help

Check the license key

To view the license key that is installed on a Linux or Unix computer, execute the following command at the shell prompt:

/opt/pbis/bin/setkey-cli

Here is an example:

Set a license key

You can set a license key for the AD Bridge agent by using the command line. You should, however, use this method of setting a key only when there is no licensing container in Active Directory and you want the agent to verify the license locally.

To set a license key, run the following command as root, replacing LicenseKeyNumber with a valid license key number:

/opt/pbis/bin/setkey-cli --key LicenseKeyNumber

ℹ️

Note

If there is a license container in Active Directory, you can only use --key to assign available keys from the license container. In this scenario, --key cannot be used to apply an additional license. Check for available licenses from Active Directory.

Release a license key

When you decommission a computer, you can release a computer's license so it can be used by another computer. When you release a permanent license key, it is replaced by a temporary evaluation license.

You can also release a license to apply a different permanent license to the computer.

/opt/pbis/bin/setkey-cli --release