[object Object] Icon

Encoding
Learn how to create, start, manage and modify Encodings

[object Object] Icon

Player
Learn how to create, start, manage and modify Players

[object Object] Icon

Analytics
Learn how to create, start, manage and modify Analyticss

Docs Home
User shortcuts for search
Focus by pressing f
Hide results by pressing Esc
Navigate via   keys

Wed Sep 16 2020

How to create an S3 Role-Based Encoding Input or Output with the Bitmovin API

OverviewLink Icon

S3 role-based Inputs resp. S3 role-based Outputs are an alternative way for our services to access your AWS (Amazon Web Services) S3 bucket to be used as an Encoding Input and/or Output, or an Output for Analytics Exports.

Instead of you providing your AWS Access/Secret key pair to our Encoding or 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.

To do that, you are asked to 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.

RequirementsLink Icon

  • S3 role-based buckets can be used for segmented outputs with encoder version 2.29.0 or higher.

Create an AWS S3 BucketLink Icon

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)), then press Next
  3. The options in the "Configure options" view are all optional and do not affect how Bitmovin uses your bucket. Press Next
  4. The way you configure options under "Set permissions" depends on how you want to use the bucket. The default settings will block public access which is generally recommended, unless you want to test playback or easily provide access to files in your bucket directly. We provide an FAQ for details on how to configure it for public access.
  5. Finish going through the wizard and click Create Bucket

Your bucket is now ready to be used.

Create an AWS IAM RoleLink Icon

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. Freely choose an external ID and write it down for later use. In this example, we will use myextid123 as the external ID. (Note: The external ID can be anything, but setting it to a a randomly generated UUID for better security and uniqueness is a good way to go).
  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, e.g. "Bitmovin".
  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.

JSON Payload

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

1{
2 "Version": "2012-10-17",
3 "Statement": [
4 {
5 "Effect": "Allow",
6 "Principal": {
7 "AWS": "arn:aws:iam::630681592166:user/bitmovinCustomerS3Access"
8 },
9 "Action": "sts:AssumeRole",
10 "Condition": {
11 "StringEquals": {
12 "sts:ExternalId": "<EXTERNAL_ID>"
13 }
14 }
15 }
16 ]
17}

Create an S3 role-based Input/OutputLink Icon

Role based S3 input and output resources can be created via the Bitmovin API. The minimal required information to create a Role based S3 input or output are the following :

  • bucketName: the name of your target S3 bucket
  • roleArn: Amazon Resource Name of the Role you created
  • externalId: Amazon External ID to ensure an additional level of authentification

(Java) S3 Role-Based Output ExampleLink Icon

This example uses our latest Open API client for Java, which is available on Github. This example shows how to create an Output.

Create a new S3 Role-Based Output

1bitmovinApi = BitmovinApi.builder().withApiKey("YOUR_BITMOVIN_API_KEY").build();
2
3AclEntry aclEntry = new AclEntry();
4aclEntry.setPermission(AclPermission.PRIVATE);
5
6List<AclEntry> acl = new ArrayList<>();
7acl.add(aclEntry);
8
9S3RoleBasedOutput s3RoleBasedOutput = new S3RoleBasedOutput();
10s3RoleBasedOutput.setBucketName("<BUCKET_NAME>");
11s3RoleBasedOutput.setRoleArn("<AWS_ARN_ROLE>");
12s3RoleBasedOutput.setExternalId("<AWS_ROLE_EXT_ID>");
13s3RoleBasedOutput.setAcl(acl);
14
15s3RoleBasedOutput = bitmovinApi.encoding.outputs.s3RoleBased.create(s3RoleBasedOutput);

Hint: In case you chose to enable Block public access on your S3 bucket (recommended), you would have to make sure that the ACL is set to PRIVATE on the output (as shown above) as well as on your Muxing configurations.

To create an Input is fairly similar, but you just use the S3RoleBasedInput resource and the bitmovinApi.encoding.inputs.s3RoleBased endpoint

Use an existing S3 Role-Based Output

1bitmovinApi = BitmovinApi.builder().withApiKey("YOUR_BITMOVIN_API_KEY").build();
2
3S3RoleBasedOutput s3RoleBasedOutput = bitmovinApi.encoding.outputs.s3RoleBased.get("YOUR_S3_ROLE_BASED_OUTPUT_ID");

(CURL) S3 Role-Based Output ExampleLink Icon

Create a new S3 Role-Based Output

API reference: create a Role-Based S3 Output:

1curl -X POST \
2 https://api.bitmovin.com/v1/encoding/outputs/s3-role-based \
3 -H 'Content-Type: application/json' \
4 -H 'x-api-key: YOUR_BITMOVIN_API_KEY' \
5 -d '{
6 "bucketName": "<BUCKET_NAME>",
7 "roleArn": "<AWS_ARN_ROLE>",
8 "externalId": "<AWS_ROLE_EXT_ID>",
9 "acl": [
10 {
11 "permission": "PRIVATE"
12 }
13 ]
14}'

Get an existing S3 Role-Based Output

API reference: get an S3 Role-Based Output

1curl https://api.bitmovin.com/v1/encoding/outputs/s3-role-based/YOUR_S3_ROLE_BASED_OUTPUT_ID \
2 -H 'Content-Type: application/json' \
3 -H 'x-api-key: YOUR_BITMOVIN_API_KEY'

What's Next?Link Icon

Now that you have created S3 Role-Based Inputs and/or Outputs, you can use them in your encoding in much the same way as you would any other Input or Output.

Give us feedback