LinkedIn
Twitter
This article is an introductory overview of some widely used identification and authentication patterns for API requests and how they can be implemented in Apigee. Reference implementations for many of these patterns can be found in the Apigee DevRel repository.
The Role of Authentication in API Management
One common use case for using an enterprise API management platform, such as Apigee, is to perform authentication and potentially authorization for incoming API requests. The goal of using an API management platform for authentication is to move the burden of correctly implementing authentication standards away from the individual target services and instead have a centralized capability to ensure that only known and trusted clients can access the APIs. Target systems are still able to perform additional authentication checks and do their own fine grained authorization of the incoming requests. The API proxy hereby establishes one level of authentication in a layered security model to achieve defense in depth.
Terminology
Without going too much into the academic details, some terminology is important to introduce the different authentication patterns in this article:
Identification is the act of indicating a person or thing's identity which differs from authentication because it does not require verifying that identity.
Authentication is the act of proving a claim, such as the identity of a computer system user.
Authorization is the function of specifying access rights/privileges to resources given a specific identity.
Identity Provider (IdP) is a system entity that creates, maintains, and manages identity information for principals and also provides authentication services.
Common Design Questions
The following questions are commonly used in selecting and designing a suitable authentication mechanism for APIs:
Which identities need to be asserted?
Is the client a mobile or web application? Is the client required to provide an assertion that they are who they claim to be? Does the application claim to have consent from an end user to access resources on their behalf?
Where are the identities managed?
API platforms, such as Apigee, can serve as an identity provider (IdP) for client applications and automatically issue client credentials for them. Developers can ideally create these applications in a self-service model through a developer portal.
Some API providers might prefer to have an external IdP that manages identities for applications and/or end users centrally. They would like to keep on using the identities from the external IdP because they are known across their systems and can be propagated down to the backend systems for secondary authentication and authorization.
For end user authentication an external IdP is required as Apigee’s built in IdP does not provide user management for end users. In practice this is typically done through OpenID Connect (OIDC) and products like identity platform.
What type of applications are accessing the APIs?
Depending on the type of application that is acting as an API client, the available authentication mechanisms might be different. A static web application, for instance, isn’t able to hold on to sensitive values such as client secrets, because anyone can directly read the configuration and identification values in the website’s code. On the other hand, a simple batch job cannot participate in an authorization code grant type because it typically cannot receive interactive approval from a resource owner.
Which automation and integration capabilities exist on the external IdP?
Assuming the authentication leverages an external IdP, does the external IdP provide APIs to integrate with identities that are managed in another IdP such as the one built into Apigee?
Do you require analytics data to measure developer engagement?
Apigee can only report actionable developer engagement analytics if the applications that are validated are known application identities. Whilst it can delegate trust and validate externally issued assertions, it will lack the necessary metadata to report on important business metrics such as the developer engagement for the API program.
Common Authentication Mechanisms in Apigee
In this section we provide an overview over widely used authentication mechanisms and how they can be implemented in Apigee. Most of these mechanisms are also provided as examples in the Apigee DevRel repository.
Each authentication mechanism starts with a quick summary consisting of:
- Difficulty: Level of difficulty of the implementation
- Apigee Policies: Links to Apigee policies used to implement the pattern
- Self-Service Compatibility: Can this pattern be used in a self-service onboarding of API consumers
- End user authentication: Can this be used to authenticate calls with (human) end user authentication
- Developer Engagement Analytics: Will this mechanism allow you to capture analytics data about the developers and apps using your APIs
Apigee with API Key (Identification only)
|
Difficulty |
Easy |
|
Apigee Policies |
|
|
Identity Provider |
Apigee Built-in |
|
Credentials can be issued in self-service |
Yes |
|
Can be used for end user authentication |
No |
|
Provides developer engagement analytics |
Yes |
One of the easiest ways to identify an API client is by using an API key. The Apigee’s built-in identity provider is able to issue client identifiers that can be used as an API key and validated using the out of the box VerifyAPIKey policy.
The simplicity of API keys comes with the caveat that this mechanism can only be used for identifying incoming requests and should not be used as an authentication mechanism in untrusted environments. API keys are generally long-lived and can often be read from access logs or are not properly masked in tooling.
Apigee with OAuth2 Token (Client Credentials Flow in Apigee)
|
Difficulty |
Medium |
|
Apigee Policies |
|
|
Identity Provider |
Apigee Built-in |
|
Credentials can be issued in self-service |
Yes |
|
Can be used for end user authentication |
No |
|
Provides developer engagement analytics |
Yes |
OAuth2 is a comprehensive industry standard that is widely used across API providers. Apigee supports a variety of different grant types for OAuth2 as described in the official documentation. Most widely adapted Apigee authentication mechanisms are built using the OAuth2 standard.
A common implementation is to use the OAuth2 Client Credentials grant type for accessing APIs. In this scenario the API client is using its client id and client secret to request an access token. The access token is then used on subsequent calls against the protected endpoints to authenticate the API client. Both the issuance of access tokens and their verification can be achieved using the built-in Apigee policy as described here.
Apigee with an external Token or Assertion
|
Difficulty |
Medium |
|
Apigee Policies |
|
|
Identity Provider |
External IdP |
|
Credentials can be issued in self-service |
Depends on the 3rd party IdP, Not available in the Apigee integrated portal. |
|
Can be used for end user authentication |
Yes |
|
Provides developer engagement analytics |
Requires synchronization between the Apigee IdP and the external IdP. |
By using externally generated tokens, Apigee only cryptographically verifies that the token is issued by a trusted issuer. Apigee is not involved in issuing the token and does not automatically hold any information about the application, developer, or API product that is associated with the API request.
For scenarios where some of these aspects are required e.g. to provide insights into developer engagement or to easily restrict the usage of a token to a specific Apigee environment, additional synchronization of the Apigee identities and the externally managed identities is required. One common approach to achieve an association of externally managed identities with the Apigee resources is to synchronize the external Idp and the Apigee IdP through automation and the Apigee API. Technically this means that the client id (API key) of an Apigee app can be included within the claims of a third party token such that the Apigee proxy can identify the client application after the authentication through the JWT signature validation.
Alternatively the POST request to /token for the external IDP can be proxied through Apigee and the externally created token can be imported via the Apigee OAuth2 policy and used in subsequent calls as documented here.
Apigee with token exchange
|
Difficulty |
High |
|
Apigee Policies |
|
|
Identity Provider |
External IdP |
|
Credentials can be issued in self-service |
Depends on the 3rd party IdP, Not available in the Apigee integrated portal. |
|
Can be used for end user authentication |
Yes |
|
Provides developer engagement analytics |
Yes |
A token exchange as described in RFC8693 starts the same way as the external token approach described above. In this case however, the externally issued token is exchanged (hence the name) for an Apigee issued token. The process of exchanging an external token or SAML assertion for an Apigee issued token adds an additional layer of trust as the external token can only be used to obtain an Apigee token by authorized applications and not to access the resource APIs directly. Additionally the Apigee context of application, developer and API product contexts can automatically be made available if they are available through the verification of the client credentials of the exchanging client application.
Apigee with an identity facade for 3-legged OAuth
|
Difficulty |
High |
|
Apigee Policies |
|
|
Identity Provider |
External IdP |
|
Credentials can be issued in self-service |
Depends on the 3rd party IdP, Not available in the Apigee integrated portal. |
|
Can be used for end user authentication |
Yes |
|
Provides developer engagement analytics |
Yes |
The main disadvantage of the process as described in the token exchange is that the burden of exchanging the external IdP token for an Apigee token is on the API consumer. API consumers have to explicitly make an additional call and exchange the token and are temporarily holding on to the external token.
An alternative approach to exchanging tokens for the OAuth Authorization Code Flow grant type is what we call as the identity facade for 3-legged OAuth. In this scenario we are using Apigee to create a facade for an external token. This facade proxy calls the token endpoint and then mints an Apigee issued token that links to the external token. This way a token validation in Apigee makes the external token available within the flow such that it can be used to call downstream systems. Because the token is intercepted through the facade the API client does not have access to the external token directly. This means that the API clients won’t be able to circumvent the API proxy by calling the backends directly and by using the external token. From a client perspective the facade nature is transparent and the OAuth flow looks identical to any other authorization code flow.
To simplify the implementation of this pattern we provide a reference implementation of an identity facade that can be used to front any OIDC compliant IdP.
