API Gateway provides various identity authentication methods for verifying API requests, including Alibaba Cloud APP and OpenID Connect. The Alibaba Cloud APP method supports two authentication modes: encrypted signature identity authentication and simple identity authentication.

1. Overview

For information about encrypted signature identity authentication, see Request signature.

This topic describes in detail how to configure simple identity authentication and how to use this method to call an API operation. Simple identity authentication is much easier to implement than encrypted signature identity authentication. Simple identity authentication does not involve the complex process of signature calculation. Simple identity authentication requires only an AppCode that is automatically provided by API Gateway for an application. You must add the AppCode in the header or as a query parameter of an API request. The following process describes how to call an API operation by using simple identity authentication:

  1. An API provider creates an API operation. When the API provider configures basic information for the API operation, the API provider sets the Security Certification parameter to Alibaba Cloud APP and select Allow AppCode authentication. By default, all API operations in Alibaba Cloud Marketplace support simple identity authentication.
  2. An API caller creates an application in the API Gateway console. If the API caller purchases an API operation in Alibaba Cloud Marketplace, the API caller can also use the application that is automatically created and authorized for the API caller to call the API operation.
  3. The API provider authorizes the API caller's application to call the API operation. For more information about application authorization, see Create an API operation with HTTP as the backend service.
  4. The API caller logs on to the API Gateway console and performs the following steps: In the left-side navigation pane, choose Consume APIs > APPs. On the APP List page, find the target application and click the application name. The APP details page displays the AppCode that is used for simple identity authentication. Use the AppCode to call the API operation.

2. Create an API operation that uses simple identity authentication

  1. When the API provider creates an API operation, the Security Certification parameter must be set to Alibaba Cloud APP or OpenID Connect & Alibaba Cloud APP.
  2. The API provider needs to set the AppCode Certification parameter to Allow AppCode authentication (Header) or Allow AppCode authentication (Header & Query).

As shown in the figure, the AppCode Certification parameter has the following valid values:

  • Open after putting on cloud market: By default, AppCode authentication is disabled. After the API operation is available in Alibaba Cloud Marketplace, AppCode authentication is enabled. The AppCode of an application must be added in the header of each API request.
  • Disable AppCode authentication: AppCode authentication is disabled no matter whether the API operation is available in Alibaba Cloud Marketplace. The API operation can be called only by using encrypted signature identity authentication.
  • Allow AppCode authentication (Header): AppCode authentication is enabled no matter whether the API operation is available in Alibaba Cloud Marketplace. The AppCode of an application must be added in the header of each API request.
  • Allow AppCode authentication (Header & Query): AppCode authentication is enabled no matter whether the API operation is available in Alibaba Cloud Marketplace. The AppCode of an application can be added in the header or as a query parameter of each API request.

Note: When the API provider defines request parameters for the API operation, the API provider does not need to define a header parameter or a query parameter for the AppCode.

3. Call an API operation by using simple identity authentication

Before an API provider provides an API operation for an API caller, the API provider must ensure that AppCode authentication is enabled for the API operation. Then, the API caller can use simple identity authentication to call the API operation without the need to implement complex signature algorithms on a client. This section describes how to call an API operation by using simple identity authentication. When you call an API operation in an application by using simple identity authentication, you can add the AppCode of your application in the header or as a query parameter of the API request.

3.1 Add the AppCode in the header

  • Add a field named Authorization to the header of an API request.
  • The value of the Authorization field must be in the following format: APPCODE + Space + AppCode value.

Format:

Authorization:APPCODE AppCode value

Example:

Authorization:APPCODE 3F2504E04F8911D39A0C0305E82C3301

3.2 Add the AppCode as a query parameter

  • Add the AppCode as a query parameter of an API request. The name of the parameter can be appcode, appCode, APPCODE, or APPCode.
  • The value of the parameter is the value of the AppCode.

Example:

http://www.aliyum.com?AppCode=3F2504E04F8911D39A0C0305E82C3301

4. Risk warning

Simple identity authentication is easy to implement because it does not involve the complex process of signature calculation. However, transmitting the AppCode as plaintext on networks may cause security risks.

You must make sure that your client and API Gateway communicate with each other by using HTTPS instead of HTTP or the WebSocket protocol. Neither HTTP nor the WebSocket protocol supports encryption. Therefore, an AppCode will be transmitted as plaintext if you use HTTP or the WebSocket protocol. This causes a high risk that the AppCode may be captured by hackers.