Manage Users and Roles

[edit on GitHub]

This topic describes the roles and permissions that may be assigned to users of Chef Automate, how to integrate an LDAP system with Chef Automate, how to add and edit users, and how to add user SSH keys.

Roles and Permissions

Chef Automate has a standard users and roles permissions scheme. Roles are sets of permissions defined by Chef Automate. Users can be assigned multiple roles.

Integrate LDAP

You can configure Workflow to access your own LDAP database.

LDAP Attributes

The following table describes the LDAP attributes that may be used with Workflow:

Configure LDAP

To configure LDAP for Workflow:

1. Open /etc/delivery/delivery.rb and enter the LDAP attributes you want Workflow to use. If you do not specify an LDAP port, the default port of 3269 is used.

   delivery['ldap_hosts'] = ['ldap.tld']
   delivery['ldap_port'] = 3269
   delivery['ldap_timeout'] = 5000
   delivery['ldap_base_dn'] = 'OU=Employees,OU=Domain users,DC=opscodecorp,DC=com'
   delivery['ldap_bind_dn'] = 'ldapbind'
   delivery['ldap_bind_dn_password'] = 'secret123'
   delivery['ldap_encryption'] = 'start_tls'
   delivery['ldap_attr_login'] = 'sAMAccountName'
   delivery['ldap_attr_mail'] = 'mail'
   delivery['ldap_attr_full_name'] = 'fullName'
   

2. Run the following command to complete the configuration process:

   sudo automate-ctl reconfigure
   

Once Workflow is set up, you will have a usable LDAP option in the Workflow Users page that allows you to find users through your LDAP database.

Manage Users

Integrating Workflow with your LDAP system allows you to automatically add more user details and authenticate users against your existing identity management system. However, even once your LDAP system has been integrated to Workflow, you must manually add users. If you are going to add a user in your integrated LDAP system to Workflow, you must have their LDAP name.

Add

To add or edit a user to Workflow:

1. Log into the Workflow web UI as an administrator.

2. Select Users from the drop-down menu on the upper right.

   The Users list page opens. You can use the search filter in the upper right corner to make sure that the user is not already added.

3. Click the plus sign (+) next to Add a New User.

4. In the Add New a User text area, select one of two types for user. The selection box is grey for the active selection.

   • Internal means you are manually adding the user to the Workflow database.
   • LDAP means the user is in an LDAP system that has been integrated to this Workflow.

   If you select Internal, options for Name and Email, first name, last name, email address, and Security Information, a login name and password, appear.

   If you select LDAP, the Name and Email options go away and a Security Information option for the user’s LDAP username and SSH public key appears.

5. Enter the appropriate information for the type of user you are adding. Leave the SSH Public Key area blank, the user must log in and enter this information.

   Select user Roles Within the Enterprise.

   Click Save and Close, or Cancel to discard the operation.

   The User list page opens and a status message appears.

To check that the user was added properly when using LDAP, click Edit and verify that the user details are present.

Edit

To edit LDAP details for a user:

1. Log into the Workflow web UI as an administrator.

2. Select Users from the drop-down menu on the upper right.

   The Users list page opens. You can use the search filter in the upper right corner to make sure that the user is not already added.

3. Click the plus sign (+) next to Add a New User.

4. In the Add New a User text area, select one of two types for user. The selection box is grey for the active selection.

   Internal means you are manually adding the user to the Delivery database.

   LDAP means the user is in an LDAP system that has been integrated to this Workflow.

   If you select Internal, options for Name and Email, first name, last name, email address, and Security Information, a login name and password, appear.

   If you select LDAP, the Name and Email options go away and a Security Information option for the user’s LDAP username appears.

5. Enter the appropriate information for the type of user you are adding. Leave the SSH Public Key area blank. The user must log in and enter this information.

   Select user Roles Within the Enterprise.

   Click Save and Close, or Cancel to discard the operation.

   The User list page opens and a status message appears.

To check that the user was added properly when using LDAP, click Edit and verify that the user details are present.

Onboard Users

Onboarding users to a project is different depending on whether you have integrated with GitHub or not.

Chef Automate with GitHub

Once a project is created, you will want to add users to that project so that they can submit changes and collaborate via the Chef Automate shared workflow using GitHub.

You may integrate Chef Automate and GitHub Enterprise or GitHub.com. If you do this, you will be able to use GitHub as a Source Code Provider when creating a project.

Add Users

You must associate a GitHub user with a Chef Automate user in order to successfully create changes from GitHub pull requests.

To onboard a user for an integrated GitHub Enterprise project or one that is hosted at GitHub.com:

1. Have the user that you want to add clone the repo for the project you want them to join. Ensure that they have write permissions to the repo if you want to allow them to submit pull requests.

2. Add or edit any users who are managed by the LDAP integration.

3. From a local checkout of a Chef Automate project, run the appropriate Chef Automate command that associates a GitHub user with a Chef Automate user.

   Note

   The Delivery CLI commands are for a user to link their own account to GitHub, or others if the user has the Admin role; api is an argument to the Delivery CLI command. The automate-ctl command can only be run by an administrator from the Chef Automate server and can affect any user.

   For GitHub Enterprise:

   delivery api put users/$AUTOMATE_USERNAME/set-oauth-alias --data='{"app_name":"github-enterprise","alias":"$GITHUB_USERNAME"}'
   

   For GitHub:

   delivery api put users/$AUTOMATE_USERNAME/set-oauth-alias --data='{"app_name":"github","alias":"$GITHUB_USERNAME"}'
   

   Or, as an administrator, run the command line tool automate-ctl. The command uses the enterprise name you set when configuring Chef Automate. The username can be an LDAP username (if LDAP integration has been completed), or an internal username:

   For GitHub Enterprise:

   automate-ctl link-github-enterprise-user $AUTOMATE_ENTERPRISE_NAME $AUTOMATE_USERNAME $GITHUB_USERNAME
   

   For GitHub:

   automate-ctl link-github-user $AUTOMATE_ENTERPRISE_NAME $AUTOMATE_USERNAME $GITHUB_USERNAME
   

The associated user can now checkout the repository, make changes on a feature branch and submit the changes for review.

Note the following constraints:

• You may not link two GitHub accounts to a single Chef Automate user.
• Two users may not share a GitHub account

Submit Changes

For an integrated GitHub Enterprise project or a project that is hosted on GitHub.com, users of Chef Automate should submit changes as follows:

1. The standard GitHub process should be followed:

   • Clone the desired repository
   • Make and test changes locally
   • Submit the changes and initiate the Chef Automate review process by creating a pull request with the delivery review command

   The GitHub webui will display a Delivery Status box showing what part of the pipeline the pull request is at. When the pull request has passed the Verify stage, GitHub will message you in the GitHub webui that approval must be manually entered for the pipeline to proceed.

2. When the “Approval Required” message appears, enter @delivery approve in the comment box.

   The pull request moves to the next stage of the Chef Automate pipeline, Build and Acceptance.

3. When the pull request has passed the Acceptance stage, GitHub will add another message indicating that that the deliver command must be issued for the pipeline to proceed. When this message appears, enter @delivery deliver in the comment box.

   The pull request moves to the final three stages, Union, Rehearsal, and Delivered. Other changes in the pipeline that would conflict with a change in the Union stage, are blocked from proceeding to the Acceptance stage.

   When the final Delivered stage is passed, GitHub updates the Delivery Status at the top of the GitHub webui page.

Chef Automate with Internal git

Once a project is created, you will want to add users to that project so that they can submit changes and collaborate via the Chef Automate shared workflow. These procedures apply to Chef Automate deployments that are using the internal Chef Automate git capabilities and are not integrated to GitHub Enterprise or GitHub.com.

Add Users

To onboard a user that is not using GitHub Enterprise or a project hosted at GitHub.com, but only the default git that comes with Chef Automate:

1. Add or edit any users who are managed by the LDAP integration.
2. Have the user log into the Chef Automate web UI and add their SSH public key to their profile.

The associated user can now create a feature branch and submit changes to Chef Automate for review.

Submit Changes

The change submission process is the familiar git process:

1. You must be onboarded to Chef Automate, a task likely to be done by your sysadmin. Once your GitHub username is linked to your Chef Automate username and you have properly set up a workstation.
2. Clone the GitHub repo to which changes are submitted. Be sure you have the right permissions.
3. Workflow for making changes:
   1. Create feature branch: git checkout -b <feature_branch_name>.
   2. Make changes.
   3. Build and test the changes locally.
   4. Check status: git status.
   5. Add changes: git add . or git add <changed file>.
   6. Commit changes: git commit -m <message>.
   7. Submit changes to delivery: delivery review. The Chef Automate web UI will open to show your change in the pipeline. Note, you may need to be on a VPN to access Chef Automate.
   8. When the change has passed Verify, approve change, or get someone to, by clicking Approve in Chef Automate web UI. Doing this marks you as the “Signed-off-by” user of the change.
   9. After change is approved, sync your local branch to master: git checkout master and then git pull delivery master.
   10. Press the Deliver button in the Chef Automate web UI when it is active. Note that your change may be superseded by another change. That is, if another change in the pipeline is approved (merged to master) and then your change is approved, when Deliver is pressed, both changes are moved to the final three stages. This goes for all approved changes in the pipeline. Also note that changes that would conflict with approved changes will not be moved past Acceptance.

Add User SSH Keys

First install the Delivery CLI, and then generate the user’s SSH keys.

Install the CLI

The Delivery CLI is included in Chef Workstation and can be obtained by installing the latest version.

Configure the CLI

Before you use the Delivery CLI from a workstation, you need to provide it with details such as the URL of the Chef Automate server, and the names of the relevant enterprise, organization, and user. The delivery setup subcommand creates a configuration file named .delivery/cli.toml with the required information.

The placement of the .delivery directory in your file hierarchy is significant. Like git, Delivery CLI commands search the current directory and parent directories to locate server settings. Because server settings are unique to an organization, we recommend that you create a directory for each organization you belong to and run the delivery setup command from that directory.

delivery setup --server=DELIVERY_SERVER_IP_ADDR --ent=ENTERPRISE --org=ORGANIZATION --user=USERNAME

The following settings may be added to the .delivery/cli.toml file:

auto_bump

Bumps the cookbook metadata version number automatically when delivery review is run. Default value: false.

Add SSH Keys

To add SSH keys to Chef Automate, do the following:

1. Check for an SSH key:

   cat .ssh/id_rsa.pub
   

   if it returns:

   No such file or directory
   

2. Create an SSH key (without a passphrase):

   ssh-keygen -t rsa -b 4096 -C "[email protected]"
   

   The output is similar to:

   Generating public/private rsa key pair.
   Enter file in which to save the key (/Users/username/.ssh/id_rsa):
   Enter passphrase (empty for no passphrase):
   Enter same passphrase again:
   Your identification has been saved in /Users/path/to/.ssh/id_rsa.
   Your public key has been saved in /Users/path/to/.ssh/id_rsa.pub.
   The key fingerprint is:
   ac:8a:57:90:58:c1:cd:34:32:18:9d:f3:79:60:f3:41 [email protected]
   The key's randomart image is:
   +--[ RSA 4096]----+
   |  .==*o.E        |
   |  . *o*..        |
   |   o + = .       |
   |  . o o.o        |
   |     . ..S       |
   |      ..         |
   |     ..          |
   |   .*o*.         |
   |  ...            |
   +-----------------+
   

3. Run the following:

   cat .ssh/id_rsa.pub
   

   The output is similar to:

   ssh-rsa
   AAAAB3NzaC1yc2EAAAADAQABAAACAQDa8BR/9bj5lVUfQP9Rsqon5qJMkiVm+JAtGi
   wnhxqgyRhkYLIzm6+gcifDgMOMuwZA88Ib5WNRhxjlmTseapower4rH/jAAczdp1h1
   7xLEEbUfQfkcqiy/Drp3k12345678ad234fgvdsasdfasdfR9ddNIeNvQ7OIpOCfLE
   PCyFz3aRRuhpM/5cySFT7bl1O44bNgfiuqRzcXFscZb03WPlhaPwCvL2uxaRzdrAGQ
   mE5jzCo6nORvKoGdVDa2++def33f3xPZCo3oJ08Q9XJ2CnfJlmyNe1hwI2NOQ3yRbc
   nfSMona7ccSyHRWGs5bS//u6P0NK5AqH5jK8pg3XwtHZqLwUVy1wX0WnnJWg9IWXf3
   2g3P4O4NJGVUeX33Czv32GK8YphuEweqFu/Ej7kQp1ppIxkEtrpBfMi3na0QqZlk6w
   wghZLa++DUfWOhGsuuBgnsocAR5rLGy+gkypdie1Ydoe8qjLVZR/jKybQfQjuZOS30
   fZnwJhl2ZaeraPfkEXlVhK02/8PIALGfeXdt9KvQN0p5c6lRoDxqBqslM+1KbKKcGd
   lSGEsAIP9OOWBECRxlOwqlqGHtrgWKOr376dntMIy2+fFD/74tJMjRwbRzm8IGWmj6
   OcF6EvTYYO4RmISD8G+6dm1m4MlxLS53aZQWgYWvRdfNB1DA
   Zo3h9Q== [email protected]
   

4. Copy the SSH key and add it to Chef Automate.

   Log into the Chef Automate web UI as an administrator.

   Select Users from the drop-down menu on the upper right.

   On the Users list page, select the user name; use the search filter in the upper right if needed.

   Under Security Information, paste the SSH key.

   Click Save & Close.

5. Setup Chef Automate for that user. Run the following:

   delivery setup --server SERVER_DNS --user USERNAME --ent ENTERPRISE --org ORGANIZATION
   

   The output is similar to:

   Chef Delivery
   Loading configuration from /Users/USERNAME
   Writing configuration to /Users/USERNAME/.delivery/cli.toml
   New configuration
   -----------------
   api_protocol = "https"
   enterprise = "ENTERPRISE"
   git_port = "8989"
   organization = "ORGANIZATION"
   pipeline = "master"
   server = "SERVER_DNS"
   user = "USERNAME"
   

6. Clone a repo from Chef Automate:

   delivery clone PROJECT_REPO
   

   The output is similar to:

   Chef Delivery
   Loading configuration from /Users/USERNAME/Desktop
   Cloning ssh://USERNAME@chef@SERVER_DNS:8989/ENTERPRISE/ORGANIZATION/PROJECT to PROJECT
   The authenticity of host '[SERVER_DNS]:8989 ([10.100.10.50]:8989)' can't be established.
   RSA key fingerprint is 42:8d:92:31:9e:55:b0:06:28:b7:35:a9:4a:87:47:9d.
   Are you sure you want to continue connecting (yes/no)? yes
   adding remote delivery: ssh://USERNAME@ENTERPRISE@SERVER_DNS:8989/ENTERPRISE/ORGANIZATION/PROJECT
   

The user can now create a local branch, make and submit changes to Chef Automate.