Powershell Management for Defender

(1)

for

Defender

(2)

This guide contains proprietary information protected by copyright. The software described in this guide is furnished under a software license or nondisclosure agreement. This software may be used or copied only in accordance with the terms of the applicable agreement. No part of this guide may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording for any purpose other than the purchaser's personal use without the written permission of Quest Software, Inc.

If you have any questions regarding your potential use of this material, contact: Quest Software World Headquarters

LEGAL Dept 5 Polaris Way

Aliso Viejo, CA 92656 USA

www.quest.com

email: legal@quest.com

Refer to our Web site for regional and international office information.

TRADEMARKS

Quest, Quest Software, the Quest Software logo, and Defender are trademarks and registered trademarks of Quest Software, Inc in the United States of America and other countries. For a complete list of Quest Software's trademarks, please see http:// www.quest.com/legal/trademark-information.aspx. Other trademarks and registered trademarks are property of their respective owners.

Disclaimer

The information in this document is provided in connection with Quest products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Quest products. EXCEPT AS SET FORTH IN QUEST'S TERMS AND CONDITIONS AS SPECIFIED IN THE LICENSE AGREEMENT FOR THIS PRODUCT, QUEST ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL QUEST BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF QUEST HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Quest makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and product descriptions at any time without notice. Quest does not make any commitment to update the information contained in this document.

Powershell Management for Defender Updated - April 2012

(3)

PowerShell Management for Defender is implemented as a Windows PowerShell snap-in, providing an extension to the Windows PowerShell environment. To get acquainted with the basic features of Windows PowerShell, refer to the Windows PowerShell Getting Started Guide, which you can access at http://msdn.microsoft.com/en-us/ library/aa973757.aspx. For more detailed information on Windows PowerShell, see the Windows PowerShell Primer document, which is included with the Windows PowerShell installation.

As the commands provided by PowerShell Management for Defender conform to the Windows PowerShell standards, and are fully compatible with the default command-line tools that come with Windows PowerShell, the information found in Microsoft’s PowerShell documentation is fully applicable.

This document details how to install, configure and use PowerShell Management for Defender. If you require a visual application as an alternative to using a DOS style command line utility, please visit

http://

www.powergui.org

PowerShell Management for Defender provides a command-line management interface for administering Defender attributes within Active Directory.

This document provides information on the basic concepts and features, and includes reference topics about the commands (cmdlets) that can be run.

Using PowerShell Management for Defender

PowerShell Management for Defender, built on Microsoft Windows PowerShell technology, provides a command-line interface that enables automation of Defender administrative tasks. With PowerShell Management for Defender, administrators can administer token related tasks such as assigning tokens to users, assigning a PIN or checking for expired tokens.

The PowerShell Management for Defender command-line tools (cmdlets), like all the Windows PowerShell cmdlets, are designed to deal with objects—structured information that is more than just a string of characters appearing on the screen. The cmdlets do not use text as the basis for interaction with the system, but use an object model that is based on the Microsoft .NET platform. In contrast to traditional, text-based commands, the cmdlets do not require the use of text-processing tools to extract specific information. Rather, you can access portions of the data directly by using standard Windows PowerShell object manipulation commands.

Installing and Opening PowerShell Management

for Defender

Installation Requirements

Before you install, ensure that your system has the following software installed: • Windows 2003 Service Pack 1, or later versions of Windows

• Microsoft .NET Framework 3.5 Service Pack 1, or a later version of .NET Framework • Microsoft Windows PowerShell 1.0 or 2.0

(5)

Installing Microsoft Windows PowerShell

For information on how to download and install Microsoft Windows PowerShell 1.0, see Microsoft’s Knowledge Base article 926139, Windows PowerShell 1.0 English Language Installation Packages for Windows Server 2003 and for Windows XP, at http://support.microsoft.com/?kbid=926139

If you are running Windows Server 2008, to install Windows PowerShell, perform the following steps: 1. Click Start, and then click Control Panel.

2. In Control Panel, double-click Administrative Tools. 3. In Administrative Tools, double-click Server Manager.

4. In Server Manager, in the console tree, click Features, and then in the details pane, click Add Features.

5. In the Add Features Wizard, select Windows PowerShell, and then complete the wizard. We recommend that you install Windows Management Framework, to upgrade your Windows PowerShell installation to version 2.0. For information on how to download and install Windows Management Framework, see Microsoft’s Knowledge Base article 968929, Windows Management Framework (Windows PowerShell 2.0, WinRM 2.0, and BITS 4.0), at http://support.microsoft.com/?kbid=968929.

Installing PowerShell Management for Defender

To install:

1. Run either setup.exe or the correct msi installer, as detailed below, included with the PowerShell Man-agement for Defender distribution package.

2. Follow the instructions on the installation wizard pages. x86 and x64 versions are available:

x86 = PowerShell Management for Defender.msi x64 = PowerShell Management for Defender (x64).msi

(6)

Opening PowerShell Management for Defender

You can open PowerShell Management for Defender by using either of the following procedures. Each procedure loads the snap-in into Windows PowerShell. If you do not load the PowerShell Management for Defender snap-in before you run a command (cmdlet) provided by that snap-in, you will receive an error.

To open PowerShell Management for Defender from the Programs menu, select Start, All Programs, Quest Software, PowerShell Management for Defender.

To add the PowerShell Management for Defender snap-in from Windows PowerShell: 1. Start Windows PowerShell.

2. Verify that the application is available to Microsoft PowerShell. To do this from PowerShell, run:

Get-PSSnapin -registered

The following text is displayed:

Name :Quest.Defender.AdminTools PSVersion : 1.0

Description : This Windows PowerShell snap-in contains cmdlets to manage Quest Defender.

3. If PowerShell commands for Defender has not been added enter the following in the command prompt:

(7)

Getting Help

PowerShell Management for Defender uses the Windows PowerShell help cmdlets to assist you in finding the appropriate information to accomplish your task. The following table provides some examples of how to use the Get-Help and Get-Command cmdlets to access the help information that is available for each cmdlet.

Command Description

Get-Help When you use Get-Help without any parameters, you are presented with basic instruc-tions on how to use the help system in Windows PowerShell.

Get-Help <Cmdlet> When you use Get-Help with the name of a cmdlet as an argument, you are presented with the help information for that cmdlet.

For example, to retrieve the help information for Add-TokenToUser, use either of the following commands:

• Get-Help Add-TokenToUser

• Get-Help Add-TokenToUser -detailed • Get-Help Add-TokenToUser -full

Get-Command Get-Command without any parameters lists all the cmdlets that are available to the shell. You can use the Get-Command cmdlet with the Format-List or Format-Table cmd-let to provide a more readable display.

For example, use Get-Command | Format-List to display the output in a list format. Get-Command <Cmdlet> When you use Get-Command with the name of a cmdlet as an argument, you are

presented with information about the parameters and other components of that cmdlet. The <Cmdlet> entry allows for wildcard character expansion.

For example, to retrieve information about the cmdlets with the names ending in Batch, you can use the following command:

• Get-Command *Batch Get-Command -Noun

<CmdletNoun> Get-Command -Noun <CmdletNoun> lists all the cmdlets with the names that include the specified noun. <CmdletNoun> allows for wildcard character expansion. Thus, you can use the following command to list all the cmdlets provided by PowerShell com-mands for Defender that include Token as part of the cmdlet:

(8)

Cmdlet Naming Conventions

All cmdlets are presented in verb-noun pairs. The verb-noun pair is separated by a hyphen (-) without spaces, and the cmdlet nouns are always singular. The verb refers to the action that the cmdlet performs. The noun identifies the entity on which the action is performed. For example, in the Add-TokenToUsercmdlet name, the verb is Add and the noun is TokenToUser.

You can use the following commands to list all cmdlets found in PowerShell Management for Defender: • Get-Command Quest.Defender.AdminTools\* (PowerShell v1.0)

• Get-Command –module Quest.Defender.AdminTools (PowerShell v2.0)

Tab Expansion to Auto-Complete Names

PowerShell Management for Defender provides a way to complete command and parameter names

automatically, thus speeding up command entry. You can fill in cmdlet names and parameters by pressing the TAB key.

To use tab expansion on a cmdlet name, type the entire first part of the name (the verb) and the hyphen that follows it, and then press TAB. The shell will complete the cmdlet name if a matching cmdlet is found. If multiple matching cmdlet names exist, repeatedly pressing TAB will cycle through all of the available choices. You can fill in more of the name for a partial match.

The following example shows how you can use tab expansion when you enter a cmdlet name:

Add-Token <TAB>

As you press the TAB key in this example, the shell cycles through all the cmdlet names that begin with

Add-Token

and you will see:

Add-TokenToUser

Add-TokenToUserBatch

You can also use tab expansion when you want the shell to complete the partial parameter name that you have entered. In this case, you must specify the full cmdlet name, either by typing it in directly or by using tab expansion. The following example shows how you can use tab expansion when you enter a parameter name:

Add-TokenToUser -u <TAB>

As you press the TAB key in this example, the shell completes the

_{UserCommonName}

parameter on the

(9)

Parameters

Cmdlets use parameters to take information necessary for completing their tasks. Parameters are string elements that follow the name of a cmdlet, either identifying an object and its attributes to act upon, or controlling how the cmdlet performs its task. The name of the parameter is preceded by a hyphen (-) and followed by the value of the parameter as follows:

Verb-Noun -ParameterName <ParameterValue>

In this example, the hyphen in front of the parameter name indicates that the word immediately following the hyphen is a parameter passed to the cmdlet and the next separate string after the parameter name is the value of the parameter.

In the examples included within the Cmdlets Reference section later in this document we have provided examples, omitting the parameter name where possible to simplify the command.

Parameter Details

The information displayed by the Get-Help cmdlet includes the Parameters section (also called metadata) on each parameter. The following example is an excerpt from the output of the Get-Help Add-TokenToUser -full command:

Name

Add-TokenToUser

Synopsis

Assigns a Defender token to a user. Syntax

Add-TokenToUser UserCommonName] <string> TokenCommonName] <string>

[-UserSearchBase <string>] [-TokenSearchBase <string>] [<CommonParameters>]

Detailed Description

Assigns a Defender token to a user. For batch assignment of many users or tokens, the

Add-TokenToUserBatch command will provide better performance than repeated running of the tool using assign.

(10)

-UserCommonName <string> Common name of the user to whom the token will be assigned. Required True

Position 0 Default

Accept pipeline input? False Accept wildcard chara ters? False

-TokenCommonName <string> Common name of the token to be assigned. Required True

Position 1 Default Value

Accept pipeline input? False Accept wildcard chara ters? False

-UserSearchBase <string> Optional parameter to specify base container from which to search for users. Required False

Position Named Default Value

Accept pipeline input? False Accept wildcard characters? False <CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, and -OutVariable. For more information, type, "get-help about_commonparameters".

Input Type Return Type Related Links

(11)

Positional Parameters

A positional parameter lets you specify the parameter’s value without specifying the parameter’s name. A positional parameter has the Position attribute set to an integer in the metadata. This integer indicates the position on the command line where the cmdlet can find the parameter’s value.

An example of a positional parameter is the UserCommonName parameter. This parameter is always in position 0 if it is available on a cmdlet. The following two commands perform the same task: listing the Defender tokens assigned to a user:

• Get-AllTokensForUser -UserCommonName "Bob Smith" • Get-AllTokensForUser "Bob Smith"

If a parameter is not a positional parameter, it is considered to be a named parameter. When you enter a command on the command line, you must type the parameter name for a named parameter.

Syntax

PowerShell Management for Defender follows the Windows PowerShell command conventions that help you understand what information is required or optional when you run a cmdlet and how you must present the parameters and their values. The following table lists these command conventions.

In the documentation, all cmdlets display their associated parameters in parameter sets. These are groupings of parameters that can be used with each other. Although a cmdlet may have multiple parameter sets, most cmdlets have only one set of parameters. The following example displays the parameter set of the Add-TokenToUser cmdlet:

Add-TokenToUser UserCommonName] <string> TokenCommonName] <string>

[-UserSearchBase <string>] [-TokenSearchBase <string>] [<CommonParameters>]

In this example:

• the UserCommonName and TokenCommonName parameters are enclosed in square brackets to indicate that you can specify the string value for this parameter without typing -UserCommonName or -TokenCom-monName (these are positional parameters, see Positional Parameters on page10 of this document). • the UserSearchBase and TokenSearchBase parameters along with their parameter values are enclosed in

square brackets, to indicate that these are optional parameters, so each of these parameters along with their values can be omitted.

Symbol Description

- A hyphen indicates that the next word on the command line is a parameter. For more information about parameters, see “Parameters” earlier in this document.

<> _{Angle brackets are used to indicate parameter values along with the parameter type setting. This} setting specifies the form that the parameter's value should take, and refers to the .NET type that determines the kind of value that is permitted as a parameter argument. For example, <Int32> indicates that the parameter argument must be an integer; <String> indicates that the argument must be in the form of a character string. If the string contains spaces, the value must be enclosed in quotation marks or the spaces must be preceded by the escape character (`).

The angle brackets are only intended to help you understand how a command should be con-structed. You do not type these brackets when you enter the command on the command line. [] Square brackets are used to indicate an optional parameter and its value. A parameter and its value

that are not enclosed in square brackets are required. If you do not supply a required parameter on the command line, the shell prompts you for that parameter. The square brackets are only intended to help you understand how a command should be constructed. You do not type these brackets when you enter the command on the command line.

(12)

Cmdlets

The following cmdlets are available in PowerShell Management for Defender version 5.7: • Add-SoftwareTokenToUser • Add-TokenToUser • Add-TokenToUserBatch • Find-DefenderToken • Get-DefenderLicense • Get-DefenderTemporaryResponses • Get-DefenderUsersLastLogon • Get-TokensForUser • Get-UnactivatedSoftwareTokens • Get-UsersForToken • Remove-AllTokensFromUser • Remove-DefenderPassword • Remove-PINFromUserToken • Remove-TemporaryResponse • Remove-TokenFromUser • Remove-TokenFromUserBatch • Reset-DefenderToken • Reset-DefenderViolationCount • Set-DefenderPassword • Set-PINOnUserToken • Set-TemporaryResponse • Test-DefenderToken

(13)

Cmdlet Reference

All Cmdlets are shown below in BOLD text. If the cmdlet requires any additional information, you can enter this on the command line. When you run the cmdlet, PowerShell Management for Defender will prompt for any missing information.

For each cmdlet referenced below, the following Windows PowerShell Common Parameters are supported: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer and OutVariable. For more information, type:

(14)

Add-SoftwareTokenToUser

This command assigns a single Defender software token to a user within Active Directory.

Syntax

Add-SoftwareTokenToUser [-UserCommonName] <string> [-TokenType] <string>

[[-TokenPIN] <string>] [-UserSearchBase <string>] [<CommonParameters>]

Parameters

UserCommonName

Common name of the user to whom the token will be assigned. TokenType

The type of the token added. This may be one of the following values: • Windows • Palm • Blackberry • WindowsPhone • iToken • Mobile • Android • EmailOTP • Java

These types produce tokens for use on the following platforms: • Windows - Windows operating systems

• Palm - Palm devices

• Blackberry - BlackBerry devices

• WindowsPhone - Devices running Windows mobile or Windows Phone operating systems • iToken - iPhone, iPad or iPod Touch devices

• Mobile - SMS token, where a text message containing one-time passwords is sent to the user's mobile phone

• Android - Devices running the Android operating system

• EmailOTP - Email token, where an email containing one-time passwords is sent to the user's mobile phone • Java - Windows, Mac or Linux operating systems that support Java applications

(15)

TokenPin

Optional parameter to specify PIN to assign to the user's token. PINs cannot be used when programming a Windows token.

UserSearchBase

Optional parameter to specify base container from which to search for users.

EXAMPLE 1

Assign a software token to use with the Defender Desktop Token on Windows to a user with CN BSmith

Add-SoftwareTokenToUser BSmith Windows

EXAMPLE 2

Assign a token to use with the iToken on iPhone, iPad or iPod Touch to a user with CN 'Bob Smith' specifying a PIN for the token and using a specific User Search Base

Add-SoftwareTokenToUser "Bob Smith" iToken 9876 -UserSearchBase

"CN=Users,DC=MyDomain,DC=Local"

EXAMPLE 3

Get-Content C:\Defender\NewTokens.txt | ForEach-Object {$data = $_.S

plit(","); Add-SoftwareTokenToUser $data[0] $data[1] $data[2] }

Description

Given a file

_{C:\Defender\NewTokens.txt}

containing a list of comma-seperated lines containing user CN, token type and PIN assign a token to each user in the file.

Example file contents:

BSmith,Windows

RJones,BlackBerry,1471

TBlack,iToken

This file would assign a Windows token to BSmith, a BlackBerry token with PIN to RJones and an iToken to TBlack.

(16)

Add-TokenToUser

This command assigns a single Defender token to a user within Active Directory.

For batch assignment of many users or tokens, the Add-TokenToUserBatch command will provide better performance than repeated running of this cmdlet.

Syntax

Add-TokenToUser [-UserCommonName] <string> [-TokenCommonName] <string>

[-UserSearchBase <string>] [-TokenSearchBase <string>] [<CommonParameters>]

Parameters

UserCommonName

Common name of the user to whom the token will be assigned. TokenCommonName

Common name of the token to be assigned. UserSearchBase

Optional parameter to specify base container from which to search for users. TokenSearchBase

Optional parameter to specify base container from which to search for tokens. Remarks

To see the examples, type:

"get-help Add-TokenToUser -examples"

For more information, type:

"get-help Add-TokenToUser -detailed" For technical information, type:

"get-help Add-TokenToUser -full" Example 1

Assign a token with Common Name (CN) GO0030050050253 to a user with CN BSmith:

Add-TokenToUser BSmith GO0030050050253

Example 2

Assign a token with CN GO0030050050253 to a user with CN 'Bob Smith' specifying a specific User Search Base:

Add-TokenToUser "Bob Smith" GO0030050050253 -UserSearchBase

"CN=Users,DC=MyDomain,DC=Local"

Example 3

Assign a token with CN GO0030050050253 to a user with CN "Bob Smith" specifying a specific User Search Base and Token Search Base:

Add-TokenToUser "Bob Smith" GO0030050050253 -UserSearchBase

"CN=Users,DC=mydomain,DC=Local" -TokenSearchBase

(17)

Parameters UsersFile

Name and path of the file containing common names of the users to whom tokens will be assigned. TokensFile

Name and path of the file containing common names of the tokens to be assigned. PINsFile

Name and path of the file containing the PINs to be assigned to the tokens. UserSearchBase

"get-help Add-TokenToUserBatch -examples"

"get-help Add-TokenToUserBatch -detailed"

For technical information, type:

(18)

Example 1

Assign tokens from a file named 'Tokens.txt' located in C:\Defender to users listed in the file 'Users.txt' located in C:\Defender:

Add-TokenToUserBatch C:\Defender\Users.txt C:\Defender\Tokens.txt

In this example the file format for the UsersFile is a list of users as shown below: Bob Smith

Bill Owen Gill Summers

and the file format for the TokensFile is a list of token CN's that exist in Active Directory, as shown below: GO0030050050277

GO0030050050253 GO0030050050260 In this example:

Bob Smith will have token GO0030050050277 assigned to his account Bill Owen will have token GO0030050050253 assigned to his account Gill Summers will have token GO0030050050260 assigned to her account.

Example 2

Assign tokens from a file named 'Tokens.txt' and set PINs from a file named 'PINs.txt' located in C:\Defender to users listed in the file 'Users.txt' located in C:\Defender:

Add-TokenToUserBatch C:\Defender\Users.txt C:\Defender\Tokens.txt

C:\Defender\PINs.txt

GO0030050050253 GO0030050050260

and the file format for the PINsFile is a list of PINs as shown below: 1471

9090 6842 In this example:

(19)

GO0030050050253 GO0030050050260

and the file format for the PINsFile is a list of PINs as shown below: 1471 expire

9090 expire 6842 expire In this example:

Bob Smith will have token GO0030050050277 with expired PIN 1471 assigned to his account Bill Owen will have token GO0030050050253 with expired PIN 9090 assigned to his account Gill Summers will have token GO0030050050260 with expired PIN 6842 assigned to her account.

Example 4

Assign tokens from a file named 'Tokens.txt' located in C:\Defender to users listed in the file 'Users.txt' located in C:\Defender

Add-TokenToUserBatch C:\Defender\Users.txt C:\Defender\Tokens.txt

PDAND3316900004 PDIPN3317169661 In this example:

Bob Smith will have token GO0030050050277, PDAND3316900004 and PDIPN3317169661 assigned to his account.

(20)

Example 5

Assign tokens from a file named 'Tokens.txt' located in C:\Defender to users listed in the file 'Users.txt' located in C:\Defender

Add-TokenToUserBatch C:\Defender\Users.txt C:\Defender\Tokens.txt

and the file format for the TokensFile is a single token CN that exists in Active Directory, as shown below: GO0030050050277

In this example:

Bob Smith, Bill Owen and Gill Summers will have token GO0030050050277 assigned to their accounts.

Example 6

Assign tokens from a file named 'Tokens.txt' and set PINs from a file named 'PINs.txt' located in C:\Defender to users listed in the file 'Users.txt' located in C:\Defender.

Add-TokenToUserBatch C:\Defender\Users.txt C:\Defender\Tokens.txt

C:\Defender\PINs.txt

GO0030050050253 GO0030050050260

9090 In this example:

Bob Smith will have token GO0030050050277 with PIN 1471 assigned to his account Bill Owen will have token GO0030050050253 with PIN 9090 assigned to his account Gill Summer will have token GO0030050050260 assigned to her account with no PIN.

(21)

Example 7

Assign tokens from a file named 'Tokens.txt' and set PINs from a file named 'PINs.txt' located in C:\Defender to users listed in the file 'Users.txt' located in C:\Defender:

Add-TokenToUserBatch C:\Defender\Users.txt C:\Defender\Tokens.txt

C:\Defender\PINs.txt

GO0030050050253 GO0030050050260

In this example:

Bob Smith will have token GO0030050050277 with PIN 1471 assigned to his account Bill Owen will have token GO0030050050253 with PIN 1471 assigned to his account Gill Summer will have token GO0030050050260 with PIN 1471 assigned to her account.

Example 8

Assign tokens from a file named 'Tokens.txt' located in C:\Defender to users listed in the file 'Users.txt' located in C:\Defender using a specified User and Token Search Base:

Add-TokenToUserBatch C:\Defender\Users.txt C:\Defender\Tokens.txt -UserSearchBase

"CN=Users,DC=mydomain,DC=Local" -TokenSearchBase

(22)

Find-DefenderToken

This command will find Defender tokens matching a serial number or part of a serial number. Non-alphanumeric characters will be removed before searching.

Syntax

Find-DefenderToken [-TokenSerialNumber] <string> [-TokenSearchBase <string>]

<CommonParameters>]

Parameters

TokenSerialNumber

The serial number or part of the serial number to search for. Non alphanumeric characters will be removed before searching.

TokenSearchBase

"get-help Find-DefenderToken -examples"

"get-help Find-DefenderToken -detailed"

"get-help Find-DefenderToken -full"

Example 1

To list the common name of all Defender Blackberry Tokens that have been programmed and exist in AD:

Find-DefenderToken BLB

Example 2

To list all Defender Tokens that have '277' as part of the serial number:

Find-DefenderToken 277

Example 3

To produce a list of tokens that have been programmed for the Android device using a specified Token Search Base:

Find-DefenderToken PDAND -TokenSearchBase

"OU=Tokens,OU=Defender,DC=MyDomain,DC=Local"

(23)

Get-DefenderLicense

This command retrieves details of the current Defender user and token licenses. There are no additional parameters for this command.

Syntax

Get-DefenderLicense [<CommonParameters>]

Remarks

"get-help Get-DefenderLicense -examples"

"get-help Get-DefenderLicense -detailed"

"get-help Get-DefenderLicense -full"

Example 1

To retrieve the current Defender User License:

(24)

Get-DefenderTemporaryResponses

Gets Defender tokens that have valid temporary responses assigned. Syntax

Get-DefenderTemporaryResponses [-UserSearchBase <string>] [<CommonParameters>]

Parameters

UserSearchBase <string>

EXAMPLE 1

Retrieve Defender tokens that have valid temporary responses assigned. Get-DefenderTemporaryResponses

EXAMPLE 2

Retrieve Defender tokens that have valid temporary responses assigned for users with the specified User Search Base.

(25)

Get-DefenderUsersLastLogon

The cmdlet will list the name and last logon time for all users that have authenticated successfully to Defender. Syntax

Get-DefenderUsersLastLogon [-UserSearchBase <string>] [<CommonParameters>]

Parameters

UserSearchBase <string>

Remarks

"get-help Get-DefenderUsersLastLogon -examples"

"get-help Get-DefenderUsersLastLogon -detailed"

"get-help Get-DefenderUsersLastLogon -full"

Example 1

To list the names and last logon times of all users who have authenticated to Defender:

Get-DefenderUsersLastLogon

Example 2

To list the names and last logon times of all users who have authenticated to Defender using a specified User Search Base:

Get-DefenderUsersLastLogon -UserSearchBase "CN=Users,DC=MyDomain,DC=Local"

Example 3

To list the names and last logon times of all users who have authenticated to Defender in the last 30 days:

Get-DefenderUsersLastLogon | Where-Object {$_.LastLogon -gt

((get-date).AddDays(-30))}

Example 4

To list the names and last logon times of all users who have authenticated to Defender since 1st November 2010:

Get-DefenderUsersLastLogon | Where-Object {$_.LastLogon -gt (get-date -Date 01/11/

2010)}

(26)

Get-TokensForUser

This command will list the Defender tokens currently assigned to a user account returning the token type, common name, DN and whether the token has a PIN assigned:

Syntax

Get-TokensForUser [-UserCommonName] <string> [-UserSearchBase <string>]

[<CommonParameters>]

Parameters

UserCommonName

Common name of the user whose tokens will be listed. UserSearchBase

Remarks

"get-help Get-TokensForUser -examples"

"get-help Get-TokensForUser -detailed"

(27)

Example 1

To retrieve a list of the common names of all Defender Tokens assigned to a User account with a CN of 'Bob Smith':

Get-TokensForUser "Bob Smith"

The screen shot below shows an example of the results returned and how they are displayed when using the '|Format-List' or '|Format-Table' parameters:

Example 2

To retrieve a list of the common names of all Defender Tokens assigned to a User account with a CN of 'Bob Smith' using a specified User Search Base:

(28)

Get-UnactivatedSoftwareTokens

This command will list software tokens that have not been activated. Syntax

Get-UnactivatedSoftwareTokens ShowExpiredOnly [<SwitchParameter>]]

[-TokenSearchBase <string>] [<CommonParameters>]

Parameters ShowExpiredOnly

Optional, if specified only Defender Software tokens that have expired activation codes are displayed. TokenSearchBase

Optional parameter to specify base container from which to search for tokens.

Remarks

"get-help Get-UnactivatedSoftwareTokens -examples"

"get-help Get-UnactivatedSoftwareTokens -detailed"

"get-help Get-UnactivatedSoftwareTokens -full"

Example 1

To retrieve a list of Defender Software Tokens that have not been activated:

Get-UnactivatedSoftwareTokens

Example 2

To retrieve a list of Defender Software Tokens that have not been activated using a specified Token Search Base:

Get-UnactivatedSoftwareTokens -TokenSearchBase

"OU=Tokens,OU=Defender,DC=MyDomain,DC=Local"

Example 3

To retrieve a list of Defender Software Tokens where the activation code has expired:

Get-UnactivatedSoftwareTokens -ShowExpiredOnly

Example 4

To retrieve a list of Defender Software Tokens where the activation code has expired using a specified Token Search Base:

Get-UnactivatedSoftwareTokens -ShowExpiredOnly -TokenSearchBase

"OU=Tokens,OU=Defender,DC=MyDomain,DC=Local"

(29)

Get-UsersForToken

This command lists the users assigned to a Defender token. Syntax

Get-UsersForToken [-TokenCommonName] <string> [-TokenSearchBase <string>]

<CommonParameters>]

Parameters

TokenCommonName

Common name of the token whose users will be listed. TokenSearchBase

Remarks

"get-help Get-UsersForToken -examples"

"get-help Get-UsersForToken -detailed"

"get-help Get-UsersForToken -full"

Example 1

To retrieve a list of user common names that have been assigned a token with CN GO0030050050277:

Get-UsersForToken GO0030050050277

Example 2

To retrieve a list of user common names that have been assigned a token with CN GO0030050050277 using a specified Token Search Base:

Get-UsersForToken GO0030050050277 -TokenSearchBase

"OU=Tokens,OU=Defender,DC=MyDomain,DC=Local"

(30)

Remove-AllTokensFromUser

This cmdlet can be used to remove or un-assign all Defender tokens from a user account.

For batch unassignment of many users or tokens, the Remove-TokenFromUserBatch command will provide better performance than repeated running of this cmdlet.

Syntax

Remove-AllTokensFromUser [-UserCommonName] <string> [-DeleteSoftwareToken

[<SwitchParameter>]] [-UserSearchBase <string>] [<CommonParameters>]

Parameters

UserCommonName

Common name of the user whose tokens will be unassigned. DeleteSoftwareToken

Optional, if specified then Defender Software tokens are removed from Active Directory as well as being unassigned from the user.

UserSearchBase

Remarks

"get-help Remove-AllTokensFromUser -examples"

"get-help Remove-AllTokensFromUser -detailed"

"get-help Remove-AllTokensFromUser -full"

Example 1

To unassign all Defender tokens from a user with common name 'Bob Smith':

Remove-AllTokensFromUser "Bob Smith"

Example 2

To unassign all Defender tokens from a user with common name 'Bob Smith' using a specified User Search Base:

Remove-AllTokensFromUser "Bob Smith" -UserSearchBase "CN=Users,DC=mydomain,DC=Local"

Example 3

To unassign all Defender tokens from a user with common name 'Bob Smith' and remove any assigned Defender Software tokens from Active Directory:

(31)

Remove-DefenderPassword

This cmdlet deletes the Defender password for a user or all users in a group. Specify a user account name to delete the Defender password for a specific user. Specify a group name to delete the Defender passwords for all users in that group. Syntax

Remove-DefenderPassword [-UserGroupCommonName] <string> [-UserSearchBase <string>]

[<CommonParameters>]

Parameters

UserGroupCommonName

Common name of the user or group of users from which the Defender Password will be removed. UserSearchBase

Optional parameter to specify base container from which to search for users and groups.

Remarks

"get-help Remove-DefenderPassword -examples"

"get-help Remove-DefenderPassword -detailed"

"get-help Remove-DefenderPassword -full"

Example 1

To remove the Defender Password from a user with common name 'Bob Smith':

Remove-DefenderPassword "Bob Smith"

Example 2

To remove the Defender Password from all members of an Active Directory security group with common name 'Sales':

Remove-DefenderPassword Sales

Example 3

To remove the Defender Password from a user with common name 'Bob Smith' using a specified User Search Base:

(32)

Remove-PINFromUserToken

This cmdlet will remove a PIN that has been assigned to a user's token. Syntax

Remove-PINFromUserToken UserCommonName] <string> TokenCommonName] <string>

[-UserSearchBase <string>] [-TokenSearchBase <string>] [<CommonParameters>]

Parameters

UserCommonName

Common name of the user from whom the PIN will be removed. TokenCommonName

Common name of the token from which the PIN will be removed. UserSearchBase

Remarks

"get-help Remove-PINFromUserToken -examples

"get-help Remove-PINFromUserToken -detailed"

"get-help Remove-PINFromUserToken -full"

Example 1

To remove a PIN from a token with common name (CN) GO0030050050277, which has been assigned to a user with CN "Bob Smith":

Remove-PINFromUserToken "Bob Smith" GO0030050050277

Example 2

To remove a PIN from a token with common name (CN) GO0030050050277, which has been assigned to a user with CN "Bob Smith" using a specified User and Token Search Base:

Remove-PINFromUserToken "Bob Smith" GO0030050050277 -UserSearchBase

"CN=Users,DC=MyDomain,DC=Local" -TokenSearchBase

(33)

Remove-TemporaryResponse

This cmdlet will remove a temporary token response that has been assigned to a User's token. Syntax

Remove-TemporaryResponse [-UserCommonName] <string> [-TokenCommonName] <string>

[-UserSearchBase <string>] [-TokenSearchBase <string>] [<CommonParameters>]

Parameters

UserCommonName

Common name of the user to whom the temporary response has been assigned. TokenCommonName

Common name of the token to which the temporary response has been assigned. UserSearchBase

Remarks

"get-help Remove-TemporaryResponse -examples"

"get-help Remove-TemporaryResponse -detailed"

"get-help Remove-TemporaryResponse -full"

Example 1

To remove the temporary token response from a token with common name GO0030050050277 that is assigned to a user with common name 'Bob Smith':

Remove-TemporaryResponse "Bob Smith" GO0030050050277

Example 2

To remove the temporary token response from a token with common name GO0030050050277 that is assigned to a user with common name 'Bob Smith' specifying a specific User Search Base:

Remove-TemporaryResponse "Bob Smith" GO0030050050277 -UserSearchBase

"CN=Users,DC=MyDomain,DC=Local"

Example 3

To remove the temporary token response from a token with common name GO0030050050277 that is assigned to a user with common name 'Bob Smith' specifying a User and Token Search Base:

Remove-TemporaryResponse "Bob Smith" GO0030050050277 -UserSearchBase

"CN=Users,DC=MyDomain,DC=Local" -TokenSearchBase

(34)

Remove-TokenFromUser

This command will unassign a Defender token from a user in Active Directory.

For batch unassignment of many users or tokens, the Remove-TokenFromUserBatch command will provide better performance than repeated running of this cmdlet.

Syntax

Remove-TokenFromUser UserCommonName] <string> TokenCommonName] <string>

[-DeleteSoftwareToken [<SwitchParameter>]] [-UserSearchBase <string>] [-TokenSearchBase

<string>] [<CommonParameters>]

Parameters

UserCommonName

Common name of the user from whom the token will be unassigned. TokenCommonName

Common name of the token to be unassigned. DeleteSoftwareToken

Optional, if specified for a Defender Software token, the token will be removed from Active Directory as well as being unassigned from the user account.

UserSearchBase

Remarks

"get-help Remove-TokenFromUser -examples"

"get-help Remove-TokenFromUser -detailed"

"get-help Remove-TokenFromUser -full"

Example 1

Unassign a token with Common Name (CN) GO0030050050277 from a user with CN BSmith:

Remove-TokenFromUser BSmith GO0030050050277

Example 2

Unassign a token with CN GO0030050050277 from a user with CN 'Bob Smith' specifying a specific User Search Base:

Remove-TokenFromUser "Bob Smith" GO0030050050277 -UserSearchBase

"CN=Users,DC=MyDomain,DC=Local"

(35)

Remove-TokenFromUserBatch

This command will unassign the tokens in the token file from the users on the corresponding line in the users file. If the users file contains just one user, all tokens listed in the tokens file are unassigned from that user.

If the tokens file contains just one token, all users listed in the users file are unassigned that token. The word all may be specified on a line in the tokens file, in which case all tokens are unassigned from the corresponding user in the users file.

These files use the same format as described for Add-TokenToUserBatch. Syntax

Remove-TokenFromUserBatch [-UsersFile] <string> [-TokensFile] <string>

[-DeleteSoftwareToken [<SwitchParameter>]] [-UserSearchBase <string>]

[-TokenSearchBase <string>] [<CommonParameters>]

Parameters UsersFile

Name of file containing common names of the users from whom tokens will be unassigned. TokensFile

Name of file containing common names of the tokens to be unassigned. DeleteSoftwareToken

Optional, if specified then Defender Software tokens are removed from Active Directory as well as being removed from the user.

UserSearchBase

Remarks

"get-help Remove-TokenFromUserBatch -examples"

"get-help Remove-TokenFromUserBatch -detailed"

(36)

Example 1

Unassign tokens from a file named 'Tokens.txt' located in C:\Defender from users listed in the file 'Users.txt' located in C:\Defender:

Remove-TokenFromUserBatch C:\Defender\Users.txt C:\Defender\Tokens.txt

GO0030050050253 GO0030050050260 In this example:

Bob Smith will have token GO0030050050277 unassigned from his account Bill Owen will have token GO0030050050253 unassigned from his account Gill Summer will have token GO0030050050260 unassigned from her account.

Example 2

Unssign tokens from a file named 'Tokens.txt' located in C:\Defender from users listed in the file 'Users.txt' located in C:\Defender, where only a single user common name is specified:

Remove-TokenFromUserBatch C:\Defender\Users.txt C:\Defender\Tokens.txt

Bob Smith will have token GO0030050050277, PDAND3316900004 and PDIPN3317169661 unassigned from his account.

(37)

Example 3

Unssign tokens from a file named 'Tokens.txt' located in C:\Defender from users listed in the file 'Users.txt' located in C:\Defender, where only a single token common name is specified:

Remove-TokenFromUserBatch C:\Defender\Users.txt C:\Defender\Tokens.txt

and the file format for the TokensFile is a single token CN that exists in Active Directory, as shown below: GO0030050050277

In this example:

Bob Smith, Bill Owen and Gill Summers will have token GO0030050050277 unassigned from their accounts.

Example 4

Unssign tokens from a file named 'Tokens.txt' located in C:\Defender from users listed in the file 'Users.txt' located in C:\Defender, using the \all\ parameter in the Tokens.txt file:

Remove-TokenFromUserBatch C:\Defender\Users.txt C:\Defender\Tokens.txt

and the file format for the TokensFile is as shown below: GO0030050050277

all all In this example:

Bob Smith will have token GO0030050050277 unassigned from his account Bill Owen will have all Defender tokens unassigned from his account

Gill Summer will have all Defender tokens unassigned from her account.

Example 5

Unassign tokens from a file named 'Tokens.txt' located in C:\Defender from users listed in the file 'Users.txt' located in C:\Defender using a specified User and Token Search Base:

RemoveTokenFromUserBatch C:\Defender\Users.txt C:\Defender\Tokens.txt

-UserSearchBase "CN=Users,DC=mydomain,DC=Local" -TokenSearchBase

(38)

Example 6

Unassign tokens from a file named 'Tokens.txt' located in C:\Defender from users listed in the file 'Users.txt' located in C:\Defender, where only a single user common name is specified:

RemoveTokenFromUserBatch C:\Defender\Users.txt C:\Defender\Tokens.txt

-DeleteSoftwareToken

Bob Smith will have token GO0030050050277, PDAND3316900004 and PDIPN3317169661 unassigned from his account. Tokens PDAND3316900004 and PDIPN3317169661 will also be removed from Active Directory.

(39)

Reset-DefenderToken

This cmdlet will reset a Defender token to aid authentication should the token become out of synchronization with the Defender Security Server.

Syntax

Reset-DefenderToken [-TokenCommonName] <string> [-TokenSearchBase <string>]

[<CommonParameters>]

Parameters

TokenCommonName

Common name of the token to reset. TokenSearchBase

Remarks

"get-help Reset-DefenderToken -examples"

"get-help Reset-DefenderToken -detailed"

"get-help Reset-DefenderToken -full"

Example 1

To reset the token with common name GO0061454569921:

Reset-DefenderToken GO0061454569921

Example 2

To reset the token with common name GO0061454569921 using a specified Token Search Base:

Reset-DefenderToken GO0061454569921 -TokenSearchBase

"OU=Tokens,OU=Defender,DC=MyDomain,DC=Local"

(40)

Reset-DefenderViolationCount

This cmdlet will reset a user's Defender violation count.

Also allows the violation and reset counts to be viewed without resetting them. Syntax

Reset-DefenderViolationCount [-UserCommonName] <string>

[-ViewOnly [<SwitchParameter>]] [-UserSearchBase <string>] [<CommonParameters>]

Parameters

UserCommonName

Common name of the user whose violation count is to be reset. ViewOnly

Optional parameter, if specified then the violation count and reset count are returned but not adjusted. UserSearchBase

Remarks

"get-help Reset-DefenderViolationCount -examples"

"get-help Reset-DefenderViolationCount -detailed"

"get-help Reset-DefenderViolationCount -full"

Example 1

To reset the Defender Violation Count for a user with CN BSmith:

Reset-DefenderViolationCount BSmith

Example 2

To reset the Defender violation count for a user with CN "Bob Smith" specifying a specific User Search Base:

Reset-DefenderViolationCount "Bob Smith" -UserSearchBase

"CN=Users,DC=MyDomain,DC=Local"

Example 3

To view the violation count and reset count information for a user with CN "Bob Smith":

(41)

Set-DefenderPassword

This cmdlet sets the Defender password for a user or all users in a group. Specify the user account name to set the Defender password for that user. Specify the group name to assign the Defender password to all users in the group. Syntax

Set-DefenderPassword [-UserGroupCommonName] <string> [-Password] <string>

[-Expire [<SwitchParameter>]] [-Overwrite [<SwitchParameter>]]

[-UserSearchBase <string>] [<CommonParameters>]

Parameters

UserGroupCommonName

Common name of the user or group of users to which the Defender Password will be added. Password

The Defender Password to set. -Expire

Sets the Defender Password to be expired. -Overwrite

Overwrites an existing Defender Password, by default existing Defender Password are not overwritten. UserSearchBase

Optional parameter to specify base container from which to search for users and groups.

Remarks

"get-help Set-DefenderPassword -examples"

"get-help Set-DefenderPassword -detailed"

"get-help Set-DefenderPassword -full"

Example 1

Assign a Defender Password 'MyPassword' to a user account with Common Name (CN) "Bob Smith":

Set-DefenderPassword "Bob Smith" MyPassword

Example 2

Assign a Defender Password 'MyPassword' to a user account with Common Name (CN) "Bob Smith" and configure the password to expire so that the user is prompted to change the Defender Password on first use:

Set-DefenderPassword "Bob Smith" MyPassword -expire

Example 3

Assign a Defender Password 'MyNewPassword' to a user account with Common Name (CN) "Bob Smith" and configure the password to expire so that the user is prompted to change the Defender Password on first use and

(42)

Set-PINOnUserToken

This cmdlet sets a PIN on a token that has been assigned to a user. Syntax

Set-PINOnUserToken [-UserCommonName] <string> [-TokenCommonName] <string> [-TokenPIN]

<string> [-UserSearchBase <string>] [-TokenSearchBase <string>] [<CommonParameters>]

Parameters

UserCommonName

Common name of the user to whom the PIN will be assigned. TokenCommonName

Common name of the token to which the PIN will be assigned. TokenPIN

The PIN to assign. UserSearchBase

Remarks

"get-help Set-PINOnUserToken -examples"

"get-help Set-PINOnUserToken -detailed"

"get-help Set-PINOnUserToken -full"

Example 1

To set a PIN of '1234' on a token with common name (CN) GO0030050050277, which has been assigned to a user with CN "Bob Smith":

Set-PINOnUserToken "Bob Smith" GO0030050050277 1234

Example 2

To set a PIN of '1234' on a token with common name (CN) GO0030050050277, which has been assigned to a user with CN "Bob Smith" using a specified User and Token Search Base:

Set-PINOnUserToken "Bob Smith" GO0030050050277 1234 -UserSearchBase

"CN=Users,DC=mydomain,DC=Local" -TokenSearchBase

(43)

Set-TemporaryResponse

To set a temporary token response on a token that has been assigned to a user account and specify the expiry date and whether the temporary token response can be used once only or multiple times.

If the token assigned to the user has a PIN assigned then the PIN must be used with the temporary token response.

Syntax

Set-TemporaryResponse [-UserCommonName] <string> [-TokenCommonName] <string>

[-ExpiryTimeMinutes] <string> [-MultipleUse] [-UserSearchBase <string>]

[-TokenSearchBase <string>] [<CommonParameters>]

Parameters

UserCommonName

Common name of the user to whom the temporary response will be assigned. TokenCommonName

Common name of the token to which the temporary response wil be assigned. ExpiryTimeMinutes

The time, in minutes, for which the temporary response is valid. MultipleUse

Optional parameter, if specified then temporary response can be used multiple times. UserSearchBase

Remarks

"get-help Set-TemporaryResponse -examples"

"get-help Set-TemporaryResponse -detailed" For technical information, type:

(44)

Example 1

To set a temporary token response on a token with common name (CN) GO0061454569921, which has been assigned to a user with CN "Bob Smith" that will expire in 1 day and can only be used once:

Set-TemporaryResponse "Bob Smith" GO0061454569921 1440

When the above cmdlet is used the temporary token response and expiry date / time will be listed as in the example below:

User "Bob Smith" can then use a temporary token response of '600202' once within the next 1440 minutes (1 day).

Example 2

To set a temporary token response on a token with common name (CN) GO0061454569921, which has been assigned to a user with CN "Bob Smith" that will expire in 7 days and can be used multiple times:

Set-TemporaryResponse "Bob Smith" GO0061454569921 10080 -MultipleUse

When the above cmdlet is used the temporary token response and expiry date / time will be listed as in the example below:

User "Bob Smith" can then use a temporary token response of '800750' multiple times within the next 10080 minutes (7 days).

Example 3

To set a temporary token response on a token with common name (CN) GO0061454569921, which has been assigned to a user with CN "Bob Smith" that will expire in 7 days and can be used multiple times specifying a User and Token Search Base:

Set-TemporaryResponse "Bob Smith" GO0061454569921 10080 -MultipleUse -UserSearchBase

"CN=Users,DC=mydomain,DC=Local" -TokenSearchBase

(45)

Test-DefenderToken

This cmdlet tests a Defender token's response. Syntax

Test-DefenderToken [-TokenCommonName] <string> [-Response] <string>

[[-Challenge] <string>] [-TokenSearchBase <string>] [<CommonParameters>]

Parameters

TokenCommonName

Common name of the token to test. Response

The token response. Challenge

The token challenge, not required for synchronous tokens. TokenSearchBase

Remarks

"get-help Test-DefenderToken -examples"

"get-help Test-DefenderToken -detailed"

"get-help Test-DefenderToken -full"

Example 1

To test the current token response, 980536, for a synchronous token with common name GO0061454569921:

Test-DefenderToken GO0061454569921 980536

If the response is not valid a message 'Token test failed' will be displayed.

Example 2

To test the current token response for a challenge / response token with common name PDWIN3053600081, where 457939 is the challenge and 363954 the response: