StreamsPlaybackEncodingBitmovin Dashboard

S3 role-based Outputs are an secure way for our service to access your AWS (Amazon Web Services) S3 bucket to be used as an Output for Analytics Exports.

Instead of you providing your AWS Access/Secret key pair to our Analytics service, we provide you with an AWS IAM (Identity and Access Management) user name, which you can grant specific access rights in your account so it can access your desired S3 bucket.

In this tutorial, we will

  1. create an **S3 bucket in your AWS account** which will serve as the input or output storage for your data.

  2. create an **S3 role based input or output in your Bitmovin account** using the Bitmovin API. This step will give you the `externalId` which is used to communicate safely with your IAM role which you create in step 3

  3. create an **IAM role in your AWS account**, and attach an IAM policy to it. This policy states which of your buckets can be accessed by our user, and which permissions are granted to it.

**NOTE**: This tutorial needs to be repeated for EACH account/sub-organization you want a S3-Role-Based access for.

## Create an AWS S3 Bucket

In the AWS Management Console, open the [S3 section](🔗).

  1. Click on the **Create Bucket** button which starts the bucket creation wizard

  2. In the "Name and Region" panel, choose a bucket name (for example _my-bitmovin-bucket_) and a Region (for example _(EU) Ireland)_)

  3. Configure **Block Public Access settings for this bucket** a. The default settings will **Block** _**all**_ **public access** b. To **enable playback** for manifests and files from the bucket, **uncheck** 🔳 **Block** _**all**_ **public access.**

  4. Leave other sections and configurations unchanged

  5. Finish going through the wizard and click **Create Bucket**

Your bucket is now ready to be used.

## Create an S3 role-based Analytics Output

[Role based S3 Analytics Output Resources](🔗) can be created via the [Bitmovin Analytics API](🔗). The minimal required information to create a Role based S3 Analytics Output are the following :

  • `bucketName`: the name of your target S3 bucket

  • `roleArn`: Amazon Resource Name of the Role you created

For more control over who can assume your IAM role, an externalID needs to be used. It is returned by the Bitmovin API after creating an S3-role-based Output. Enable it by selecting one of the following `externalIdMode`:

  • `externalIdMode`:

    • `GLOBAL` - A consistent and unique ID is used, which is used for every S3 role-based output that you create.

    • `GENERATED` - A unique but random UUID is returned

Warning - common pitfall

Be sure to create a **analytics** output (under `/v1/analytics/outputs`) and not an encoding output (`v1/encoding/outputs`). Analytics does not share the same output resources as encoding.

## Create an AWS IAM Role

In order to continue, you will have to create a `Role` in your AWS account.

  1. Login to your AWS account.

  2. Click on "Services" near the top left.

  3. Look for "Security, Identity & Compliance" and click on "IAM". You are now in the _Identity and Access Management (IAM)_ page of your account.

  4. On the left pane, click on "Access Management" -> "Roles".

  5. Click on "Create Role". The _Create Role_ page appears.

  6. The page shows you four boxes of which you can select one for a type of trusted entity. Click on the "Another AWS account" box.

  7. In the field "Account ID", enter `630681592166`.

  8. Next to "Option", check the "Require external ID" checkbox. A box opens asking you to enter an external ID.

  9. Enter the `externalId` that you got in the previous section.

  10. Click on "Next: Permissions"

  11. Assign a policy to the role by selecting it in the policy list.

    _(Note: The pre-defined `AmazonS3FullAccess` policy is known to be suitable but since it provides unrestricted access to your bucket, you might need to create a custom policy with fine-tuned access rights. Please review details of the permissions required for [buckets for Encoding Input and Output](🔗) or [buckets for Analytics Exports](🔗) buckets_)

  12. Click on "Next: Tags". The _Add Tags_ page appears, on which you optionally can assign tags to the role.

  13. Click "Next: Review". The _Review_ page appears. Give the new role a name. **Role name MUST match the YOUR-INTENDED-ROLE-NAME specified in Create an S3 role-based Input/Output > in `roleArn`**

  14. Click "Create Role". You are now back in the _Identity and Access Management(IAM)-Roles_ page, and the system tells you "The role Bitmovin has been created". You also see the new role in the list of roles in your account.

If you want to learn more about Roles in AWS, please see their [documentation][1].

### JSON Payload

If you prefer using the AWS CLI tools, you can create this role with the following JSON payload.


[1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html
## Examples
This example uses our latest [Open API client for Java](🔗), which is available on Github. The example shows how to create an Output. 
### Create a new S3 role-based Output

API reference: [create a role-based S3 Output](🔗):
### Use an existing S3 role-based Output

API reference: [get a S3 role-based Output](🔗)
_Beware that there is a very similar endpoint used for S3 Role-Based Outputs used for encoding: bitmovinApi.encoding.outputs.s3RoleBased. You cannot use those for your Analytics exports and vice-versa, so make sure you set the right one up_
**Important**: Make sure you are creating this resource in the appropriate Organization if you have been invited into a Multi-Tenant Organization. Your personal API Key will by default create all resources in your user's organization and not in the organization you have been invited to. You can pass the `X-Tenant-Org-Id` HTTP Header or use the `withTenantOrgId()` API to indicate which Organization your API call is targetting (see [Using an API SDK with different Organisations](🔗)).
Now that you have an S3 role-based Output for Bitmovin Analytics available, you can [start exporting data](🔗) to it.