[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

Mon Sep 02 2019

How to create an S3 role-based encoding output with the Bitmovin API

OverviewLink Icon

S3 role-based Outputs are an alternative way of service to access your AWS S3 bucket to be used as an Input (Encoding) and/or Output (Encoding/Analytics). Instead of providing an Access/Secret key pair, we provide you with an AWS IAM user name, which you can grant specific access rights in your account so it can access your desired S3 bucket.

NOTE: At this time, S3 role-based buckets support progressive output files (MP4 / MOV / TS muxings) only. We are working on adding support for segmented output types in the future.

To do that, you create an IAM role in your AWS account, and attach an IAM policy to it. This policy states which bucket can be accessed by our user, and which permissions are granted to it.

Create an IAM Role in your AWS accountLink Icon

In order to continue, you will have to create a Role in your AWS account. Please see our tutorial to learn how to create a AWS IAM Role. If you want to learn more about Roles in AWS, please see their documentation.

Attach an IAM Policy to your IAM RoleLink Icon

IAM Policies can be applied to IAM Users or IAM Groups, and enable to manage their access rights accordingly. In order to use your S3 bucket we require a minimum set of rights that are necessary in order to use S3 role-based authentication. Therefore please see the following IAM Policy example:

1{
2 "Version": "2012-10-17",
3 "Statement": [
4 {
5 "Sid": "S3RoleBasedAccessRights",
6 "Effect": "Allow",
7 "Action": "sts:AssumeRole",
8 "Resource": "arn:aws:iam::630681592166:role/user/bitmovinCustomerS3Access",
9 "Condition": {
10 "StringEquals": {
11 "sts:ExternalId": "<AWS_ROLE_EXT_ID>"
12 }
13 }
14 },
15 {
16 "Sid": "S3ObjectLevelRights",
17 "Effect": "Allow",
18 "Action": [
19 "s3:GetObject",
20 "s3:PutObject",
21 "s3:PutObjectAcl"
22 ],
23 "Resource": "arn:aws:s3:::<BUCKET_NAME>/*"
24 },
25 {
26 "Sid": "S3BucketLevelRights",
27 "Effect": "Allow",
28 "Action": [
29 "s3:ListBucket",
30 "s3:GetBucketLocation"
31 ],
32 "Resource": "arn:aws:s3:::<BUCKET_NAME>"
33 }
34 ]
35}

Create an S3 role-based 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

Hint: In case you choose 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 and Muxing configuration, as shown below.


(Java) S3 role-based Output ExampleLink Icon

This example uses our latest Open API client for Java, which is available on Github.

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);

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 a existing S3 role-based Output

API reference: get a 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'

Give us feedback