This document is aimed at RESTful API callers.

Introduction to API Certification

Users can interact with Baidu AI Cloud in two ways: authentication and anonymous. For authentication method, you need to verify the identity of a request sender by using Access Key Id / Secret Access Key encryption method. Access Key Id (AK) is used to identify users, and Secret Access Key (SK) is a key used by users to encrypt authentication string and by Baidu AI Cloud to verify the authentication string, where SK must be confidential, which can only be known by users and Baidu AI Cloud.

After Baidu Cloud receives a request of users, the system will use the same SK and authentication mechanism to generate an authentication string, and compare it with the authentication string contained in the user request. If the two authentication strings are the same, the system considers that the user has the designated operation privilege, and executes the related operations; if the two authentication strings are different, the system will ignore the operation and return an error code.

Note:

This document is mainly for RESTful API callers, and SDK users do not need to pay attention. A complete signature algorithm has been encapsulated in the SDK, and users do not need to implement it themselves.

API Certification Advantages

API certification will bring the following advantages to users:

• Verify the identity of the requester.
  The authentication string uses the AK/SK of the specified user to sign the HTTP request, which can verify the identity of the user. For getting AK/SK, please see Get AK/SK.
• Protect the transmitted content against illegal tampering.
  The user generates an authentication string based on the specified content of the HTTP request. If it is illegally tampered during transmission, the authentication string generated by the system will not match the authentication string generated by the user, and eventually the authentication will fail.
• Prevent replay attacks.
  The authentication strings all have a specified effective time. A request must reach Baidu AI Cloud within the specified time, otherwise the system will reject the request.

In order to protect the user's SK information, Baidu AI Cloud does not directly use SK information, but uses SK to generate a SigningKey, and at the same time contains a valid time range in SigningKey. This can reduce the security risks caused by the loss of the SigningKey.

API Authentication Method

Baidu AI Cloud uses the authentication algorithm to calculate the specified content of the HTTP request and outputs an authentication string for authentication. Developers need to first connect the specified content of the HTTP request into a string, combined with the SK allocated by Baidu AI Cloud, and calculate the message digest through the HMAC algorithm. This process is also the process of signing the HTTP request. Baidu AI Cloud API uses an HTTP request signature mechanism based on the authentication string to verify the user's identity. Each HTTP request shall carry an authentication string and then include this authentication string in the request in the following two ways:

• Include the Authentication String into the Header

  The commonly used method is to include the authentication string in the Authorization header field of the HTTP request. Except for anonymous requests, all interactions with Baidu AI Cloud should include this field. For more information on how to include the authentication string in the HTTP Header, please see Include the Authentication String into the Header.

• Include the Authentication String into the URL

  The user can also place the authentication string in the authorization parameter of the Query String of the HTTP request. It is often used to generate scenarios where a URL is used by a third party, for example, to temporarily open some data to others for download. For how to include the authentication string in the URL, please see Include the Authentication String into the URL.

User Requested Authentication Process

The Baidu AI Cloud API uses an authentication string-based HTTP request signature mechanism to verify user identity. The non-anonymous HTTP requests should carry an authentication string. After Baidu AI Cloud receives the user's HTTP request, the system will process it according to the process shown in the figure below.

1. Determine whether the user's HTTP request is anonymous, that is, whether the user's request contains the Authorization authentication string. If it does not contain an authentication string, you need to refer to other related processes for processing according to different business situations; if it contains an authentication string, perform the next step.

2. Determine whether the user's request has timed out, that is, the time required for the server to receive the request must meet the following requirements:

   {timestamp}-5 minutes <request time received by the server <{timestamp}+{expirationPeriodInSeconds}+5 minutes

   Where timestamp represents the UTC time when the signature was valid, andexpirationPeriodInSeconds represents the validity period of the signature.

   To prevent authentication failures caused by user clocks not being synchronized with server clocks, a 5-minute leniency factor is introduced here. If the time that the server receives the request does not meet the above time requirements, the request is considered to have timed out and the request is rejected; if the above requirements are met, perform the next step.

3. Based on the HTTP request information, use the same algorithm to generate a Signature string.
4. Use the Signature string generated by the server to compare with the string provided by the user. If the content is inconsistent, the authentication is considered failed and the request is rejected; if the content is consistent, the authentication is successful and the system will operate according to the user's request.

Authentication String Generation Method

The generation mechanism of Baidu AI Cloud authentication string is shown in the following figure:

For detailed schemes of generating authentication strings, please see Generate Authentication String.

Some Baidu AI Cloud products support the latest V2 authentication string. For the generation method, see Generate V2 Authentication String. The products that currently support V2 certification strings are the Table Service BTS.

Glossary

The core terms involved in this section are explained as follows:

• Authentication string: Authentication information that must be carried in non-anonymous requests. It contains the information necessary to generate the string to be signed CanonicalRequest and the signature digest signature.
• authStringPrefix: The prefix part of the authentication string.
• canonicalRequest: String to be signed. It carries request information normalized.
• signingKey: Signature Key. Baidu AI Cloud does not directly use SK to generate digests for signature strings. In contrast, Baidu AI Cloud first uses SK and the authentication string prefix to generate the signingKey, and then uses the signingKey to generate a digest for the string to be signed.
• signature: Signature digest. Baidu AI Cloud uses the signingKey to calculate the signature for the canonicalRequest by HMAC algorithm.

Video Reference

You can also refer to Call API Interface by Python from Scratch. The first half of the video introduces Baidu AI Cloud authorization and authentication mechanism to help you get to know faster.