ACCESS MANAGEMENT SERVICE ADMINISTRATOR S TOOLKIT COMMAND REFERENCE GUIDE

(1)

A ^CCESS M ^ANAGEMENT S ^ERVICE

A DMINISTRATOR ’ ^S T ^OOLKIT

C OMMAND R EFERENCE G UIDE

(2)

Copyrights, Trademarks, and Third Party Licenses

Access Management Service Administrator's Toolkit Command Reference, HyperWorks Enterprise, 11.1.0

HWE Compute Manager, HyperWorks Enterprise, PBS™, PBS Works™, PBS GridWorks®, PBS Professional®, PBS Analytics™, PBS Desktop™, PBS Portal™, PBS Animate™, PBS BioChem™, PBS MCAE™, e-BioChem™, e-Compute™ and e-Render™ are trademarks of Altair Engineering, Inc. and are protected under U.S. and international laws and treaties.

All other marks are the property of their respective owners.

Copyright notice does not imply publication. Contains trade secrets of Altair Engineering, Inc.

Decompilation or disassembly of this software is strictly prohibited.

Updated: 9/1/2012.

(5)

1 Introduction to the Toolkit

The Access Management Service (AMS) Toolkit is used to implement authentication and authorization rules for the HyperWorks Enterprise (HWE) web application suite. This guide provides a reference for the list of commands supported by the toolkit.

The HWE installer creates a Super User called amadmin. To use the toolkit initially, a password for the amadmin Super User is required. The screen shown below is displayed during HWE installation for creating the Super User (amadmin) credentials. This is required to perform all initial operations through the Access Management Service Toolkit.

The installer places the toolkit at the following location:

< HWE Installation Folder>\Scripts\AccessManagerAdminToolkit\

Open a command line (console) window at the above location to begin using the toolkit.

Commands of the toolkit can be executed through the command line by the authorized user.

In Windows: AAservice.bat has to be prefixed to all the commands.

In Linux: . /AAService.sh has to be prefixed to all the commands.

(6)

1.1 Changing the Super User (amadmin) Password

To change the amadmin password follow the steps below:

1. Locate the update-ad-password.bat (in Linux: update-ad-password.sh) file at:

< HWE Installation Folder>\Scripts\

2. Execute the following command

In Windows: update-ad-password.bat update-admin-password [oldadminpassword]

[newadminpassword]

In Linux: ./update-ad-password.sh update-admin-password [oldadminpassword]

[newadminpassword]

Example:

If the old password is adminadmin to change it to admin123 execute,

update-ad-password.bat update-admin-password adminadmin admin123

1.2 Updating the Active Directory User Password

The screen below shows the option in the HWE installer to connect AMS to Active Directory.

When AMS is connected to Active Directory, credentials for the Active Directory user needs to be provided. If the password for this user changes, it should be updated in Access Management Service as well.

To update the password of Active Directory user, follow the steps below:

1. Locate the update-ad-password.bat (in Linux: update-ad-password.sh) file at:

< HWE Installation Folder>\Scripts\

2. Execute the following command

In Windows: update-ad-password.bat update [new-ad-password]

In Linux: ./update-ad-password.sh update [new-ad-password]

Example:

If the new password is admin123 execute, update-ad-password.bat update admin123

(7)

2 Toolkit Command Reference

The toolkit commands have been grouped into three sets 1. User Management Commands

2. Group Management Commands 3. Policy Management Commands

Usage of the commands is identical in Linux and Windows. This commands reference can be used for both platforms. In Windows, AAService.bat has to be prefixed to all the commands. In Linux, ./AAService.sh has to be prefixed to all the commands.

For example:

In Windows, to access command specific help type AAService.bat –help <commandname>

In Linux, to access command specific help type ./ AAService.sh –help <commandname>

2.1 User Management Commands

This section describes the following user management commands.

• adduser

• deleteuser

• addug

• removeug

• userlist

• userlistforgroup

• userdetails

In the examples below, the following details are used:

• Example User Id is amadmin

• Example Password is adminadmin

• Application Name is CM

adduser

This command adds the specified user to the datastore Command Syntax

adduser [user_id] [password] [User_Id_Of_New_User] [First_Name_Of_New_User]

[Last_Name_Of_New_User] [User_Password_Of_New_User] [User_Email]

[User_Department]

Example

AAService.bat adduser amadmin adminadmin alice alice doj pwd123 [email protected] CAEDept

Tip: If the password or any other parameter contains special characters like “&” then provide the parameters within double quotes. e.g. “rock&roll”

Caution: Users cannot be added to the AMS datastore using the adduser command if AMS is connected to LDAP (Lightweight Directory Access Protocol).

(8)

4 Toolkit Command Reference

deleteuser

This command deletes the specified user from the datastore Command Syntax

deleteuser <user_Id> <password> <User_ID_To_Be_Deleted>

Example

AAService.bat deleteuser amadmin adminadmin alice

Tip: To see all the users in datastore execute command userlist

Caution: If AMS is connected to LDAP then using deleteuser command, users cannot be deleted from LDAP datastore

addug

This command adds the specified user to the specified group.

The specified user and group must exist in the server datastore Command Syntax

addug <user_Id> <password> <User_ID_That_Should_Be_Added_To_The_Group>

<Group_Name_For_Which_The_User_Should_Be_Added>

Example

AAService.bat addug amadmin adminadmin alice RefreeGroup

Tip: By executing this command LDAP users can be added to AMS groups

removeug

This command removes the specified user from the specified group.

Command Syntax

removeug <user_Id> <password>

<User_ID_That_Should_Be_Removed_From_The_Group>

<Group_Name_From_Which_The_User_Should_Be_Removed>

Example

AAService.bat removeug amadmin adminadmin alice RefreeGroup Caution: Does not remove the user from the server datastore.

(9)

userlist

This command returns a list of users that are present in the server datastore Command Syntax

userlist <user_id> <password>

Example

AAService.bat userlist amadmin adminadmin

userlistforgroup

This command returns a list of users that the group contains in the server datastore Command Syntax

userlistforgroup <user_id> <password> <group >

Example

AAService.bat userlistforgroup amadmin adminadmin RefreeGroup

userdetails

This command gets the details of the user requested Command Syntax

userdetails <user_id> <password> <user_name>

Example

AAService.bat userdetails amadmin adminadmin alice

(10)

2.2 Group Management Commands

This section describes the following user group management commands.

• addgroup

• deletegroup

• grouplist

• grouplistforuser

• addsubgroup

• removesubgroup

• subgroupforparentgroup

• parentgroupforsubgroup

• setprivilege

• removeprivilege

addgroup

This command adds the specified group to the datastore Command Syntax

addgroup <user_Id> <password> <Group_name_For_The_new_Group>

Example

AAService.bat addgroup amadmin adminadmin RefreeGroup

Caution: Independent of the datastore connected (either LDAP or AMS) groups are created only in AMS datastore

deletegroup

This command deletes the specified group Command Syntax

deletegroup <user_Id> <password> <Group_name_To_Be_Deleted>

Example

AAService.bat deletegroup amadmin adminadmin RefreeGroup

Tip: To see all the groups in datastore execute command grouplist

Caution: Independent of the datastore connected (either LDAP or AMS) only AMS datastore groups can be deleted

grouplist

This command returns a list of groups that are present in the server datastore Command Syntax

grouplist <user_id> <password>

Example

AAService.bat grouplist amadmin adminadmin

Tip: If connected to LDAP then the grouplist command returns the combined list of the LDAP and AMS groups

(11)

grouplistforuser

This command returns a list of groups that the user belongs to in the server datastore Command Syntax

grouplistforuser <user_id> <password> <user_first_name>

Example

AAService.bat grouplistforuser amadmin adminadmin alice

addsubgroup

This command adds a sub-group to the specified parent group Command Syntax

addsubgroup <user_id> <password> <parent_group_name> <sub_group_name>

Example

AAService.bat addsubgroup amadmin adminadmin admin sub-group

Caution: Independent of the datastore connected (either LDAP or AMS) sub-groups are created only in AMS datastore

removesubgroup

This command removes a specified sub-group from parent group Command Syntax

removesubgroup <user_id> <password> <parent_group_name> <sub_group_name>

Example

AAService.bat removesubgroup amadmin adminadmin admin subgroup

Caution: Independent of the datastore connected (either LDAP or AMS) only AMS datastore sub-groups can be deleted

subgroupforparentgroup

This command gets the list of sub-groups for a specified group Command Syntax

subgroupforparentgroup <user_id> <password> <parent_group_name>

Example

AAService.bat removesubgroup amadmin adminadmin admin

(12)

parentgroupforsubgroup

This command gets the list of all parent groups for the specified sub-group Command Syntax

parentgroupforsubgroup <user_id> <password> <sub_group_name>

Example

AAService.bat removesubgroup amadmin adminadmin subgroup

setprivilege

This command sets the admin privilege for the specified Group Command Syntax

setprivilege <user_id> <password><group_name>

Example

AAService.bat setprivilege amadmin adminadmin AdminGroup

Tip: On executing setprivilege command, all the users who are members of the group will get admin privilege

Caution: Independent of the datastore connected (either LDAP or AMS) only AMS datastore groups can be given admin privilege

removeprivilege

This command removes the admin privilege for the specified Group Command Syntax

removeprivilege <user_id> <password> <group_name>

Example

AAService.bat removeprivilege amadmin adminadmin AdminGroup

Caution: Independent of the datastore connected (either LDAP or AMS) only AMS datastore groups can be removed from admin privilege

(13)

2.3 Policy Management Commands

This section describes the following policy management commands.

• import

• export

• createapp

• deleteapp

• actions

• cacheupdatedtime

• addresource

• deleteresource

• resourcelist

• addpolicy

• getpolicy

• removepolicy

import

This command imports a set of policies into the server. The policies must be stored in an XML file. For more details on the policy file and its syntax, refer to the Sample Policy File section of this document. We have provided detailed comments in it.

Command Syntax

import <user_Id> <password> <Policy_file_path_To_Upload> <application_name>

Example

AAService.bat import amadmin adminadmin C:/CMpolicy.xml CM

Tip: Before executing import, execute an export command which returns all the policies for an application in xml format. The obtained xml can be modified and imported back to AMS using import command

Caution: On executing import command all the old policies for an application will be removed and new polices will be applied. It is recommended to use export command and backup the policies

export

This command exports the policies to a specified file on the local system Command Syntax

export <user_Id> <password><application_name>

<file_path_To_Export_The_Policies>

Example

AAService.bat export amadmin adminadmin CM C:/CMpolicyExport.xml

Tip: To view all the policies for an application in xml format execute export policies which writes xml file into a specified file on the local system.

(14)

createapp

This command creates the new application in the server with the specified action list.

Policies for an application can be created for the action list provided with this command.

Actions list describes the actions that are performed on a resource for an application.

Command Syntax

createapp <user_Id> <password> <Application_Name> <ActionList>

Example

AAService.bat createapp amadmin adminadmin CM submit checkin checkout

deleteapp

This command deletes the specified application from the server Command Syntax

deleteapp <user_Id> <password> <Application_Name>

Example

AAService.bat deleteapp amadmin adminadmin CM

Caution: On executing deleteapp command, all the policies for the application specified will be deleted

actions

This command returns a list of actions applicable for the specified application Command Syntax

actions <user_id> <password><application_name>

Example

AAService.bat actions amadmin adminadmin CM

cacheupdatedtime

This command returns the time when the cache was last updated Command Syntax

cacheupdatedtime <user_id> <password>

Example

AAService.bat cacheupdatedtime amadmin adminadmin

(15)

addresource

This command adds the resource to the application. Refer to the Sample Policy File section for specific instructions for this format.

Command Syntax

addresource <user_id> <password> <application_name>

<resource_name_to_be_added>

Example

AAService.bat addresource amadmin adminadmin CM job/complete/readonly

Tip: Execute resourcelist command to get all the resources for an application.

Caution: To create a resource for an application the parent resource must exist in the AMS datastore

deleteresource

This command deletes the resource from the application Command Syntax

deleteresource <userid> <password> <applicationname>

<resource_name_to_be_deleted>

Example

AAService.bat deleteresource amadmin adminadmin CM job/complete/readonly

Caution: On executing delete resource command, all the child resources and policies under the specified resource will be deleted.

resourcelist

This command gets the list of resources for the specified application Command Syntax

resourcelist <user_id> <password> <application_name>

Example

AAService.bat resourcelist amadmin adminadmin CM

(16)

addpolicy

This command adds policy to the Server datastore.

The policy details must be available in the properties file provided along with the toolkit.

The Addpolicy.properties file is located at:

< HWE Installation Folder>\Scripts\AccessManagerAdminToolkit\

Command Syntax

addpolicy <user_id> <password> <AddPolicy.properties file path>

Example

AAService.bat addpolicy amadmin adminadmin AddPolicy.properties

getpolicy

This command gets the policy details from the server for specified application and resource

Command Syntax

getpolicy <user_id> <password> <policyName>

<application_name_of_the_policy><resource_name_of_the_policy>

Example

AAService.bat getpolicy amadmin adminadmin MusicPolicy AltairMusicCatalyst Music/DJ

removepolicy

This command removes the specified policy from the application specified Command Syntax

removepolicy <user_id> <password><policyName>

<application_name_of_the_policy>

Example

AAService.bat removepolicy amadmin adminadmin MusicPolicy AltairMusicCatalyst

(17)

3 Error Codes

This section describes error codes, the reason for the errors and related commands.

Error Code No.100: LoginException Error Code No.101: JDOMException Error Code No.102: IOException

Error Code No.103: ApplicationNotFoundException_Exception Error Code No.104: InvalidPolicyException_Exception

Error Code No.105: InvalidResourceException_Exception Error Code No.106: PolicyNotFoundException_Exception Error Code No.107: IdentityException_Exception

Error Code No.108: InvalidApplicationException_Exception Error Code No.109: InvalidXmlException_Exception

Error Code No.110: UnAuthorizedUserException_Exception Error Code No.111: PrivilegeException_Exception

Error Code No.112: Generic Exception

Error Code No.100 LoginException

Reason for Error

1. “Null” username and password is provided during execution of a command 2. Invalid user credentials are provided during execution of a command Related Commands

Login

Error Code No.101 JDOMException

1. If the policy structure is invalid on exporting policies back to xml file.

Related Commands export

Error Code No.102 IOException

1. If the file exists but is a directory rather than a regular file 2. File does not exist but cannot be created as well (export) 3. File cannot be opened for any other reason

4. File specified doesn’t exist (addpolicy)

Related Commands export, addpolicy

(18)

Error Code No.103 ApplicationNotFoundException_Exception

1. If the application name is “Null”

2. If the application is not registered with AccessManagement Service before creating policies for application.

Related Commands

import, export, actions, addresource, deleteresource, resourcelist, addpolicy, getpolicy, removepolicy

Error Code No.104 InvalidPolicyException_Exception

1. If the policy structure doesn’t adhere to the schema (import)

2. During import policy if the application name (service name) specified in the file doesn’t match with the application specified as parameter.

3. Policy name is empty or “null”

4. Policy contains duplicate subject_type 5. Policy contains duplicate subject values

6. Policy with specified name already exists in server for that application (addpolicy) 7. Policy contains duplicate action names

8. The actions specified for the policy is not registered during registration of Application

9. If the subject type is not one of the following :

• DEFAULT_GROUP

• DEFAULT_USER

• AuthenticatedUsers

Related Commands import, addpolicy

Error Code No.105 InvalidResourceException_Exception

1. Resource name is null or empty 2. Trying to add duplicate root resource

3. If the child resource doesn’t start with parent resource 4. Resource ends with a “\”

5. Trying to add duplicate resource for an application 6. Adding child resource without adding parent resource 7. If the child resource is not under a valid parent 8. Specified resource doesn’t exist

import, addresource, deleteresource, resourcelist, addpolicy, getpolicy

(19)

Error Code No.106 PolicyNotFoundException_Exception

1. The specified policy name doesn’t exist for an application Related Commands

export, getpolicy, removepolicy

Error Code No.107 IdentityException_Exception

1. Any parameter values are null or empty 2. Trying to add duplicate user or group 3. Non existing user or group

All User Management Commands, All Group Management Commands.

Error Code No.108 InvalidApplicationException_Exception

1. Application name is null or empty

2. Application doesn’t contain any action during registration (createapp) 3. Duplicate action names (createapp)

4. Creating duplicate application (createapp) 5. Non existing application (deleteapp, actions) Related Commands

createapp, deleteapp, actions

Error Code No.109 InvalidXmlException_Exception

1. XML file used in import policies doesn’t adhere to the schema specified by Access Management Service

Related Commands import

Error Code No.110 UnAuthorizedUserException_Exception

1. If a non-admin user is trying to perform Admin operations in Access Management Service

Related Commands all commands

(20)

Error Code No.111 PrivilegeException_Exception

1. Group name is null on setting or removing admin privilege for a group 2. On specifying non existing group name

3. If the group name specified is already having admin privilege 4. If the group name specified is not having admin privilege Related Commands

setprivilege, removeprivilege

Error Code No.112 Generic Exception

1. Generic error with Access Manager.

Refer to log files or more details for these errors Related Commands

All commands

(21)

4 Sample Policy File

This section provides a fully commented sample policy file in XML format.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Service name="AltairMusicCatalystService">

<Resource name="Music" description="This is Music Resource">

<!--Resource name must not be empty.

Example of Valid Root resource:

a."Music"

b. "/"

c. "/Music".

Example of Invalid Root Resource:

a. "Music/"

b. "Music/Rock"

c. "/Music/Rock"

d. "Music\"

e. "/\"

A resource element can have Resource attributes, Any number of Policies and Any number of of Child Resources.

-->

<ResourceAttributes>

<ResourceAttribute>

<Name>owner</Name>

<Value>jim</Value>

</ResourceAttribute>

</ResourceAttributes>

<Policy name="Music_Policy1">

<Actions> 

<Action>

<Name>READ</Name>

<Value>allow</Value>

</Action>

<Action>

<Name>CREATE</Name>

</Action>

</Actions>

<Subjects>

<Subject type="DEFAULT_USER">

<Value>bill</Value>

(22)

<Value>joe</Value>

</Subject>

<Subject type="DEFAULT_GROUP">

<Value>admin</Value>

<Value>manager</Value>

</Subject>

<Subject type="AuthenticatedUsers">

<Value>admin</Value>

<Value>manager</Value>

</Subject>

</Subjects>

<PolicyAttributes>

<PolicyAttribute>

<Name>policyType</Name>

<Value>regular</Value>

</PolicyAttribute>

</PolicyAttributes>

</Policy>

<Policy name="Music_Policy2">

<Actions>

<Action>

</Action>

</Actions>

<Subjects>

<Value>joe</Value>

</Subject>

</Subjects>

</Policy>

(23)

<Resource name="Music/Rock" description="This is Music/Rock Resource">

<Value>jim</Value>

<Policy name="MusicRock_Policy1">

<Actions>

<Action>

</Action>

<Action>

<Value>deny</Value>

</Action>

<Action>

<Name>LISTEN</Name>

</Action>

</Actions>

<Subjects>

</Subject>

</Subjects>

</Policy>

<Resource name="Music/Rock/Metallica" description=" Rock Metallica/Resource">

<Policy name="MusicRockMetallica_Policy1">

<Actions>

<Action>

</Action>

<Action>

</Action>

(24)

<Action>

<Name>LISTEN</Name>

</Action>

</Actions>

<Subjects>

</Subject>

</Subjects>

</Policy>

</Resource>

</Service>

ACCESS MANAGEMENT SERVICE ADMINISTRATOR S TOOLKIT COMMAND REFERENCE GUIDE