Set up roles and permissions using the Deploy CLI

This topic describes the default permission settings in Deploy after installation. Initially, no permissions are granted to any user, except for administrator users, who have all permissions.

Deploy has one predefined administrator user called admin, with the default password admin. For more information, see roles and permissions.

Set up roles and permissions in Deploy

To change password strength requirements please refer to Password strength requirements.

Step 1 - Change the admin user's password

To change the admin user's password:

1. Use the Deploy command-line interface (CLI) to Update User details:

adminUser = security.readUser('admin')
adminUser.password = 'newPassword_1'
security.modifyUser(adminUser)

For more information, see getting started with the Deploy command-line interface (CLI)

Note: Only users with admin rights can change the password using this method.

1. Change the password in the XL_DEPLOY_SERVER_HOME/conf/deployit.conf configuration file:

admin.password=newPassword_1

1. Restart the Deploy server.

Note: The password in deployit.conf file is encrypted when the server starts for the first time.

Step 2 - Create new users

To create new Deploy users, execute the following commands in the CLI:

security.createUser('john', 'Secret01')
security.createUser('alice', 'Secret02', 'Alice Smith', 'alice.smith@example.com')
security.createUser('alice', 'Secret02', 'Alice Smith', 'alice.smith@example.com')

When you execute security.createUser('john', 'Secret01'), it creates a new user with the username john and the password Secret01. Similarly, executing security.createUser('alice', 'Secret02', 'Alice Smith', 'alice.smith@example.com') creates a user with the username alice, the password Secret02, the full name Alice Smith, and the email address alice.smith@example.com.

To delete a user, execute:

security.deleteUser('john')

Important: Deploy will only create users in its own repository, even if it is configured to use an LDAP repository for authentication and authorization. You must use an LDAP administration tool to create users in, for example, an LDAP credentials store.

Deploy supports the concept of groups when using LDAP as the credentials store. All groups defined in LDAP can be assigned to roles in Deploy. Users that are part of these groups will be assigned the role permissions when they use the system.

Step 3 - Update user information and change password

If a user's password is forgotten, or there is a need to update other profile information such as their full name, email, or login status, you can execute the following commands in the CLI:

note

You cannot retrieve a user's password because Deploy does not store it as plain text. When requesting and viewing a user CI, passwords will always be shown as follows: ********.

user = security.readUser('alice')
user.password = 'newPassword_1'
user.getUserProfile().setFullName('Deploy Administrator')
user.getUserProfile().setEmail('admin@example.com')
user.getUserProfile().setLoginAllowed(true)
security.modifyUser(user)

In this example:

• The user variable is used to retrieve and store the user object for the user created with the name admin.

• The password is set to newPassword_1. Optional:

• The full name is updated to Deploy Administrator.

• The email address is updated to admin@example.com.

• The login permission is set to true to allow the user to log in.

  Tip:

  • If permission is set to false, the user's login will be disabled.
  • The maximum allowed length for both the full name and email address is 255 characters.
  • If an invalid email address format is entered, an error message is displayed: "The email address 'john' is invalid. Provide a valid email address."

Step 4 - Create roles and assign principals to roles

To assign a role to a user, execute the following command in the CLI:

security.assignRole("developers", ["john"])

This assigns principal john to the developers role. If the role does not exist, Deploy creates it.

note

In Deploy, user principals are not case-sensitive.

Step 5 - Log in as a different user

After the CLI has started, log out of the current user profile. You can see the deployit prompt and you can log in as a different user.

In this example, an administrator is logged in as user alice, and must switch to user admin to delete user john.

security.logout()
security.login('admin', 'admin')

# Delete the user john
security.deleteUser('john')

# Switch back to the account with less privileges
security.logout()

Step 6 - Grant permissions

To grant a particular permission to a role, execute:

security.grant("import#initial", "developers", ['Applications'])

To grant a particular permission to a role within a directory, execute:

security.grant("deploy#initial", "developers", ['Environments/DevelopmentDirectory'])

Permissions required for each role

These are the required permissions for each role.

Role	Permissions required
Administrators	repo#edit permission on the infrastructure and environment trees.
Front-end deployers	Access to the front-end application directory, deploy#initial and deploy#upgrade on environments DEV and TEST, read rights on environment PROD.
Back-end deployers	Access to the back-end application directory, deploy#initial and deploy#upgrade on environments DEV and TEST, read rights on environment PROD.
Senior deployers	import#initial permission for the applications, deploy#initial and deploy#upgrade permission on all environments.
Developers	import#upgrade permission for the applications, deploy#upgrade on the DEV and TEST environments.

Revoke permissions

To revoke a particular permission from a role, execute:

security.revoke("read", "developers")

To revoke a permission from a particular directory:

security.revoke("read", "developers", ['Environments/DevelopmentDirectory'])

Retrieve permissions

The security object is used to find permissions for a certain role along with the permissions for the user that is currently logged in.

important

The security#edit permission is required to retrieve permissions for a role and also to grant or revoke permissions.

• To show your own permissions, execute:

  print security.getPermissions()
• To show the permissions for a particular role, execute:

  print security.getPermissions('rolename')

Both methods return an AssignedPermissions object that shows the relevant permissions when printed. The AssignedPermissions object can be used to retrieve and inspect user permissions, including specific permissions on CIs. You can use this to automate the granting and/or revoking of permissions through a script.

This is an extended example of working with permissions:

security.logout()
security.login('admin', 'admin')
security.createUser('alice', 'al1ce')
security.assignRole('deployer', ['alice'])

if security.isGranted('deployer','login'):
    security.grant('login', 'deployer')

print security.getPermissions('deployer')
security.removeRole('deployer')
security.deleteUser('alice')

Initial security setup example

The following code examples combine together to complete script for this example.

important

Administrator privileges are required to complete this section.

1. Create user and roles and allow them to access Deploy. Execute the following code to create users and grant them access:

note

The passwords in the examples are chosen for clarity. When creating users, choose strong passwords.

# Sample security setup.

deployit> security.createUser('alice', 'al1ce')
deployit> security.assignRole('administrators', ['alice'])
deployit> security.createUser('bob', 'b0b')
deployit> security.assignRole('senior-deployers', ['bob'])
deployit> security.createUser('carol', 'car0l')
deployit> security.assignRole('frontend-deployers', ['carol'])
deployit> security.createUser('dave', 'd@ve')
deployit> security.assignRole('backend-deployers', ['dave'])
deployit> security.createUser('mallory', 'mall0ry')
deployit> security.assignRole('developers', ['mallory'])

deployit> security.grant('login', 'administrators')
deployit> security.grant('login', 'senior-deployers')
deployit> security.grant('login', 'frontend-deployers')
deployit> security.grant('login', 'backend-deployers')
deployit> security.grant('login', 'developers')

# Create some environments
deployit> infraGroup = repository.create(factory.configurationItem('Infrastructure/Dev','core.Directory',{}))
deployit> host = factory.configurationItem(infraGroup.id + '/myHost', 'overthere.SshHost', {
            'os':'UNIX',
            'address':'localhost',
            'username':'deployit',
            'password':'deployit'})
deployit> repository.create(host)
deployit> repository.create(factory.configurationItem('Environments/Dev', 'core.Directory'))
deployit> repository.create(factory.configurationItem('Environments/Test', 'core.Directory'))
deployit> repository.create(factory.configurationItem('Environments/Acc', 'core.Directory'))
deployit> repository.create(factory.configurationItem('Environments/Prod', 'core.Directory'))
deployit> repository.create(factory.configurationItem('Environments/Dev/env', 'udm.Environment',
            { 'members': ['Infrastructure/Dev/myHost'] }))
deployit> repository.create(factory.configurationItem('Environments/Test/env', 'udm.Environment'))
deployit> repository.create(factory.configurationItem('Environments/Acc/env', 'udm.Environment'))
deployit> repository.create(factory.configurationItem('Environments/Prod/env', 'udm.Environment'))
# Import a application
deployit> repository.create(factory.configurationItem('Applications/team1','core.Directory',{}))
deployit> repository.create(factory.configurationItem('Applications/team1/PetClinic-ear','udm.Application',{}))
deployit> deployit.importPackage('PetClinic-ear/1.0')

note

You do not need to specify a list of CIs because the login permission is a global permission.

1. Grant permissions to the administrators role. To create, delete, and update CIs under the root nodes, the read and repo#edit permissions are required on Infrastructure and Environments root nodes.

   deployit> security.grant('read', 'administrators',['Infrastructure', 'Environments'])
   deployit> security.grant('repo#edit', 'administrators', ['Infrastructure', 'Environments', 'Applications'])

note

If you want to grant rights to specific environments to a user with limited administrator privileges, use the following command:

deployit> security.grant('repo#edit', 'administrators', ['Environments/Prod'])

1. Grant a senior-deployer permissions to import and deploy applications to the DEV, TEST, ACC, and PROD environments:

   deployit> security.grant("import#initial", 'senior-deployers', ['Applications'])
   deployit> security.grant("import#upgrade", 'senior-deployers', ['Applications'])
   deployit> security.grant("deploy#initial", 'senior-deployers', ['Environments'])
   deployit> security.grant("deploy#upgrade", 'senior-deployers', ['Environments'])
2. Separate front-end and back-end applications by creating two directories:

   deployit> repository.create(factory.configurationItem('Applications/frontend', 'core.Directory'))
   deployit> repository.create(factory.configurationItem('Applications/backend', 'core.Directory'))
3. Grant the front-end deployer access to front-end applications and back-end access to the back-end deployer. Both roles can deploy to the DEV, TEST, and ACC environments.

   deployit> security.grant("import#initial", 'frontend-deployers', ['Applications'])
   deployit> security.grant("import#upgrade", 'frontend-deployers', ['Applications/frontend'])
   deployit> security.grant("deploy#initial", 'frontend-deployers', ['Environments/Dev', 'Environments/Test',
       'Environments/Acc'])
   deployit> security.grant("deploy#upgrade", 'frontend-deployers', ['Environments/Dev', 'Environments/Test',
       'Environments/Acc'])
   
   deployit> security.grant("import#initial", 'backend-deployers', ['Applications'])
   deployit> security.grant("import#upgrade", 'backend-deployers', ['Applications/backend'])
   deployit> security.grant("deploy#initial", 'backend-deployers', ['Environments/Dev', 'Environments/Test',
       'Environments/Acc'])
   deployit> security.grant("deploy#upgrade", 'backend-deployers', ['Environments/Dev', 'Environments/Test',
       'Environments/Acc'])
4. Grant deployers permission to perform a deployment to the Environments/Prod environment and read permission to see deployments in the production environment.

   deployit> security.grant('read', 'frontend-deployers', ['Environments/Prod'])
   deployit> security.grant('read', 'backend-deployers', ['Environments/Prod'])
5. Grant permissions to the developer role. This role is permitted to import new versions of applications into Deploy and to perform the deployment upgrade to the Dev and Test environments.

   deployit> security.grant("import#upgrade", 'developers', ['Applications/frontend', 'Applications/backend'])
   deployit> security.grant("deploy#upgrade", 'developers', ['Environments/Dev', 'Environments/Test'])

note

In this scenario the developer role can import new versions of both front-end and back-end applications. If there are no specific directories below the applications root node that override the root permissions, the following command gives permissions for all applications in Deploy:

deployit> security.grant('import#upgrade', 'developers', ['Applications'])