Authentication

All interactions between your connector service and the Amazon Yojaka product are via RESTful API calls. This page documents how you can secure these API calls and authenticate your connector service with the Amazon Yojaka product.

AWS Signature Version 4

AWS Signature Version 4 (shortened to AWS SigV4) is a standard mechanism used to add authentication information to AWS requests sent over HTTP. A detailed description of this authentication mechanism can be found here.

Amazon Yojaka leverages the same authentication mechanism for adding authentication information to RESTful API calls made by connectors to Amazon Yojaka.

Note

To authenticate requests to the Amazon Yojaka APIs using the AWS SigV4 mechanism, you will need the access keys of the AWS IAM user that you created during the Amazon Web Services Setup step and the ARN of the AWS IAM role provided during the Post On-boarding Steps step.

How to sign requests

The exact process for signing your Amazon Yojaka API call are documented here. You will need the following information while signing the canonical request to the API:

Region

The region you will need to specify while signing the request will vary based on the country/area in which you are invoking Amazon Yojaka APIs. Refer to the table below to find the region to use.

Country / Area

Region

IN

eu-west-1

NA

us-east-1

Service

To invoke the Amazon Yojaka APIs, the service to use while signing the request is always execute-api.

Tip

AWS SigV4 signing of your requests to the Amazon Yojaka APIs are automatically handled for you if you use the Amazon Yojaka SDK that is available or most common programming languages. Refer to the SDKs documentation for more details.

Sample Code

Below is some sample code for authenticating a request to the Amazon Yojaka APIs in multiple programming languages.

Java

The code below uses the standard Apache HttpComponents library and an additional library available here.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
import com.amazonaws.auth.AWS4Signer;
import com.amazonaws.auth.AWSStaticCredentialsProvider;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.auth.STSAssumeRoleSessionCredentialsProvider;
import com.amazonaws.http.AWSRequestSigningApacheInterceptor;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.securitytoken.AWSSecurityTokenService;
import com.amazonaws.services.securitytoken.AWSSecurityTokenServiceClientBuilder;
import org.apache.http.client.HttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.client.methods.HttpPut;
import org.apache.http.client.utils.URIBuilder;


    public static void invokeAmazonYojaka() {
        // Create the AWS SigV4 signer
        AWS4Signer aws4Signer = new AWS4Signer();

        // Set the service name and region
        aws4Signer.setServiceName("execute-api");
        aws4Signer.setRegionName("eu-west-1");

        // Create an AWS STS client using the AWS IAM user credentials
        AWSSecurityTokenService awsSecurityTokenService = AWSSecurityTokenServiceClientBuilder.standard()
            .withRegion(Regions.EU_WEST_1)
            // Use the access key and secret access key of the AWS IAM user that you have on-boarded with
            // Amazon Yojaka
            .withCredentials(new AWSStaticCredentialsProvider(
                    new BasicAWSCredentials("AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY")))
            .build();

        // Create an AWS STS assume role credentials provider that will assume the role assigned to your
        // connector
        STSAssumeRoleSessionCredentialsProvider stsAssumeRoleSessionCredentialsProvider =
            // Use the ARN of the AWS IAM role created by the Amazon Yojaka team as part of on-boarding
            new STSAssumeRoleSessionCredentialsProvider.Builder("AWS_IAM_ROLE_ARN", "MyConnector")
                    // Use the AWS STS client created above
                    .withStsClient(awsSecurityTokenService)
                    // The maximum duration of the assume role credentials is 4 hours
                    // This credentials provider class will automatically refresh the session credentials
                    // upon expiry
                    .withRoleSessionDurationSeconds(4 * 60 * 60)
                    .build();

        // Create the AWS SigV4 signing interceptor
        AWSRequestSigningApacheInterceptor awsRequestSigningApacheInterceptor =
            new AWSRequestSigningApacheInterceptor("execute-api", aws4Signer,
                stsAssumeRoleSessionCredentialsProvider);

        // Create the HTTP client
        HttpClient httpClient = HttpClients.custom()
            .addInterceptorLast(awsRequestSigningApacheInterceptor)
            .build();

        // Use the HTTP client to invoke Amazon Yojaka APIs using the HTTP client object
        // Build a request to invoke the UpdateInventory API of the Amazon Yojaka Sandbox
        URIBuilder uriBuilder = new URIBuilder();
        uriBuilder.setScheme("https");
        uriBuilder.setHost("api.sandbox.dub.yojaka.xp.sellers.a2z.com");
        uriBuilder.setPort(443);
        uriBuilder.setPath("v1/inventories");
        // Replace with the appropriate values for locationId, skuId, quantity and inventoryUpdateSequence
        uriBuilder.setCustomQuery("locationId=896e68a8-990f-4f5a-99a2-f9877a7ef36d&skuId=TestSku1"
            + "&quantity=19976&inventoryUpdateSequence=2");

        HttpPut httpPut = new HttpPut(uriBuilder.build());
        httpPut.addHeader("Accept", "application/json");
        // Replace with an appropriate LWA access token
        httpPut.addHeader("X-Amz-Access-Token", "Atza|IwE...");

        // Invoke the method
        HttpResponse httpResponse = httpClient.execute(httpPut);

        // Use the response as appropriate for your application
    }

Note

Use the credentials of the AWS IAM user you created during the Amazon Web Services Setup step to sign your HTTP request in the code above.

C#

The code below uses standard C# programming language constructs and uses an additional library available here.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.SecurityToken;
using Amazon.SecurityToken.Model;
using Amazon;

using Aws4RequestSigner;

    private static async Task<Dictionary<string, object>> InvokeAmazonYojaka()
    {

        // Create an AWS Credentials object, using the access key and secret access key of the AWS IAM user
        // that you have on-boarded with Yojaka
        AWSCredentials credentials = new Credentials
        {
            AccessKeyId = "AWS_ACCESS_KEY_ID",
            SecretAccessKey = "AWS_SECRET_ACCESS_KEY"
        };

        // Create an AWS STS client using these credentials
        AmazonSecurityTokenServiceClient stsClient =
                new AmazonSecurityTokenServiceClient(credentials, RegionEndpoint.EUWest1);

        // Invoke the AssumeRole operation on this STS Client that will assume the role assigned to your connector
        var apiCallerAssumedRoleResult = stsClient.AssumeRoleAsync(new AssumeRoleRequest
        {
            // Use the ARN of the AWS IAM role created by the Amazon Yojaka team as part of on-boarding
            RoleArn = "AWS_IAM_ROLE_ARN",
            RoleSessionName = "MyConnector",
            // The maximum duration of the temporary security credentials is 4 hours
            DurationSeconds = 3600
        }).Result;

        string AWS_ACCESS_KEY_ID = apiCallerAssumedRoleResult.Credentials.AccessKeyId;
        string AWS_SECRET_ACCESS_KEY = apiCallerAssumedRoleResult.Credentials.SecretAccessKey;
        string AWS_SECURITY_TOKEN = apiCallerAssumedRoleResult.Credentials.SessionToken;

        // Create the AWS SigV4 signer with the AccessKeyId and SecretAccessKey obtained above
        var signer = new AWS4RequestSigner(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY);

        // Build a request to invoke the UpdateInventory API of the Amazon Yojaka Sandbox
        UriBuilder uriBuilder = new UriBuilder
        {
            Scheme = "https",
            Host = "api.sandbox.dub.yojaka.xp.sellers.a2z.com",
            Port = 443,
            Path = "v1/inventories",
            // Replace with the appropriate values for locationId, skuId, quantity and inventoryUpdateSequence
            Query = "locationId=896e68a8-990f-4d5a-9944-f9877a7ef36d&skuId=Sku1&quantity=5&inventoryUpdateSequence=2"
        };

        var request = new HttpRequestMessage
        {
            Method = HttpMethod.Put,
            RequestUri = uriBuilder.Uri,
            Headers = {
                { "Accept", "application/json" },
                // Replace with an appropriate LWA access token
                { "X-Amz-Access-Token", "Atza|IwE..." },
                { "X-Amz-Security-Token", AWS_SECURITY_TOKEN }
            }
        };

        // Sign the request for the eu-west-1 region
        request = await signer.Sign(request, "execute-api", "eu-west-1");

        // Invoke the method
        var client = new HttpClient();
        var response = await client.SendAsync(request);
        response.EnsureSuccessStatusCode();

        // Use the response as appropriate for your application
        return JsonSerializer.Deserialize<Dictionary<string, object>>(await response.Content.ReadAsStringAsync());
    }

Note

Use the credentials of the AWS IAM user you created during the Amazon Web Services Setup step to sign your HTTP request in the code above.