<h3 id="table-of-contents">Table of Contents</h3>
<ul>
<li><a href="#build-an-api-gateway-resource">Build an API Gateway resource</a>
<ul>
<li><a href="#build-a-lambda-function-for-it-to-run">Build a Lambda function for it to run</a></li>
<li><a href="#define-the-api">Define the API</a></li>
</ul>
</li>
<li><a href="#iam-setup">IAM Setup</a>
<ul>
<li><a href="#create-policy">Create Policy</a></li>
<li><a href="#bind-policy-to-a-user">Bind policy to a user</a></li>
</ul>
</li>
<li><a href="#test-the-api-in-postman">Test the API in Postman</a></li>
<li><a href="#execute-the-api-from-python">Execute the API from Python</a></li>
</ul>
<h1 id="build-an-api-gateway-resource">Build an API Gateway resource</h1>
<h2 id="build-a-lambda-function-for-it-to-run">Build a Lambda function for it to run</h2>
<p>Open the lambda console and create a function. Here's an example python
function that says hello to whoever sent the authenticated request.</p>
<pre><code class="language-python">def lambda_handler(event, context):
    """ run a hello function """
    body = 'NO HTTP METHOD'
    if 'httpMethod' in event and event['httpMethod'] == 'POST':
        request_body = event['body']
        request_user = event['requestContext']['identity']['userArn']
        body = f'{request_user} sent a POST with body: {request_body}'
    elif 'httpMethod' in event and event['httpMethod'] == 'GET':
        request_user = event['requestContext']['identity']['userArn']
        body = f'{request_user} sent a GET'
    return {
        'statusCode': 200,
        'body': json.dumps(body)
    }
</code></pre>
<h2 id="define-the-api">Define the API</h2>
<ol>
<li>Go to the <a href="https://ca-central-1.console.aws.amazon.com/apigateway/">API Gateway Console</a></li>
<li>Create</li>
<li>Protocol: REST</li>
<li>New API</li>
<li>API Name: <code>&#x3C;name></code></li>
<li>Endpoint type: Regional</li>
<li>Create API</li>
</ol>
<p>Create a method:</p>
<ol>
<li>Actions</li>
<li>Create Method</li>
<li>POST</li>
<li>Check mark</li>
<li>Integration Type: Lambda Function</li>
<li>Use Lambda Proxy Integration: Checked</li>
<li>Lambda Region: ca-central-1</li>
<li>Lambda Function: HelloWorld</li>
</ol>
<p>Enable IAM Authorization</p>
<ol>
<li>Click Method Request</li>
<li>Set authorization to <code>AWS_IAM</code></li>
</ol>
<h1 id="iam-setup">IAM Setup</h1>
<h2 id="create-policy">Create Policy</h2>
<p>Collect the ARN of the API Gateway. Click your endpoint, then the method.
The ARN will display under Method Request in the Method Execution diagram.</p>
<p>Navigate to the IAM console and create a new policy.</p>
<pre><code class="language-json">{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": [
								"arn:aws:execute-api:ca-central-1:850047500507:42mydti3lg/*/POST/*"
            ]
        }
    ]
}
</code></pre>
<h2 id="bind-policy-to-a-user">Bind policy to a user</h2>
<p>Here's how I do it:</p>
<ol>
<li>Open the IAM console</li>
<li>If you don't have a group yet, make one</li>
<li>Attach the policy to the group</li>
<li>Attach the group to a user</li>
</ol>
<p>Collect the key and key ID of that user.</p>
<h1 id="test-the-api-in-postman">Test the API in Postman</h1>
<p>Postman is nice since you know it works, and it natively handles building the
AWS request headers. It's the easiest way I know to run a one-off test of your
API.</p>
<p>Install <a href="https://www.getpostman.com/">Postman</a>.</p>
<ol>
<li>New > Request - fill in some names.</li>
<li>Set the request type to POST</li>
<li>Enter the URL</li>
<li>Enter any request data</li>
<li>Go to the Authorization tab and choose AWS signature</li>
<li>Enter the key and key ID from your IAM user</li>
<li>Set the region, in my case ca-central-1</li>
<li>Send</li>
</ol>
<p>You should get a valid response from your API. If you skip any of the
authorization steps you'll get an error instead.</p>
<h1 id="execute-the-api-from-python">Execute the API from Python</h1>
<p>End users don't use postman. Usually they'd be using JavaScript, and in my case
they use Python to access my API. This was <strong>really complicated</strong>.</p>
<p><a href="https://github.com/DavidMuller/aws-requests-auth">Here's an open source library that can do it</a>.</p>
<p>I've written my own version of this for the Breqwatr deployment tool. I didn't
want to depend on the above link. Also I tried to rewrite the client as
functions with the hope of making it easier to read.</p>
<p>You can find it in <a href="https://github.com/breqwatr/breqwatr-deployment-tool">Breqwatr's GitHub</a>
under <code>lib/aws</code>.</p>
<p>Here's the high level flow of how it gets the auth header:</p>
<pre><code class="language-python">def get_authorization_header(time, key_id, secret_key, region, method, host,
                             body, uri, query):
    """ Return an aws authorization header """
    # canonical request is a multi-line string with a particular format
    canonical_headers = get_canonical_headers(host, time)
    payload_hash = get_payload_hash(body)
    canonical_request = get_canonical_request(
         method=method,
         uri=uri,
         query=query,
         canonical_headers=canonical_headers,
         payload_hash=payload_hash)
    # create a string-to-sign from the canonical requests' digest
    cr_digest = hashlib.sha256(canonical_request.encode('utf-8')).hexdigest()
    credential_scope = get_credential_scope(time, region)
    string_to_sign = get_string_to_sign(time, credential_scope, cr_digest)
    # sign the String-To-Sign with a signing key derived from secret iam key
    signing_key = get_signing_key(secret_key, time, region)
    signature = get_signature(signing_key, string_to_sign)
    # return the headers all in one string
    return (
        f'AWS4-HMAC-SHA256 Credential={key_id}/{credential_scope}, '
        f'SignedHeaders=host;x-amz-date, '
        f'Signature={signature}')
</code></pre>


Kyle Pericak

Authenticating with AWS IAM in AWS API Gateway