# Request Authentication **Topics** + [What Is Authentication?](WhatIsAuthentication.md) + [Creating an AWS Account](AboutAWSAccounts.md) + [Managing Users of Amazon SimpleDB](UsingIAMWithSDB.md) + [Using Temporary Security Credentials](UsingTemporarySecurityCredentials_SDB.md) + [HMAC-SHA Signature](HMACAuth.md) This section explains how Amazon SimpleDB authenticates your requests. # What Is Authentication? Authentication is a process for identifying and verifying who is sending a request. The following diagram shows a simplified version of an authentication process. ![\[General Process of Authentication\]](http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/images/GenericAuthProcess.png) **General Process of Authentication** | | | | --- |--- | | ![\[Red circle with number 1 inside, indicating a numerical step or priority.\]](http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/images/callouts/1.png) | The sender obtains the necessary credential. | | ![\[Red circle with number 2 inside, likely representing a step or item in a sequence.\]](http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/images/callouts/2.png) | The sender sends a request with the credential to the recipient. | | ![\[Red circle with number 3 inside, indicating a step or sequence number.\]](http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/images/callouts/3.png) | The recipient uses the credential to verify the sender truly sent the request. | | ![\[Red circle with number 4 inside, likely representing a notification or count indicator.\]](http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/images/callouts/4.png) | If yes, the recipient processes the request. If no, the recipient rejects the request and responds accordingly. | During authentication, AWS verifies both the identity of the sender and whether the sender is registered to use services offered by AWS. If either test fails, the request is not processed further. The subsequent sections describe how Amazon SimpleDB implements authentication to protect you and your customers' data. # Creating an AWS Account To access any web service AWS offers, you must first create an AWS account at [http://aws.amazon.com](http://aws.amazon.com). You can use an existing Amazon.com account login and password when creating the AWS account. From your AWS account you can view your AWS account activity, view usage reports, and manage your AWS Security Credentials. See the steps outlined below to setup a new AWS account. ## Sign up for an AWS account If you do not have an AWS account, complete the following steps to create one. **To sign up for an AWS account** 1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup). 1. Follow the online instructions. Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad. When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks). AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [https://aws.amazon.com/](https://aws.amazon.com/) and choosing **My Account**. ## Create a user with administrative access After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks. **Secure your AWS account root user** 1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password. For help signing in by using root user, see [Signing in as the root user](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial) in the *AWS Sign-In User Guide*. 1. Turn on multi-factor authentication (MFA) for your root user. For instructions, see [Enable a virtual MFA device for your AWS account root user (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html) in the *IAM User Guide*. **Create a user with administrative access** 1. Enable IAM Identity Center. For instructions, see [Enabling AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html) in the *AWS IAM Identity Center User Guide*. 1. In IAM Identity Center, grant administrative access to a user. For a tutorial about using the IAM Identity Center directory as your identity source, see [ Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html) in the *AWS IAM Identity Center User Guide*. **Sign in as the user with administrative access** + To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user. For help signing in using an IAM Identity Center user, see [Signing in to the AWS access portal](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html) in the *AWS Sign-In User Guide*. **Assign access to additional users** 1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions. For instructions, see [ Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html) in the *AWS IAM Identity Center User Guide*. 1. Assign users to a group, and then assign single sign-on access to the group. For instructions, see [ Add groups](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html) in the *AWS IAM Identity Center User Guide*. # Managing Users of Amazon SimpleDB **Topics** + [Amazon Resource Names (ARNs) for Amazon SimpleDB](#SDB_ARN_Format) + [Amazon SimpleDB Actions](#UsingWithSDB_Actions) + [Amazon SimpleDB Keys](#UsingWithSDB_Keys) + [Example Policies for Amazon SimpleDB](#ExamplePolicies_SDB) Amazon SimpleDB does not offer its own resource-based permissions system. However, the service now integrates with IAM (AWS Identity and Access Management) so that you can give other Users in your AWS Account access to Amazon SimpleDB domains within the AWS Account. For example, Joe can create an Amazon SimpleDB domain, and then write an IAM policy specifying which Users in his AWS Account can access that domain. Joe can't give another AWS Account (or Users in another AWS Account) access to his AWS Account's SimpleDB domains. **Important** Aside from the integration with IAM, Amazon SimpleDB hasn't changed. Its API is not affected by the introduction of IAM, and includes no new actions related to Users and access control. For examples of policies that cover Amazon SimpleDB actions and resources, see [Example Policies for Amazon SimpleDB](#ExamplePolicies_SDB). ## Amazon Resource Names (ARNs) for Amazon SimpleDB For Amazon SimpleDB, domains are the only resource type you can specify in a policy. The ARN format for domains follows this format: ``` arn:aws:sdb:::domain/ ``` The ** is required and can be any of the individual Regions Amazon SimpleDB supports (e.g., us-east-1), or \$1 to represent all Regions. The ** must not be blank. **Example** Following is an ARN for a domain named Domain1 in the us-east-1 region, belonging to AWS Account 111122223333. ``` arn:aws:sdb:us-east-1:111122223333:domain/Domain1 ``` **Example** Following is an ARN for a domain named Domain1 in all Regions that Amazon SimpleDB supports. ``` arn:aws:sdb:*:111122223333:domain/Domain1 ``` You can use \$1 and ? wildcards in the domain name. The \$1 represents zero or multiple characters, and ? represents one character. For example, the following could refer to all the domains prefixed with `don_`. ``` arn:aws:sdb:*:111122223333:domain/don_* ``` For more information about ARNs, see [ARNs](http://docs.aws.amazon.com/IAM/latest/UserGuide/Using_Identifiers.html#Identifiers_ARNs). ## Amazon SimpleDB Actions In an IAM policy, you can specify any and all actions that Amazon SimpleDB offers. You must prefix each action name with the lowercase string `sdb:`. For example: `sdb:GetAttributes`, `sdb:Select`, `sdb:*` (for all Amazon SimpleDB actions). For a list of the actions, see [Operations](SDB_API_Operations.md). ## Amazon SimpleDB Keys Amazon SimpleDB implements the following policy keys, but no product-specific ones. For more information about policy keys, see [Condition](http://docs.aws.amazon.com/IAM/latest/UserGuide/AccessPolicyLanguage_ElementDescriptions.html#Condition). For a list of condition keys supported by each AWS service, see [Actions, resources, and condition keys for AWS services](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html) in the *IAM User Guide*. For a list of condition keys that can be used in multiple AWS services, see [AWS global condition context keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) in the *IAM User Guide*. ## Example Policies for Amazon SimpleDB This section shows several simple policies for controlling User access to Amazon SimpleDB domains. **Note** In the future, Amazon SimpleDB might add new actions that should logically be included in one of the following policies, based on the policy’s stated goals. **Example 1: Allow a group to use any Amazon SimpleDB actions on specific domains** In this example, we create a policy that lets the group use any of the AWS Account's domains that start with the literal string `test`. **** ``` { "Version":"2012-10-17", "Statement":[{ "Effect":"Allow", "Action":"sdb:*", "Resource":"arn:aws:sdb:*:111122223333:domain/test*" } ] } ``` **Example 2: Allow a group to read data from the AWS Account's domains** In this example, we create a policy that lets the group use the `GetAttributes` and `Select` actions with any of the AWS Account's domains. **** ``` { "Version":"2012-10-17", "Statement":[{ "Effect":"Allow", "Action":["sdb:GetAttributes","sdb:Select"], "Resource":"*" } ] } ``` **Example 3: Allow a group to list domains and get their metadata** In this example, we create a policy that lets the group use the `ListDomains` and `DomainMetadata` actions with any of the AWS Account's domains. **Example 4: Allow a partner to only read data from a particular domain** There's no way to share a domain with a different AWS Account, so the partner must work with your domain as a User within your own AWS Account. In this example, we create a user for the partner, and create a policy for the user that gives access to the `GetAttributes` and `Select` actions only on the domain named *mySDBDomain*. (Instead of attaching the policy to the User, you could create a group for the partner, put the User in the group, and assign the policy to the group.) You might also want to prevent the partner from doing anything else with mySDBDomain, so we add a statement that denies permission to any Amazon SimpleDB actions besides `GetAttributes` and `Select`. This is only necessary if there's also a broad policy that gives the AWS Account's Users wide access to Amazon SimpleDB and all the AWS Account's domains. **** ``` { "Version":"2012-10-17", "Statement":[{ "Effect":"Allow", "Action":["sdb:GetAttributes","sdb:Select"], "Resource":"arn:aws:sdb:*:111122223333:domain/mySDBDomain" }, { "Effect":"Deny", "Action":["sdb:GetAttributes","sdb:Select"], "Resource":"*" } ] } ``` # Using Temporary Security Credentials In addition to creating users with their own security credentials, IAM also enables you to grant temporary security credentials to any user to allow the user to access your AWS services and resources. You can manage users for your system who do not have AWS accounts; these users are called federated users. Additionally, "users" can also be applications that you create to access your AWS resources. You can use these temporary security credentials to make requests to Amazon SimpleDB. Replace your usual `AWSAccessKeyId` parameter with the one provided by IAM, add the IAM `SecurityToken` as a new parameter, and sign the request with the `SecretKeyId` provided by IAM. If you send requests using expired credentials Amazon SimpleDB denies the request. For more information about IAM support for temporary security credentials, go to [Granting Temporary Access to Your AWS Resources](http://docs.aws.amazon.com/IAM/latest/UserGuide/TokenBasedAuth.html) in *Using IAM*. **Example Using Temporary Security Credentials to Authenticate an Amazon SimpleDB Request** The following example demonstrates the wire protocol for using temporary security credentials to authenticate an Amazon SimpleDB request over HTTPS. ``` https://sdb.amazonaws.com/ ?Action=GetAttributes &AWSAccessKeyId=Access Key ID provided by AWS Security Token Service &DomainName=MyDomain &ItemName=JumboFez &SignatureVersion=2 &SignatureMethod=HmacSHA256 &Timestamp=2010-01-25T15%3A03%3A07-07%3A00 &Version=2009-04-15 &Signature=Signature calculated using the SecretKeyId provided by AWS Security Token Service &SecurityToken=Security Token Value ``` **Note** AWS provides support for temporary security credentials and session tokens in the AWS SDKs so you can implement temporary security credentials or session tokens with a specific programming language. Each SDK has its own instructions for implementing this feature. For a current list of AWS SDKs that support this feature, see [Ways to Access the AWS Security Token Service](http://docs.aws.amazon.com/IAM/latest/UserGuide/AccessingSTS.html). Non-AWS products and services should have their own documentation about supporting temporary credentials and session tokens, if available. # HMAC-SHA Signature **Topics** + [Required Authentication Information](#RequiredAuthInfo) + [Authentication Process](#AuthProcess) + [Signing REST Requests](#REST_RESTAuth) + [About the Time Stamp](#AboutTimestamp) ## Required Authentication Information When accessing Amazon SimpleDB using one of the AWS SDKs, the SDK handles the authentication process for you. For a list of available AWS SDKs supporting Amazon SimpleDB, see [Available Libraries](AWSLibraries.md). However, when accessing Amazon SimpleDB using a REST request, you must provide the following items so the request can be authenticated. **Authentication** + **AWSAccessKeyId—**Your AWS account is identified by your Access Key ID, which AWS uses to look up your Secret Access Key. + **Signature—**Each request must contain a valid HMAC-SHA signature, or the request is rejected. A request signature is calculated using your Secret Access Key, which is a shared secret known only to you and AWS. You must use a HMAC-SHA256 signature. + **Date—**Each request must contain the time stamp of the request. Depending on the API you're using, you can provide an expiration date and time for the request instead of or in addition to the time stamp. For details of what is required and allowed for each API, see the authentication topic for the particular API. ## Authentication Process Following is the series of tasks required to authenticate requests to AWS using an HMAC-SHA request signature. It is assumed you have already created an AWS account and received an Access Key ID and Secret Access Key. For more information about those, see [Creating an AWS Account](AboutAWSAccounts.md). You perform the first three tasks. ![\[HMAC-SHA Authentication Process\]](http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/images/HMACAuthProcess_You.png) **Process for Authentication: Tasks You Perform** | | | | --- |--- | | ![\[Red circle with number 1 inside, indicating a numerical step or priority.\]](http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/images/callouts/1.png) | You construct a request to AWS. | | ![\[Red circle with number 2 inside, likely representing a step or item in a sequence.\]](http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/images/callouts/2.png) | You calculate a keyed-hash message authentication code (HMAC-SHA) signature using your Secret Access Key (for information about HMAC, go to [http://www.rfc-editor.org/rfc/rfc2104.txt](http://www.rfc-editor.org/rfc/rfc2104.txt)) | | ![\[Red circle with number 3 inside, indicating a step or sequence number.\]](http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/images/callouts/3.png) | You include the signature and your Access Key ID in the request, and then send the request to AWS. | AWS performs the next three tasks. ![\[HMAC-SHA Authentication Process\]](http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/images/HMACAuthProcess_AWS.png) **Process for Authentication: Tasks AWS Performs** | | | | --- |--- | | ![\[Red circle with number 4 inside, likely representing a notification or count indicator.\]](http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/images/callouts/4.png) | AWS uses the Access Key ID to look up your Secret Access Key. | | ![\[Red circle with white number 3 inside, indicating a step or sequence number.\]](http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/images/callouts/5.png) | AWS generates a signature from the request data and the Secret Access Key using the same algorithm you used to calculate the signature you sent in the request. | | ![\[Red circle with white letter B inside, representing a logo or icon.\]](http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/images/callouts/6.png) | If the signature generated by AWS matches the one you sent in the request, the request is considered authentic. If the comparison fails, the request is discarded, and AWS returns an error response. | ## Signing REST Requests You can send REST requests over either HTTP or HTTPS. Regardless of which protocol you use, you must include a signature in every REST request. This section describes how to create the signature. The method described in the following procedure is known as *signature version 2*, and uses the HMAC-SHA256 signing method. In addition to the requirements listed in [Required Authentication Information](#RequiredAuthInfo), signatures for REST requests must also include: + **SignatureVersion—**The AWS signature version, which is currently the value `2`. + **SignatureMethod—**Explicitly provide the signature method `HmacSHA256`. **Important** If you are currently using signature version 1: Version 1 is deprecated, and you should move to signature version 2 immediately. **To create the signature** 1. Create the canonicalized query string that you need later in this procedure: 1. Sort the UTF-8 query string components by parameter name with natural byte ordering. The parameters can come from the GET URI or from the POST body (when `Content-Type` is `application/x-www-form-urlencoded` ). 1. URL encode the parameter name and values according to the following rules: + Do not URL encode any of the unreserved characters that RFC 3986 defines. These unreserved characters are A-Z, a-z, 0-9, hyphen ( - ), underscore ( \$1 ), period ( . ), and tilde ( \$1 ). + Percent encode all other characters with %XY, where X and Y are hex characters 0-9 and uppercase A-F. + Percent encode extended UTF-8 characters in the form %XY%ZA.... + Percent encode the space character as %20 (and not \$1, as common encoding schemes do). **Note** Currently all AWS service parameter names use unreserved characters, so you don't need to encode them. However, you might want to include code to handle parameter names that use reserved characters, for possible future use. 1. Separate the encoded parameter names from their encoded values with the equals sign ( = ) (ASCII character 61), even if the parameter value is empty. 1. Separate the name-value pairs with an ampersand ( & ) (ASCII character 38). 1. Create the string to sign according to the following pseudo-grammar (the `"\n"` represents an ASCII newline character). ``` StringToSign = HTTPVerb + "\n" + ValueOfHostHeaderInLowercase + "\n" + HTTPRequestURI + "\n" + CanonicalizedQueryString ``` The HTTPRequestURI component is the HTTP absolute path component of the URI up to, but not including, the query string. If the HTTPRequestURI is empty, use a forward slash ( / ). 1. Calculate an RFC 2104-compliant HMAC with the string you just created, your Secret Access Key as the key, and SHA256 or SHA1 as the hash algorithm. For more information, see [http://www.ietf.org/rfc/rfc2104.txt](http://www.ietf.org/rfc/rfc2104.txt). 1. Convert the resulting value to base64. 1. Use the resulting value as the value of the `Signature `request parameter. **Important** The final signature you send in the request must be URL encoded as specified in RFC 3986 (for more information, see [http://www.ietf.org/rfc/rfc3986.txt](http://www.ietf.org/rfc/rfc3986.txt)). If your toolkit URL encodes your final request, then it handles the required URL encoding of the signature. If your toolkit doesn't URL encode the final request, then make sure to URL encode the signature before you include it in the request. Most importantly, make sure the signature is URL encoded *only once*. A common mistake is to URL encode it manually during signature formation, and then again when the toolkit URL encodes the entire request. Some toolkits implement RFC 1738, which has different rules than RFC 3986 (for more information, go to [http://www.rfc-editor.org/rfc/rfc2104.txt](http://www.rfc-editor.org/rfc/rfc2104.txt). **Example PutAttributes Request** ``` https://sdb.amazonaws.com/?Action=PutAttributes &DomainName=MyDomain &ItemName=Item123 &Attribute.1.Name=Color&Attribute.1.Value=Blue &Attribute.2.Name=Size&Attribute.2.Value=Med &Attribute.3.Name=Price&Attribute.3.Value=0014.99 &Version=2009-04-15 &Timestamp=2010-01-25T15%3A01%3A28-07%3A00 &SignatureVersion=2 &SignatureMethod=HmacSHA256 &AWSAccessKeyId= ``` Following is the string to sign. ``` GET\n sdb.amazonaws.com\n /\n AWSAccessKeyId= &Action=PutAttributes &Attribute.1.Name=Color &Attribute.1.Value=Blue &Attribute.2.Name=Size &Attribute.2.Value=Med &Attribute.3.Name=Price &Attribute.3.Value=0014.99 &DomainName=MyDomain &ItemName=Item123 &SignatureMethod=HmacSHA256 &SignatureVersion=2 &Timestamp=2010-01-25T15%3A01%3A28-07%3A00 &Version=2009-04-15 ``` Following is the signed request. ``` https://sdb.amazonaws.com/?Action=PutAttributes &DomainName=MyDomain &ItemName=Item123 &Attribute.1.Name=Color&Attribute.1.Value=Blue &Attribute.2.Name=Size&Attribute.2.Value=Med &Attribute.3.Name=Price&Attribute.3.Value=0014.99 &Version=2009-04-15 &Timestamp=2010-01-25T15%3A01%3A28-07%3A00 &Signature= &SignatureVersion=2 &SignatureMethod=HmacSHA256 &AWSAccessKeyId= ``` ## About the Time Stamp The time stamp (or expiration time) you use in the request must be a `dateTime` object, with the complete date plus hours, minutes, and seconds (for more information, go to [http://www.w3.org/TR/xmlschema-2/\$1dateTime](http://www.w3.org/TR/xmlschema-2/#dateTime)). For example: 2010-01-31T23:59:59Z. Although it is not required, we recommend you provide the time stamp in the Coordinated Universal Time (Greenwich Mean Time) time zone. If you specify a time stamp (instead of an expiration time), the request automatically expires 15 minutes after the time stamp (in other words, AWS does not process a request if the request time stamp is more than 15 minutes earlier than the current time on AWS servers). Make sure your server's time is set correctly. **Important** If you are using .NET you must not send overly specific time stamps, due to different interpretations of how extra time precision should be dropped. To avoid overly specific time stamps, manually construct `dateTime` objects with no more than millisecond precision.