Introduction

This is the README file for using sample orchestration scripts to automatically
enroll Linux-based cloud instances to Centrify Identity Platform or
to automatically join the instance to Active Directory.

You need to set up your configuration by modifying the top part of the sample orchestration
script startup-userdata.sh. When you launch the new EC2 instance, you need to upload the script as "user data".

The following platforms are supported:

• Red Hat Enterprise Linux 6.5 or later for 32/64 bit
• Ubuntu Server 14.04 LTS for 32/64 bit
• Ubuntu Server 16.04 LTS
• Amazon Linux AMI 2014.09 for 32 bit
• Amazon Linux AMI 2016.09
• CentOS 7.x
• SUSE Linux Enterprise Server 11 SP4 for 64 bit
• SUSE Linux Enterprise Server 12 SP2

Prerequisite

• You need the following AWS permissions:
  • Full permission to EC2
• If you need to use Centrify Server Suite to join the AWS instance to Active Directory,
  you also need the followings:
  • An AD user who joins the EC2 instance for Linux to your centrify zone.
    You need to make sure that the AD user has following two permissions at least:
  • Delegate Join a computer to the domain in Active Directory Users and Computers.
  • Delegate 'Join computers to the zone' in DirectManage Access Manager.
  • Permission to create and upload files to an S3 bucket
  • permission to create, modify, read, list and delete IAM Policies and Roles
  • An EC2 instance that has Centrify Server Suite installed and joined to your Active Directory.
  • An account in the Centrify Support website. Follow the instructions in https://www.centrify.com/support/customer-support-portal/repos to generate the repo key. Use the string before @repo.centrify.com to set up the parameter CENTRIFY_REPO_CREDENTIAL. For example, if the repo key is 1111111122222233333333333333344444555555:[email protected],
    set
    CENTRIFY_REPO_CREDENIIAL=1111111122222233333333333333344444555555:777888880000099999991234567890abcdefghij

Configuration parameters

You can specify the AWS deployment configuration in the User Data of the AWS instance. You need to download the file startup-userdata .sh and set up the parameter values in the top part of the file. The whole file must be copied to the User Data of the new EC2 instance and/or Auto Scaling group launch configuration.

Centrify Agent for Linux parameters

The following parameters are for enrolling the AWS instances to Centrify Identity Platform.

Notes:

• The AWS instance ID used as the computer name for the created resource. If CENTRIFYCC_COMPUTER_NAME_PREFIX is specified, the computer name
  will be <CENTRIFYCC_COMPUTER_NAME_PREFIX>-<AWS Instance ID>. Otherwise, it will be <AWS Instance ID>.

Centrify Server Suite agent parameters

The following parameters are for joining to Active Directory using the Centrify Server Suite agent.

Note that hostname is limited to 15 characters. If the instance ID is longer than 15 characters, the first 15 characters of instance ID will be used and there is a remote possibility of hostname conflicts. We recommend using PRIVATE-IP address for the hostname.

Deployment process

1. If you do not need to install/deploy Centrify Server Suite agent to join to Active Directory,
   you can skip directly to step 3.
   
   
   Generate login.keytab using the following command on your Linux/Unix that has joined
   to Active Directory:

   adkeytab -A -K login.keytab -u your_admin -p your_admin_password your_ad_user
   

   where
   • your_admin is the name of an user who is permitted to adopt the account your_ad_user
   • your_admin_password is the password of your_admin
   • your_ad_user is the user who joins the instance to Active Directory.

For example:
 ```
 adkeytab -A -K login.keytab -u admin1  -p admin1_pass join_user1
```

2. You need to sign in https://console.aws.amazon.com/s3 to create an S3 bucket and then upload
   login.keytab file (created in step 1) to the bucket. You can refer to
   http://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html about how to create a bucket.

3. Create your Key Pair if you don't have one so that you can log into your EC2 instances. You can refer to
   
   http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#having-ec2-create-your-key-pair about
   how to create Key Pair.

4. Create VPC, subnet and security group for your new EC2 instances.

5. If your AWS instance does not need to join to Active Directory, skip to step 6.
   
   a. Create the following IAM Policy to allow the instance to access the S3 bucket to download the login.keytab file:
   
   

```
{
	"Version": "2012-10-17",
	"Statement": [{ 
		"Effect": "Allow",
		"Action": [
			"s3:GetObject",
			"s3:ListObject"
			],
		"Resource": [
			"arn:aws:s3:::your_s3_bucketname/*"
		]
	}]
}
```

Replace your_s3_bucketname by the name of the S3 bucket that you created in step 2.

b. Create IAM Role for the AWS instance:
- Select IAM Service in AWS Console
- Select Roles, and click on Create New Role.
- Enter your role name, click Next Step.
- Select AWS Service Roles, and select Amazon EC2 in the drop-down list, click Next Step.
- In the Attach Policy page, select the IAM policy created above.
- Keep click Next Step until you have finished the creation process.

6. Download startup-userdata.sh and create a userdata template. See the section Configuration Parameters for more information.

7. Create a new EC2 instance. If you set the configuration parameter CENTRIFYCC_NETWORK_ADDR_TYPE to PublicIP, you need to select your subnet you can access public internet in. Set up user data from the userdata template created in step 6 above.

FAQ

Q. Can I only install CentrifyDC but not join to AD?

Yes. You can set CENTRIFYDC_JOIN_TO_AD to no in the user data. You also do not need to specify CENTRIFYDC_KEYTAB_S3_BUCKET and CENTRIFYDC_ZONE_NAME.

Q. Can I specify additional packages to be installed for CentrifyDC?

Yes. You can specify additional packages in parameters CENTRIFYDC_ADDITIONAL_PACKAGES.

Q. Can I specify additional options for adjoin or cenroll?

Yes. You can specify additional options in parameter CENTRIFYDC_ADJOIN_ADDITIONAL_OPTIONS
or CENTRIFYCC_CENROLL_ADDITIONAL_OPTIONS.

Q. Can I output debug information?

Yes. You can set DEBUG_SCRIPT to yes and the centrifydc.sh/centrifycc.sh will enable 'set -x'.

Q. Can I specify what to use as the network address in created CPS resource?

Yes. You can set parameter CENTRIFYCC_NETWORK_ADDR_TYPE to specify public
IP(set to PublicIP), private IP(set to PrivateIP), or hostname(set to HostName)
as your network address in CPS resource.

Q. Can I specify my computer name in Active Directory while adjoin?

Yes. You can set CENTRIFYDC_HOSTNAME_FORMAT. Currently, we only support using
aws instance id(set to INSTANCE_ID) or private IP(set to PRIVATE_IP) as your computer name.

Q. Why don't I get Public IP while enrolling EC2 for Linux to Centrify identity?

You shall make sure that your AutoScaling/EC2 has enabled public IP assignment and
set CENTRIFYCC_NETWORK_ADDR_TYPE to yes if you want to use public IP as your
address while running cenroll. If you want to use hostname or private IP as your
address parameter of cenroll, you need not a public IP for your EC2 and only need to
set CENTRIFYCC_NETWORK_ADDR_TYPE parameter to PrivateIP or HostName.

Q. Can I view any log output after running startup-userdata.sh?

Yes. You can find the log in /tmp/auto_centrify_deployment/centrifycc/deploy.log
for CentrifyCC and in /tmp/auto_centrify_deployment/centrifydc/deploy.log for CentrifyDC.

Q. What does error "x509: certificate signed by unknown authority" mean?

Your computer needs to be enrolled in Centrify Identity Platform, but none of
the server certificates can be verified. Certificate problems may indicate
potential security risks. Please contact your administrator to configure the
root CA certificate.
References:

• https://centrify.force.com/support/Article/KB-7973-How-to-configure-Linux-machine-trusted-certificate-chain-to-perform-enrollment-for-Centrify-Agent

Q. How to use "user data" to run orchestration script on AWS instances?

From AWS documentation:

"Scripts entered as user data are executed as the root user, so do not use the
sudo command in the script. Remember that any files you create will be owned by
root; if you need non-root users to have file access, you should modify the
permissions accordingly in the script. Also, because the script is not run
interactively, you cannot include commands that require user feedback (such as
yum update without the -y flag)." [1]

"User data is limited to 16 KB." [2]

References:
[1] Running Commands on Your Linux Instance at Launch

• http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html

[2] Instance Metadata and User Data

• http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html