AWS Identity and Access Management
Using IAM
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

Managing Server Certificates

This section describes the process of uploading a server certificate to use with AWS products through IAM.

Server certificates are used in some AWS services, including the following:

For a complete list of all the commands and APIs available for working with server certificates in AWS, see Working with certificates with the IAM API, AWS CLI, and Tools for Windows PowerShell.

Managing your server certificates

Getting your server certificate

You can create a certificate manually by following the steps at Creating a Server Certificate, or by using any available third-party tool that allows you to create a certificate and get it signed by a certificate authority (CA).

Upload a signed server certificate to IAM

When you receive a server certificate from a certificate authority (CA), you can upload the certificate to IAM along with the private certificate and a certificate chain. After you upload the certificates to IAM, the certificates are available for other AWS services to use.

To upload server certificates on IAM, you use the AWS command line interface. For more information, see the AWS Command Line Interface User Guide.

Note

A certificate authority might return a certificate in a format that is not supported by IAM. You can convert the certificate to the correct format (X.509 PEM) by using OpenSSL. The specific command depends on the current format of your certificate.

To upload your certificate, you need three files:

  • Your server certificate in PEM format.

  • Your private key in PEM format.

  • A certificate chain file. This contains all the intermediate certificates and the root certificate of the CA. The certificate chain lets an end user's browser build a certificate chain to a root certificate it trusts. As a result, the browser can implicitly trust your certificate.

Examples of all three are shown in Sample Certificates below. You can upload all three files from the command line with one command.

To upload a server certificate

  • Use the aws iam upload-server-certificate command to upload a signed certificate:

    aws iam upload-server-certificate --server-certificate-name certificate_object_name --certificate-body file://public_key_certificate_file --private-key file://privatekey.pem --certificate-chain file://certificate_chain_file

    When you upload your certificates, IAM validates the certificates with the following criteria:

    • Certificates must follow the X.509 PEM format.

    • The current date must be between the certificate’s start and end date.

    • Public and private certificate files must contain only a single certificate.

    • The private key must match the public key that is in the certificate.

    • The private key must be an RSA private key in PEM format, where the PEM header is BEGIN RSA PRIVATE KEY and the footer is END RSA PRIVATE KEY (as shown in Sample Certificates).

    • The private key cannot be encrypted with a password.

    • The certificate chain file must include all of your CA’s intermediary certificates that lead to the root certificate, and ends with your CA’s root certificate. Typically, both intermediary and root certificates are provided by a CA in a bundled file with the proper chained order. If a certificate bundle is not available or not available in the required order, you can create your own file similar to the sample certificate chain in Sample Certificates. Use the intermediary certificates that were provided by your CA. Any intermediaries that are not involved in the chain of trust path must not be included.

    Note

    Notice that when you specify a file as a parameter (for example, for the certificate-body and private-key parameters), you include file:// as part of the file name. These parameters expect the contents of the file, not the file name, and the file:// prefix in front of the file name performs that read operation for you.

    If you are uploading a self-signed certificate and it's not important that browsers implicitly accept the certificate, you can omit the --certificate-chain option and upload just the server certificate and private key, as shown in the following example:

    aws iam upload-server-certificate --server-certificate-name certificate_object_name --certificate-body file://public_key_certificate_file --private-key file://privatekey.pem

    CloudFront: If you are uploading a server certificate specifically for use with Amazon CloudFront distributions, you must specify a path using the --path option. The path must begin with /cloudfront and must include a trailing slash (for example, /cloudfront/test/). Enter the following command:

    aws iam upload-server-certificate --server-certificate-name certificate_object_name --certificate-body file://public_key_certificate_file --private-key file://privatekey.pem --certificate-chain file://certificate_chain_file --path /cloudfront/path/

You assign your own name to the certificate (the certificate_object_name parameter in the preceding commands). For information about limitations on server certificate names, see Limitations on IAM Entities.

For the Amazon CloudFront example, the command displays the ARN and unique ID of the uploaded certificate. If you use the CloudFront API to add a certificate to a distribution, you need the certificate ID. (If you use the CloudFront console for this task, the console displays the certificate name that you specified in the --server-certificate-name option.) For more information about using server certificates with CloudFront, see Using an HTTPS Connection to Access Your Objects in the Amazon CloudFront Developer Guide.

  • After you upload your certificate chain to AWS, you can use SSL Checker to verify it.

    Note

    • The order of intermediary certificates should be documented by the CA. AWS does not recommend any one CA. For a listing of some CAs, see Third-Party Certificate Authorities.

    • Although the root certificate is optional, you can include it so that you can run full chain of trust verifications, such as SSL Checker.

If you have certificates that result in an error when you upload them, ensure that they meet the criteria, and then try uploading them again.

To see sample certificates that are valid with IAM, see Sample Certificates.

Note

If you are having difficulties uploading a server certificate, you might find it helpful to follow the steps outlined in the following blog post: Setting up SSL on an Amazon Elastic Load Balancer.

Verify the IAM Certificate Object

After the server certificate is uploaded, you can verify that the information is stored in IAM. Each certificate object has a unique Amazon Resource Name (ARN) and ID. You can request these details for a specific certificate object by referencing the name of the certificate object.

To view the certificate object's ARN and ID

  • Use the aws iam get-server-certificate command to verify the certificate object:

    aws iam get-server-certificate --server-certificate-name certificate_object_name

    The output will look similar to the following example.

    arn:aws:iam::Your_AWS_Account_ID:server-certificate/Your_Certificate_Object_Name Certificate_Object_GUID

You have now completed the process for creating and uploading a signed certificate. For information about setting up an Elastic Load Balancing load balancer with HTTPS support, see the AWS Command Line Interface (AWS CLI) examples in the How to Set Up a Load Balancer with HTTPS Support section of the Elastic Load Balancing Developer Guide.

Renaming Server Certificates

When you rename a server certificate (using the aws iam update-server-certificate CLI command or the UpdateServerCertificate API), the unique ID for the server certificate remains the same (for more information about ID, see Unique IDs in IAM Identifiers). However, IAM does not automatically update policies that refer to the server certificate as a resource to use the new name. You must manually do that. For example, Bob is a developer in the company ABC and has a policy attached to him that lets him manage the company's build server certificate, arn:aws:iam::123456789012:server-certificate/abc/certs/build. If an admin changes the name of the build server certificate to build_01 or changes the path for the server certificate, the admin also needs to update the policy attached to Bob to use the new name or path so that Bob can continue to manage that server certificate.

Delete an IAM Certificate Object

If you no longer need a certificate, you can delete it.

To delete a certificate object

  • Use the aws iam delete-server-certificate command to remove an individual certificate.

    aws iam delete-server-certificate --server-certificate-name certificate_object_name

    If the command is successful, no output is displayed.

Sample Certificates

The following certificates show the valid format that IAM accepts for server certificates and their associated private key and certificate chain.

The server certificate associates your public key with your identity. When you submit your Certificate Signing Request (CSR) to a certificate authority (CA), a server certificate is returned to you by the CA. The following example shows the format of a server certificate:

-----BEGIN CERTIFICATE-----
your-certificate-here
-----END CERTIFICATE-----

The private key allows you to decrypt messages that are encrypted with your public key. The following example shows the format of a key:

-----BEGIN RSA PRIVATE KEY-----
your-key-here
-----END RSA PRIVATE KEY-----

The certificate chain includes all intermediary certificates that lead to the root certificate, as shown in the following example. Intermediaries that are not involved in the trust path must not be included. The chain ends with your CA’s root certificate. Typically, both intermediary and root certificates are provided by a CA in a bundled file with the proper chained order.

Sample certificate chain

-----BEGIN CERTIFICATE-----
Intermediate certificate 2
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Intermediate certificate 1
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Optional: Root certificate
-----END CERTIFICATE-----