APIs are becoming a main interface for interacting with many things, from enterprise services, public services offered over the internet to physical devices. As there can be a large number of APIs deployed within an organization and there can many consumers for those APIs, properly authenticating all parties involved in API based interactions is a major step of API security. This article looks at different authentication scenarios related to APIs and possible implementation approaches.

API正在成为与许多事物进行交互的主要接口，从企业服务，互联网提供的公共服务到物理设备。 由于组织内可能部署了许多API，并且这些API的使用方很多，因此正确验证基于API的交互中涉及的所有各方是API安全的重要步骤。 本文介绍了与API和可能的实现方法有关的不同身份验证方案。

First, let’s look at main entities involved in a simple API deployment (Figure 1). We have a set of services that need to be exposed as APIs. These services can be back end services deployed in on-premise data centers, service offered by a device or cloud services. Then we have client applications that need to consume services. These can be mobile applications, web applications, IoT devices, partner systems, etc. Some client applications will be used by human users (e.g. mobile apps and web apps) and some may not have an associated human user (e.g. IoT devices). API layer sits in between client applications and services, forming a proxy for all service requests. Details about organization’s users are stored in its identity provider (IDP). API layer uses IDP to authenticate users and access user information. IDP can be built into the API layer or can be an external IDP.

首先，让我们看一下简单API部署中涉及的主要实体(图1)。 我们有一组服务需要公开为API。 这些服务可以是部署在本地数据中心中的后端服务，由设备提供的服务或云服务。 然后，我们有需要使用服务的客户端应用程序。 这些可以是移动应用程序，Web应用程序，IoT设备，合作伙伴系统等。某些客户端应用程序将由人类用户使用(例如，移动应用程序和Web应用程序)，而某些客户端应用程序可能没有关联的人类用户(例如IoT设备)。 API层位于客户端应用程序和服务之间，形成所有服务请求的代理。 有关组织用户的详细信息存储在其身份提供程序(IDP)中。 API层使用IDP验证用户身份并访问用户信息。 IDP可以内置在API层中，也可以是外部IDP。

As human users, devices and systems access services via APIs, API layer can identify who is accessing services. Moving the authentication part to the API layer can also free up services from performing such tasks in most cases. Furthermore, API layer can provide a single authentication experience to all users by hiding possibly heterogeneous authentication mechanisms required for back end services.

当人类用户，设备和系统通过API访问服务时，API层可以识别谁在访问服务。 在大多数情况下，将身份验证部分移至API层还可以使服务免于执行此类任务。 此外，API层可以通过隐藏后端服务所需的异构身份验证机制为所有用户提供单一身份验证体验。

身份验证方案 (Authentication scenarios)

In the following sections, we examine different authentication scenarios related to APIs.

在以下各节中，我们研究与API相关的不同身份验证方案。

Scenario 1:

方案1：

Assume that a company named HMart is developing a web portal for its employees to access company’s facilities (Figure 2). This web portal needs to invoke APIs of multiple systems such as HR system, building management system, parking slot allocation system, etc. In this scenario, the client application is HMart portal. Application users are HMart’s employees, whose details are stored in HMart IDP. Therefore, in this scenario, it is possible and useful to authenticate both the client application and users.

假设一家名为HMart的公司正在开发一个供其员工访问公司设施的Web门户(图2)。 该Web门户需要调用多个系统的API，例如HR系统，建筑物管理系统，停车位分配系统等。在这种情况下，客户端应用程序是HMart门户。 应用程序用户是HMart的员工，其详细信息存储在HMart IDP中。 因此，在这种情况下，对客户端应用程序和用户进行身份验证是可能且有用的。

Scenario 2:

方案2：

Assume that there is a partner company named DDStore, which has an online shopping app. HMart is a supplier of DDStore. DDStore’s shopping app needs to access HMart product catalog via an API (Figure 3). In this case, DDStore shopping app is used by its customers and this customer data is stored in a DDStore IDP. Usually, HMart only needs to know that DDStore shopping app is accessing its APIs, rather than knowing each customer who is using the shopping app. Furthermore, DDStore would not be willing to share its customer data with HMart. Therefore, in this scenario, it is sufficient to authenticate only the client application (i.e. shopping app) at the API layer. Authentication of users will be performed only by the DDStore shopping app using DDStore IDP.

假设有一个名为DDStore的合作伙伴公司，该公司有一个在线购物应用程序。 HMart是DDStore的供应商。 DDStore的购物应用程序需要通过API访问HMart产品目录(图3)。 在这种情况下，其客户使用DDStore购物应用程序，并且此客户数据存储在DDStore IDP中。 通常，HMart仅需要知道DDStore购物应用正在访问其API，而不需要知道正在使用该购物应用的每个客户。 此外，DDStore不愿意与HMart共享其客户数据。 因此，在这种情况下，仅在API层对客户端应用程序(即购物应用程序)进行身份验证就足够了。 用户身份验证将仅由使用DDStore IDP的DDStore购物应用程序执行。

方案3： (Scenario 3:)

Consider a scenario where a sensor installed in one of HMart warehouses sending temperature values periodically to HMart warehouse management system via an API (Figure 4). Another scenario would be HMart reporting system accessing HMart building management system to get building occupation data via an API. In these scenarios, regardless of whether the client is an internal system or an external system, there is no user associated with it. Therefore, from the authentication perspective, we can consider this similar to Scenario 2 and authenticate only the client system.

考虑以下情况：安装在HMart仓库之一中的传感器通过API定期向HMart仓库管理系统发送温度值(图4)。 另一种情况是HMart报告系统访问HMart建筑物管理系统以通过API获取建筑物占用数据。 在这些情况下，无论客户端是内部系统还是外部系统，都没有与之关联的用户。 因此，从身份验证的角度来看，我们可以认为这与方案2类似，并且仅对客户端系统进行身份验证。

方案4： (Scenario 4:)

In scenario 2, we considered a situation where two separate organizations interact using APIs. In that scenario, IDPs are completely isolated from each other and the API layer only considers DDStore as the client, not its individual users. However, there could be use cases where two organizations are maintaining separate IDPs, yet need to authenticate individual users as well. As an example, we can assume HMart to have a head office and multiple regional offices, each maintaining its own IDPs. Now let’s consider a use case where a head office employee visits a regional office and attempts to use its warehouse management system’s web portal. In this case, it may be useful to authenticate both the client application and the user, although the user is not registered in the IDP associated with the API layer.

在场景2中，我们考虑了两个单独的组织使用API​​进行交互的情况。 在这种情况下，IDP彼此完全隔离，并且API层仅将DDStore视为客户端，而不是其单个用户。 但是，在某些情况下，两个组织将维护单独的IDP，但同时也需要对单个用户进行身份验证。 例如，我们可以假设HMart拥有总部和多个区域办事处，每个办事处都维护自己的IDP。 现在让我们考虑一个用例，其中总部员工访问区域办事处并尝试使用其仓库管理系统的Web门户。 在这种情况下，尽管未在与API层关联的IDP中注册用户，但对客户端应用程序和用户进行身份验证可能还是有用的。

方案5： (Scenario 5:)

So far, we have looked at situations where clients authenticate with the API layer. However, there could be situations where the API layer may also have to authenticate with back end services. One example is when the API layer needs to call a cloud service such as Salesforce or Google Sheets. Even within the same organizational network, it is useful enforce authentication mechanisms for each system as it enables administrators to track and control service interactions. For example, HMart parking slot allocation system may have an authentication mechanism to authenticate any application that uses its services. Furthermore, authenticating users with back end services and passing user information to them could be useful for enforcing fine grained access control at those services (e.g. only the users with manager role and working at the administration division can access parking slot usage data).

到目前为止，我们已经研究了客户端通过API层进行身份验证的情况。 但是，在某些情况下，API层也可能必须通过后端服务进行身份验证。 一个示例是API层需要调用诸如Salesforce或Google Sheets之类的云服务时。 即使在同一个组织网络中，它对于每个系统强制执行身份验证机制也是有用的，因为它使管理员能够跟踪和控制服务交互。 例如，HMart停车位分配系统可以具有认证机制，以认证使用其服务的任何应用程序。 此外，使用后端服务对用户进行身份验证并将用户信息传递给他们对于在那些服务上执行细粒度的访问控制可能很有用(例如，只有具有管理者角色并且在管理部门工作的用户才能访问停车位使用情况数据)。

实施方法 (Implementation methods)

In this section, we will discuss different authentication mechanisms and how they can be used to implement authentication scenarios discussed above.

在本节中，我们将讨论不同的身份验证机制以及如何将其用于实现上述身份验证方案。

验证客户端应用程序 (Authenticating client applications)

First we will look at methods for authenticating client applications. These methods can be used to implement scenarios 2 and 3, which require only the client application to be authenticated. Furthermore, these methods can be used in conjunction with different user authentication methods discussed in the next section to implement scenarios 1 and 4, which require both the client application and the user to be authenticated. Scenario 5 requires API layer to be authenticated with back end services. Below methods can be used for that scenario by considering API layer as the client application.

首先，我们将研究验证客户端应用程序的方法。 这些方法可用于实现方案2和3，方案2和3仅要求对客户端应用程序进行身份验证。 此外，这些方法可以与下一部分中讨论的不同用户身份验证方法结合使用，以实现方案1和4，这需要对客户端应用程序和用户都进行身份验证。 方案5要求API层通过后端服务进行身份验证。 通过将API层视为客户端应用程序，可以将以下方法用于该场景。

Client certificates: We can create a certificate for each client application containing the client identifier and other required details, and sign it with a certificate trusted by the API layer. Client application has to send its certificate with each API invocation so the the API layer can validate the certificate and identify the client.

客户端证书：我们可以为每个包含客户端标识符和其他所需详细信息的客户端应用程序创建一个证书，并使用API​​层信任的证书对其进行签名。 客户端应用程序必须在每次API调用时发送其证书，以便API层可以验证证书并识别客户端。

API keys: Each client application can register with the API layer and obtain a unique key to represent itself. This key can be just a string or a meaningful text signed with a trusted certificate. In either case, client applications have to send their API keys with each API invocation and the API layer can correlate the API key to a registered application.

API密钥：每个客户端应用程序都可以向API层进行注册，并获得代表其自身的唯一密钥。 该密钥可以只是字符串，也可以是使用受信任证书签名的有意义的文本。 无论哪种情况，客户端应用程序都必须在每次API调用时发送其API密钥，并且API层可以将API密钥与已注册的应用程序相关联。

OAuth 2.0 tokens (client credentials grant type): Client credentials grant type only requires client application identifier and client secret for generating an OAuth token. Therefore, when a client application sends such OAuth token with API invocations, API layer can uniquely identify the client. In this case, user is not identified as user credentials are not used for generating OAuth tokens.

OAuth 2.0令牌(客户端凭据授予类型)：客户端凭据授予类型仅需要客户端应用程序标识符和客户端密钥即可生成OAuth令牌。 因此，当客户端应用程序通过API调用发送此类OAuth令牌时，API层可以唯一地标识客户端。 在这种情况下，不会将用户标识为用户凭证，因为用户凭证未用于生成OAuth令牌。

验证用户 (Authenticating users)

Now we can look at methods for authenticating users. These methods can be used alone or in conjunction with client application authentication methods to identify both the client application and the user as required by scenario 1 and 4.

现在我们来看一下验证用户身份的方法。 这些方法可以单独使用，也可以与客户端应用程序身份验证方法结合使用，以根据场景1和4的要求识别客户端应用程序和用户。

HTTP Basic Authentication: HTTP basic authentication can be used to send user credentials in HTTP headers with each API invocation. Therefore, this method can be used to authenticate users with the API layer. Furthermore, if we represent an application using some user credentials, it is possible to use basic authentication for authenticating client applications as well. The downside of this method is that user credentials can be exposed to unintended parties if TLS is not used.

HTTP基本身份验证： HTTP基本身份验证可用于在每次API调用时在HTTP标头中发送用户凭据。 因此，此方法可用于通过API层对用户进行身份验证。 此外，如果我们使用某些用户凭据表示应用程序，则也可以使用基本身份验证来验证客户端应用程序。 这种方法的缺点是，如果不使用TLS，则用户凭据可能会暴露给意外的参与者。

HTTP Digest Authentication: HTTP digest authentication sends hashed value of user credentials of with each API invocation. Therefore, similar to HTTP basic authentication, this can be used for both user and client application identification. However, the risk of exposing user credentials is eliminated as hashed values are used.

HTTP摘要身份验证： HTTP摘要身份验证在每次API调用时发送的用户凭据的哈希值。 因此，类似于HTTP基本身份验证，此方法可用于用户和客户端应用程序标识。 但是，由于使用了哈希值，因此消除了暴露用户凭据的风险。

OAuth 2.0 tokens (authorization code grant type): Authorization code grant type requires both client application credentials and user credentials when issuing an OAuth token. Therefore, when such tokens are sent with each API invocation, API layer can identify both the client application and the user.

OAuth 2.0令牌(授权代码授予类型)：颁发OAuth令牌时，授权代码授予类型既需要客户端应用程序凭证，也需要用户凭证。 因此，在每次API调用时发送此类令牌时，API层可以识别客户端应用程序和用户。

验证来自外部身份提供商的用户 (Authenticating users from external identity providers)

In scenario 4, HMart head office and each HMart regional office have separate identity providers. API layer of each of HMart regional office only trusts its identity provider. Now the problem in scenario 4 is that an employee belonging to HMart head office wants to access a warehouse API deployed in a HMart regional office.

在方案4中，HMart总部和每个HMart区域办事处都有单独的身份提供者。 HMart地区办事处的每个API层仅信任其身份提供者。 现在，场景4中的问题是属于HMart总公司的一名员工想要访问部署在HMart地区办公室中的仓库API。

As this is the same organization, regional office IDPs can trust the head office IDP. One way of establishing this trust is to import head office IDP’s certificate into regional office IDPs as a trusted certificate (Figure 7). Then the head office user can first obtain a security token (e.g. containing user name and other relevant details) from head office IDP (as the user is in it’s user store), signed by head office IDP’s private key. Now the user can present this security token to regional office IDP and exchange it for a security token recognized by regional office API layer. Then this new security token can be used for the regional office warehouse API invocations. Some implementations of this approach is JWT token exchange and SAML token exchange, where JWT or SAML tokens obtained from external IDP’s are exchanged for OAuth 2.0 tokens recognized by the API layer.

由于这是同一组织，因此地区办公室IDP可以信任总部IDP。 建立这种信任的一种方法是将总部IDP的证书作为受信任的证书导入到区域办公室IDP中(图7)。 然后，总部用户首先可以从总部IDP(因为用户在其用户存储区中)获得安全令牌(例如，包含用户名和其他相关详细信息)，并由总部IDP的私钥签名。 现在，用户可以将此安全令牌提供给区域办事处IDP，并将其交换为区域办事处API层识别的安全令牌。 然后，可以将此新安全令牌用于区域办公室仓库API调用。 此方法的一些实现是JWT令牌交换和SAML令牌交换，其中将从外部IDP获得的JWT或SAML令牌交换为API层识别的OAuth 2.0令牌。

Another approach for enabling trust relationship among IDPs is to configure the head office IDP as a federated identity provider of the regional IDP (Figure 8). That means, when a user tries to authenticate with the regional office IDP, he also gets the option for authenticating via the head office IDP. If a user selects head office IDP option and successfully authenticates with it, regional office IDP will trust that authentication and issue a security token valid for regional office API layer. Common implementations of this approach are OpenID Connect federation and SAML federation.

启用IDP之间信任关系的另一种方法是将总部IDP配置为区域IDP的联合身份提供者(图8)。 这意味着，当用户尝试通过区域办公室IDP进行身份验证时，他还将获得通过总部IDP进行身份验证的选项。 如果用户选择总部IDP选项并成功进行身份验证，则区域办事处IDP将信任该身份验证并颁发对区域办事处API层有效的安全令牌。 这种方法的常见实现是OpenID Connect联合和SAML联合。

使用后端系统进行身份验证 (Authenticating with back end systems)

Approaches described above can be used to authenticate API consumers with the API layer and can be used to implement scenarios 1 to 4. Similar to the API layer, back end services may also want to authenticate either client applications, users or both, which is the problem considered in scenario 5. Note that in this scenario, client application is always the API layer. We can use any of the client application authentication methods discussed above to authenticate the API layer with back end services (i.e. client certificates, API keys or client credentials based OAuth 2.0 tokens). It is also possible to represent the API layer as a user account in back end services and use user credentials based authentication mechanisms (e.g. HTTP basic authentication) to authenticate the API layer. Similar to the way we can embed tokens/credentials in client applications, we can embed credentials in the API layer as well.

上述方法可用于通过API层对API使用者进行身份验证，并可用于实现方案1至4。类似于API层，后端服务可能还希望对客户端应用程序，用户或两者进行身份验证。方案5中考虑的问题。请注意，在此方案中，客户端应用程序始终是API层。 我们可以使用上面讨论的任何客户端应用程序身份验证方法来通过后端服务(即，基于OAuth 2.0令牌的客户端证书，API密钥或客户端凭据)对API层进行身份验证。 还可以将API层表示为后端服务中的用户帐户，并使用基于用户凭据的身份验证机制(例如HTTP基本身份验证)来对API层进行身份验证。 与我们在客户端应用程序中嵌入令牌/凭据的方式类似，我们也可以在API层中嵌入凭据。

Now we can consider authenticating users with back end services. One method is to send user credentials or hashed credentials to back end services. However, as back end services and the API layer may have different user stores, two sets of user credentials may have to be used. Further, back end service user credentials have to be passed through the API layer, which can expose them unless those are encrypted. Therefore, a better approach for authenticating users with back ends is to have a trust relationship between API layer and back ends. Then for each request, API layer can create a token containing user details and sign it with API layer’s private key. As back end services trust API layer’s certificate, those services can validate the user details sent in the signed token and authenticate the user. This method can be realized by generating JWT tokens signed by API layer’s private key and sending them to back end services.

现在，我们可以考虑使用后端服务对用户进行身份验证。 一种方法是将用户凭据或哈希凭据发送到后端服务。 但是，由于后端服务和API层可能具有不同的用户存储，因此可能必须使用两组用户凭据。 此外，后端服务用户凭据必须通过API层传递，除非这些凭据经过加密，否则它们可以公开它们。 因此，一种通过后端认证用户的更好方法是在API层和后端之间具有信任关系。 然后，对于每个请求，API层都可以创建一个包含用户详细信息的令牌，并使用API​​层的私钥对其进行签名。 当后端服务信任API层的证书时，这些服务可以验证在签名令牌中发送的用户详细信息并验证用户身份。 可以通过生成由API层的私钥签名的JWT令牌并将其发送到后端服务来实现此方法。

整体图片 (The overall picture)

We have looked at different API authentication scenarios and possible implementation methods. Now we can see how these methods can be combined to achieve better API security from the authentication perspective.

我们研究了不同的API身份验证方案和可能的实现方法。 现在，我们将从身份验证的角度看到如何组合使用这些方法以实现更好的API安全性。

Above diagram shows interactions among HMart head office, HMart regional office and DDStore (partner) systems. API calls are indicated in blue color arrows. Client to API layer authentications are marked in red color arrows. First, let’s take the scenario of Jane (HMart regional office employee) accessing the warehouse portal. Jane is authenticated with the regional office IDP and a API token is issued to the warehouse portal. Warehouse portal uses this token to invoke warehouse management system’s APIs via the API layer.

上图显示了HMart总部，HMart区域办事处和DDStore(伙伴)系统之间的交互。 API调用以蓝色箭头指示。 客户端到API层的身份验证用红色箭头标记。 首先，让我们以Jane(HMart地区办事处员工)访问仓库门户的场景为例。 Jane已通过区域办事处IDP进行身份验证，并且向仓库门户发出了API令牌。 仓库门户网站使用此令牌通过API层调用仓库管理系统的API。

Now we can consider the scenario where Peter (HMart head office employee) uses the warehouse mobile app. Regional office IDP is configured as the IDP of the mobile app. Therefore, Peter is directed to authenticate with the regional office IDP. However, as the head office IDP is configured as a federated IDP, Peter can select that option and authenticate with the head office IDP. Once authenticated, regional office IDP recognizes that and issues a API token to the mobile app, which can be used to invoke warehouse APIs.

现在我们可以考虑Peter(HMart总部员工)使用仓库移动应用程序的情况。 区域办事处IDP被配置为移动应用程序的IDP。 因此，Peter被指示向区域办事处IDP进行身份验证。 但是，由于总部IDP被配置为联合IDP，因此Peter可以选择该选项并向总部IDP进行身份验证。 身份验证后，区域办事处IDP会识别出该问题并向移动应用程序发出API令牌，该令牌可用于调用仓库API。

Finally, we can consider the scenario where Mark (DDStore customer) uses the DDStore shopping portal to buy products. Shopping portal first authenticates Mark with DDStore IDP. DDStore IDP issues an API token for the shopping portal to be used for relevant internal API invocations including the inventory management API. However, DDStore inventory management system needs to invoke HMart’s warehouse API to order products that are not available in DDStore stocks. Inventory management system gets an API token from the HMart regional office IDP using the client credentials grant type. In addition to token based authentication, HMart enforces certificate based client system authentication in order mitigate risks of token leakages. To enable this, inventory system’s certificate is associated with HMart API layer as a valid client certificate. Therefore, DDStore inventory system sends both API token and its certificate (via mutual TLS) to securely access HMart APIs. All API layers can use any combination of basic authentication, API keys and client certificates to authenticate with corresponding backend systems as discussed earlier.

最后，我们可以考虑Mark(DDStore客户)使用DDStore购物门户购买产品的情况。 购物门户网站首先使用DDStore IDP对Mark进行身份验证。 DDStore IDP为购物门户颁发API令牌，以用于相关的内部API调用，包括库存管理API。 但是，DDStore库存管理系统需要调用HMart的仓库API来订购DDStore库存中不可用的产品。 库存管理系统使用客户端凭据授予类型从HMart区域办事处IDP获取API令牌。 除了基于令牌的身份验证之外，HMart还执行基于证书的客户端系统身份验证，以减轻令牌泄漏的风险。 为此，库存系统的证书与HMart API层相关联，作为有效的客户端证书。 因此，DDStore库存系统同时发送API令牌及其证书(通过双向TLS)以安全地访问HMart API。 所有API层都可以使用基本身份验证，API密钥和客户端证书的任意组合，以使用相应的后端系统进行身份验证，如前所述。