# Use third-party private extensions that have been shared with you
To use third-party private extensions that have been shared with you, you must first *register* them with CloudFormation, in the accounts and Regions where you want to use them. Registering the extension uploads a copy of it to the CloudFormation registry in your account, and activates it. Once you're registered a private extension, it will appear in the CloudFormation registry for that AWS account and Region, and you can use it in your stack templates.
**Topics**
+ [IAM permissions for registering a third-party private extension](#registry-register-permissions)
+ [Commonly used AWS CLI commands for working with private extensions](#registry-commonly-used-commands-private-extensions)
+ [Register a third-party private extension in your account](registry-register-private-extension.md)
+ [Remove third-party private extensions from your account](registry-private-deregister-extension.md)
## IAM permissions for registering a third-party private extension
As part of registering a private extension, you might specify an Amazon S3 bucket that contains the extension project package. This package contains any source files necessary for the extension you want to register. The user registering the extension must be able to access the project package in that Amazon S3 bucket. To do so, the user must have [https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) permissions for the extension package.
This is true whether you're either using the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html) command of the AWS CLI, or the [https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-submit.html](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-submit.html) command of the CloudFormation CLI.
For more information, see [Actions, Resources, and Condition Keys for Amazon S3](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazons3.html) in the *Service Authorization Reference*.
## Commonly used AWS CLI commands for working with private extensions
The commonly used commands for working with private extensions include:
+ [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html) to register a private extension in your account.
+ [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type-registration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type-registration.html) to return the current status of a registration request.
+ [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html) to list the extensions in your account.
+ [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type.html) to return detailed information about a specific extension or specific extension version, including current configuration data.
+ [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html) to specify the configuration data for an extension in your account and to disable and enable Hooks.
+ [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-default-version.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-default-version.html) to specify which version of an extension is the default version.
+ [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html) to remove a private extension or extension version from your account.
# Register a third-party private extension in your account
This topic covers the steps to register a third-party private extension that's shared with you so it's available for use in your account.
**Note**
Before you continue, confirm that you have the required [IAM permissions](registry-private.md#registry-register-permissions) to register a private extension.
**To register a private extension that's shared with you (AWS CLI)**
1. Locate the Amazon S3 bucket that contains the project package for the private extension you want to register in your account.
1. Use the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html) command to register the private extension in your account.
For example, the following command registers the `My::Resource::Example` resource type in the specified AWS account.
```
aws cloudformation register-type --type RESOURCE \
--type-name My::Resource::Example \
--schema-handler-package [s3 object path] --region us-west-2
```
`RegisterType` is an asynchronous operation, and returns a registration token you can use to track the progress of your registration request.
```
{
"RegistrationToken": "f5525280-104e-4d35-bef5-8f1fexample"
}
```
If your extension calls AWS APIs as part of its functionality, you must create an IAM execution role that includes the necessary permissions to call those AWS APIs, and provision that execution role in your account. You can then specify this execution role using the `--execution-role-arn` option. CloudFormation then assumes that execution role to provide your resource type with the appropriate credentials.
```
--execution-role-arn arn:aws:iam::123456789012:role/MyIAMRole
```
1. (Optional) Use the registration token with the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type-registration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type-registration.html) command to track the progress of your registration request.
When CloudFormation completes the registration request, it sets the progress status of the request to `COMPLETE`.
The following example uses the registration token returned by the `describe-type-registration` command above to return registration status information.
```
aws cloudformation describe-type-registration \
--registration-token f5525280-104e-4d35-bef5-8f1fexample \
--region us-west-2
```
The command returns the following output.
```
{
"ProgressStatus": "COMPLETE",
"TypeArn": "arn:aws:cloudformation:us-west-2:123456789012:type/resource/My-Resource-Example",
"Description": "Deployment is currently in DEPLOY_STAGE of status COMPLETED; ",
"TypeVersionArn": "arn:aws:cloudformation:us-west-2:123456789012:type/resource/My-Resource-Example/00000001"
}
```
**Important**
If the extension you are registering is a Hook, this next step is required. You must specify `ENABLED` for the `HookInvocationStatus` property. This operation enables the Hook’s properties that are defined in the Hook’s schema `properties` section. For more information, see [Hook configuration schema syntax reference](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hook-configuration-schema.html) in the *CloudFormation Hooks User Guide*.
**To specify the configuration data for a Hook (AWS CLI)**
1. Get the ARN for your Hook and save it. You can get the ARN of a Hook using the AWS Management Console or AWS CLI. For more information see [View the available and activated extensions in the CloudFormation registry](registry-view.md).
```
export HOOK_TYPE_ARN="arn:aws:cloudformation:us-west-2:123456789012:type/hook/Organization-Service-Hook/"
```
1. Use the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html) command to specify the configuration data. The JSON you pass for `--configuration` must validate against the Hook's configuration schema. To activate the Hook, you must set the `HookInvocationStatus` property to `ENABLED` in the `HookConfiguration` section.
```
aws cloudformation set-type-configuration \
--configuration "{"CloudFormationConfiguration":{"HookConfiguration":{"HookInvocationStatus": "ENABLED", "FailureMode": "FAIL", "Properties":{}}}}" \
--type-arn $HOOK_TYPE_ARN --region us-west-2
```
For more information, see [Hook configuration schema syntax reference](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hook-configuration-schema.html) in the *CloudFormation Hooks User Guide*.
# Remove third-party private extensions from your account
To remove a third-party private extension or extension version, use the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html) command.
You can deregister a specific extension version, or the extension as a whole. To deregister an extension, you must individually deregister all registered versions of that extension. If an extension has only a single registered version, deregistering that version results in the extension itself being deregistered. You can't deregister the default version of an extension, unless it's the only registered version of that extension, in which case the extension itself is deregistered as well.
**Warning**
Deregistering a private extension can't be undone. This action will:
Make the extension unusable in all CloudFormation operations.
Cause failures in future stack updates that use this extension (for modules and resource types). Although you can reregister the extension privately later, this could cause failures if CloudFormation relies on an earlier version.
Before proceeding, use the [list-stacks](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-stacks.html) and [get-template](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/get-template.html) commands to verify that no active stacks are using this extension.
## Example deregister extension commands
This section provides examples that show the different ways to deregister private extensions.
**Deregister by type name**
Use the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html) command with `--type` and `--type-name` options to deregister your extension.
```
aws cloudformation deregister-type \
--type MODULE \
--type-name My::S3::SampleBucket::MODULE
```
**Deregister by type name and version**
To deregister a specific version of your extension, specify the `--version-id` option in the command.
```
aws cloudformation deregister-type \
--type MODULE \
--type-name My::S3::SampleBucket::MODULE \
--version-id 00000001
```
**Tip**
To set a different version of the extension as default first, use the [set-type-default-version](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-default-version.html) command.
**Deregister by ARN**
Use the `--arn` option and specify your extension's ARN to deregister it.
```
aws cloudformation deregister-type \
--arn arn:aws:cloudformation:us-west-2:123456789012:type/resource/Organization-Service-Resource
```