tombcghtech/api_guidelines huggingface dataset:
When implementing an OAuth 2.0 model that supports ‘authorisation code’ flow.
Client secret
Also provided when the OAuth client application is registered. This is used with the client ID when exchanging an authorisation code for an access token.
When implementing an OAuth 2.0 model that supports authorisation code flow.
ID token
ID tokens are JWTs that can be used to:
* authenticate a user
* collect information about a user and send it in a verifiable format that can be trusted by the relying party
* provide information in the token that can be used to customise the client application or to provide claims for an access policy
* provide a set of hashed claims that can be used to verify that the ID token and related access / refresh tokens can be from the service provider.
* These are incorporated into any OAuth 2.0 / OpenID Connect environments as they provide additional security controls that allow a higher level of communication trust between the relying party, the identity provider and the service being protected.
* Use ID tokens to provided verified claims to provide finer grained access to services.
MTLS allows a higher level of trust between different parties when exchanging credentials.
* When the relying party (who owns the client application) is communicating with the OpenID (identity) provider for exchanging credentials.
* Organisations should implement a proof-of-possession / holder-of-key capability that ties the MTLS certificate to the access token when handling confidential / restricted information.
JWT (private_key_JWT)
OAuth 2.0 clients applications can use client IDs and client secrets to authenticate to the services (for example, token generation, user information and access revoke).
RFC 7523 defines the concept of using JWTs for client authentication. This provides additional controls over the standard client ID and secret, and it mandates that the JWT is signed and verified, that it contains the required claims which are validated, and ones (for example, jti – JWT ID) that are used to ensure the JWT is not used twice.
Organisations implement this form of client authentication when protecting information classified confidential and above.
9.1. OAuth scenario (authorisation code grant flow type)
This is a hypothetical scenario to demonstrate a key OAuth pattern using the authorisation code grant flow type. In this scenario Inland Revenue (IR — previously called IRD) has developed a set of APIs that can be used by professional accounting firms to offer additional services to their customers.
The assumption here is that IR have an API gateway, that offers:
an API developer portal
an OAuth authorisation server
a resource server, exposing the APIs that can be called
that IR are securing an API called ‘View IR Return’ with an authorisation code grant type.
9.1.1. Stage 1 client registration — Develop the application (third party)
The third party (in this case MyAccountantWebsite.com) develops a client application that will be exposed to their customers when they login to their website. It will allow customers of MyAccountantWebSite to authorise and set up delegated access for the MyAccountantWebSite application to view their IR returns, but without the customer having to provide their IR username and password to MyAccountantWebsite.
The application will use the APIs exposed by IR and is developed on an MyAccountantWebsite.com application (web) server that can securely store security credentials.
9.1.2. Stage 2 client registration — Register the (client) application
The developer needs to register as a user of the IR API portal. IR needs to verify that this person is allowed to register as a user. (This process is outside the scope of these guidelines and will vary depending on the sensitivity of the APIs exposed.)
As illustrated in figure 29, the authentication of the developer can be via:
IR’s internal client login services
an external identity service provided (OpenID Connect or SAML based, or social network provider).
Once the developer has been approved and has been granted login credentials (username and password) they log onto the IR API portal and register their client application — this is carried out over a TLS secure link. The following information is provided:
name of the application (by the developer)
return URL (by the developer)
client ID (by IR) — stored securely
client secret (by IR) — stored securely.
The developer completes development of the client application on MyAccountantWebsite. The next steps detail how the MyAccountantWebsite customer uses the application.
Note: The values of the client ID and secret are represented as simple strings in figure 29. In reality these are long, randomly generated strings.
Figure 29: Stage 2 client registration
View larger image (PNG 265KB)
9.1.3. Stage 3 client registration — Customer sets new service and authorises access
As illustrated in figure 30, the customer logs into MyAccountantWebsite from their browser and clicks on the IR button (view IR), which should allow the user access to information presented by the ‘view IR return’ API. As there is no current acess token stored for the client application to use, the user is redirected to the IR authorisation server ‘authorisation endpoint’ with the following information:
IR URL A (authorisation endpoint URL)
return URL (where the authorisation code will be sent)
client ID = ABC (random long string that is used to identify the client application)
scope = READ (defined by the application as to what the application can do)
state = xyz123 (random long string that is used to mitigate man-in-the-middle attacks).
Figure 30: Stage 3 client registration
View larger image (PNG 291KB)
9.1.4. Stage 4 client registration — Authentication and approval by the resource owner
Figure 31 illustrates that, as the client application does not have an access token for this customer or a session set up with IR, the customer is redirected to the IR login page. The customer then logs into IR and will be presented with a request to accept the scopes (in this case Accept READ) for MyAccountantWebsite access.
Figure 31: Stage 4 client registration
View larger image (PNG 285KB)
9.1.5. Stage 5 client registration — Provide an authentication code
Figure 32 illustrates that with the customer’s acceptance of the scope, the authorisation server sends an authorisation code to the client application (with the same state parameter for the client to validate).
Figure 32: Stage 5 client registration
View larger image (PNG 286KB)
9.1.6. Stage 6 client registration — Authorisation code is sent to token endpoint
Figure 33 illustrates that to gain access to API resources, the client application sends the authorisation code to the token endpoint (T) on the authorisation server, along with the client ID and client secret it received when the client application was registered. This is used for authentication of the client application to the authorisation server.
Note: The communication must be over TLS.
Figure 33: Stage 6 client registration
View larger image (PNG 288KB)
9.1.7. Stage 7 client registration — The access token it provides
As illustrated in figure 34, the authorisation server provides an access token back to the client application, along with a refresh token (for later use) and an expiry time for the access token.
Figure 34: Stage 7 client registration
9.1.8. Stage 8 client registration — The client application uses the access token to access the resource
As illustrated in figure 35, the client application presents the access token to the resource server at IR, which is verified by the authorisation server and the requested data is returned from the IR backend system via the view IR return API to the MyAccountantWebsite client application.
Figure 35: Stage 8 client registration
View larger image (PNG 294KB)
This completes the OAuth scenario as the client application has retrieved, and can use, the resource data returned from the API.
10. Appendix E — Authorisation
To implement Attribute-based Access Control (ABAC), the current models defined use XACML.
XACML (developed by OASIS) provides a reference architecture, a request / response protocol and a policy language.
It is a highly distributed and loosely coupled architecture. It provides very useful generic definitions of the required components (services) that can be used to define any access control model.
It uses the following services to define the reference architecture:
Policy Enforcement Point (PEP) — where the request to the resource is intercepted and policy applied (based on the decision made by the Policy Decision Point)
Policy Decision Point (PDP) — this is the policy server to which the PEP sends the request for evaluation as to whether a user should or should not have access to a resource. The PDP has access to policy and can match the credentials and request against policy to make a permit / deny decision. It can also enforce policy-related obligations, for example, enhanced logging, notification and alerts, or re-routing to request additional authorisation process
Policy Administration Point (PAP) — the interface where the policies are developed and defined
Policy Information Point (PIP) — used to gather additional information about a user from identity stores or databases to provide additional attributes that are required by the PDP to validate the policy and apply the required outcome.
The links and flows between these services are detailed in figure 36.
Figure 36: XACML reference architecture
Figure 36 illustrates the services in an eXtensible Access control Markup Language (XACML) reference architecture.
It shows a user requesting a resource. The request is intercepted and policy is applied at the Policy Enforcement Point (PEP). The PEP requests an evaluation about whether or not the user can access the resource from the Policy Decision Point (PDP), which is also the Policy Administration Point (PAP) where policies are developed and accessed by an administrator.
The PDP / PAP requests more information about the user from a Policy Information Point (PIP) — this point gathers information from Lightweight Directory Access Protocol (LDAP) and Active Directory (AD) directories and databases.
View larger image (PNG 32KB)
XACML is generally perceived as being difficult to write policies in, but this is being addressed in 2 ways:
OASIS is developing a request / response interface based on JSON and HTTP for XACML 3.0, version 1.0
there is a JSON-based language called ALFA (Abbreviated Language for Authorization) that can be used to build XACML policies.
For XACML to support fine-grained access for APIs it requires a model such as illustrated in figure 37 (based on the scenario in Appendix D).
Figure 37: ABAC support for APIs
View larger image (PNG 38KB)
Figure 37 shows the following steps:
The access token is obtained during the request and exchange process.
The access token is presented during the resource request to the PEP, which also exposes the resource.
The access request is passed to the authorisation server.
The authorisation server verifies the access token and passes a XACML request to the PDP. This is where additional fine-grained access can be applied.
The PDP authorises the PEP to allow access to the backend service.
11. Appendix F — Security controls
Appendix F captures a number of key security controls that should be applied. It is recommended that organisations should apply the relevant RFC (or active draft documents) that relate to securing APIs.
11.1. Communications security (confidentiality) — Required
All communications to or from an API must be over TLS 1.3 or higher. Other versions of TLS and Secure Sockets Layer (SSL) should be disabled. This provides a recognised level of confidentiality that covers all communications between all components.
The consuming application must validate the TLS certificate chain when making requests to protected resources, including checking the Certificate Revocation List (CRL).
11.2. State (integrity)
State is also a parameter that can be used during the authorisation grant stage to provide a level of security to address possible man-in-the-middle attacks.
The state parameter is a string of random letters and numbers that is sent to the authorisation server by the client when requesting an authorisation code. It is sent back to the client with the authorisation code and should be verified by the client application to confirm the authenticity of the response — that it came from the authorisation server to which the request was sent.
Note: State is used to provide a level of integrity when using the standard format of bearer tokens. The confidence in the level of integrity can be increased if JWT tokens are used for bearer tokens.
11.3. Content encryption (confidentiality)
Use encryption if content needs only to be visible to specific consumer endpoints. However, if content only needs to be guaranteed untampered and / or from a specific source (for example, provider) then use content signing.
Content encryption enables all or part of a JavaScript Object Notation (JSON) payload to be readable only by the target consumer(s). This is useful where the content being carried by the API is sensitive, and the API request or response transits multiple stopping points. While TLS protects the payload in transit, it only applies to each point to point connection between components (for example, mobile app to API gateway). If transit components are not totally under the provider’s control, it can be worthwhile performing body encryption. It may be sensible to encrypt credit card details passed between consumer and provider backend systems.
It is also worth considering how much protection the information needs while at rest (for example, information received from consuming applications, caches) and whether some content should be stored encrypted.
Encryption is only worthwhile implementing when data sensitivity or data protection requirements drive it, as encryption is computationally intensive. It also makes it more difficult for protection mechanisms, such as API gateways, to validate and transform API content. When only the integrity of the content passed needs to be ensured, consider using content signing instead.
There are many existing ways of encrypting message content, built into code libraries and development tools. It is required that any content encryption adheres to the standard algorithms laid out in the New Zealand Information Security Manual (NZISM) (Hash-based Message Authentication Code (HMAC)algorithms).
11.4. Content signing (integrity)
Content signing is used to assure content integrity and proof of authorship. It can apply to the whole body of the JSON message or specific elements of that content, for example, credit card details. There are many approaches to content signing and the most appropriate approach is requirements dependent. Standard signing algorithms exist within coding libraries, and JWT has a body that can contain verifiable (signed) JSON fields. API gateways can also be configured to sign content objects in transit, if provided with an appropriate private key.
Signing has less of a computational overhead than encryption, but can still affect performance, so it is advisable that it be used only when and where needed.
For APIs, this is a developing area: there are 2 standards currently under development to address content signing:
Message Authentication Code — OAuth 2.0 Message Authentication Code (MAC) tokens (draft)
Proof of Possession — OAuth 2.0 Proof-of-Possession (PoP) Security Architecture (draft).
It is recommended that where bearer tokens are used, they should be signed using JSON Web Tokens (JWT) as defined in:
JSON Web Token (JWT) RFC 7519
JSON Web Signature (JWS) RFC 7515
JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants RFC 7523.
11.5. Non-repudiation (integrity)
Non-repudiation covers the means to ensure that a consumer cannot deny making a request and, similarly, a provider cannot claim they did not send a response. To aid non-repudiation for APIs, it is important to ensure credentials are not shared between consumers and to perform comprehensive logging of API request / responses.
Digital signatures are useful for not just guaranteeing authenticity and integrity, but also supporting non-repudiation.
11.6. Availability and threat protection
Table 5 lists threat risk types and some recommended approaches to help mitigate these.
Table 5: Threat risks and mitigations
Mitigation (OWASP)
Exposure of inappropriate API methods to access services.
* Protect and limit (allow list) the HTTP methods (GET, PUT, and so on) exposed.
* Validate method(s) for session token / API key.
Denial of Service (DoS) attacks
* Throttle access to all exposed APIs.
* Monitor use to indicate possible DoS attacks.
Malicious input, injection attacks and fuzzing
* Validate input secure parsing and strong typing.
* Validate incoming content-type application / JSON.
* Validate JSON content.
* Validate XML (schema and format).
* Scan attachments.
* Produce valid HTTP return code.
* Validate response type.
Use tokens with state and nonce parameters.
Cross-site scripting attacks
11.7. Token threat mitigation
Securing OAuth flows relies on the exchange of tokens between consuming applications and API backend servers. There is always the threat of these tokens being obtained illicitly, losing confidentiality and integrity of message content, or the integrity of the sender of the token. This risk also applies to the transferring of API keys.
Table 6 captures the main token threats and possible mitigation strategies.
Table 6: Token threat mitigation
Token manufacture or modification — fake tokens and man-in-the-middle attacks)
Digital signing of tokens like JWS with JWT, or attaching a Message Authentication Code (MAC).
Token disclosure — man-in-the-middle attack — the access token is passed in clear text with no hashing, signing or encryption
* Communication security.
* Use TLS 1.3 with a cipher suite that includes DHE or ECDHE.
* The client application must validate:
* the TLS certificate chain
* check the certificate revocation list stored locally in a file or LDAP server.
Token redirects
* Ensure the authentication and resource servers are ‘paired’, and the access token can only be used in this between the specified servers.
* Using the ‘audience’ header (defined currently in a draft RFC) the client application, resource server and authorisation server can help ensure that the token can only be used on the resource servers requested by the client and recognised by the authorisation server.
* Also addressed with ‘state’ parameter in the header.
Token replay — where the threat actor copies an existing token (for example, refresh token or authorisation code) and reuses it on their own request
* Limit lifetime of the token (for example, 10 minutes) — turning it into a short-lived issue.
* Use signed requests along with nonce and timestamps.
* Validate TLS certificate chain when accessing resource server.
API gateway capabilities can protect against many typical API vulnerabilities and threats. Typically, these relate to:
message analysis to block HTTP attacks — parameter attacks such as cross-site scripting, SQL injection, command injection and cross-site request forgery
controlling egress of information via the API, aligned to set access permissions / policies.
As well as providing (if required) access control to API functionality.
12. Appendix G — Internet Engineering Task Force (IETF) RFCs relating to OAuth 2.0
Table 7: IETF RFCs relating to OAuth 2.0
RFC number and title
High level description
RFC 6749
The core OAuth 2.0 RFC defining the authorisation framework.
RFC 6750
The OAuth 2.0 Authorization Framework:
Bearer Token Usage
How to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. Any party in possession of a bearer token (a ‘bearer’) can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport.
Note: RFC 8996 deprecates Transport Layer Security (TLS) 1.0 and 1.1 and recommends 1.2 or ideally 1.3 in OAuth 2.0 implementations.
RFC 6755
This document establishes an IETF Uniform Resource Name (URN) Sub-namespace for use with OAuth-related specifications.
RFC 6819
Security considerations for OAuth beyond those in the OAuth 2.0 specification, based on a comprehensive threat model for the OAuth 2.0 protocol.
RFC 7009
Token Revocation
This profile defines a revocation endpoint on the authorisation server to enable clients (consuming applications) to revoke their own access or refresh tokens. This is essential should a token get into the wrong hands and be used for malicious purposes. Before allowing a client to revoke an access token and / or associated refresh tokens, the authorisation server first validates the client’s credentials.
RFC 7519
URL-safe means of representing claims to be transferred between 2 parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and / or encryption.
RFC 7521
Common framework for OAuth 2.0 to interact with other identity systems using an assertion and to provide alternative client authentication mechanisms.
RFC 7522
The use of a Security Assertion Markup Language (SAML) 2.0 Bearer Assertion as a means for requesting an OAuth 2.0 access token as well as for client authentication.
RFC 7523
Use of a JSON Web Token (JWT) Bearer Token as a means for requesting an OAuth 2.0 access token as well as for client authentication.
RFC 7591
Mechanisms for dynamically registering OAuth 2.0 clients with authorisation servers.
RFC 7592
Methods for the management of OAuth 2.0 dynamic client registrations for use cases in which the properties of a registered client may need to be changed during the lifetime of the client.
RFC 7636
OAuth 2.0 public clients utilising the authorisation code grant are susceptible to the authorisation code interception attack. This specification describes the attack as well as a technique to mitigate against the threat through the use of Proof Key for Code Exchange.
RFC 7662
Method for a protected resource to query an OAuth 2.0 authorisation server to determine the active state of an OAuth 2.0 token and to determine meta-information about this token. Provides authorisation context of the token from the authorisation server to the protected resource.
RFC 7800
How to declare in a JWT that the presenter of the JWT possesses a particular proof-of-possession key and how the recipient can cryptographically confirm proof of possession of the key by the presenter.
RFC 8176
Establishing a registry for authentication methods for example:
* retina scan
* facial recognition
* fingerprints
* geolocation information
* proof of possession of a hardware key
* knowledge-based authentication
* multi-channel authentication
* multi-factor authentication
* one-time password
* personal identification number
* password based
* risk based
* SMS confirmation messages
* proof of possession of a software key
* confirm by telephone
* user presence test
* voice biometrics
* Windows integration.
RFC 8252
This RFC recommends external user agents like in-app browser tabs as the only secure and usable choice for OAuth, rather than embedded user agents.
RFC 8414
This defines how an OAuth 2.0 Client can interact with an authorisation server by providing a discovery endpoint that provides the endpoints and authorisation server capability.
RFC 8628
The OAuth 2.0 device authorisation grant is designed for Internet-connected devices that either lack a browser to perform a user agent-based authorisation or are input constrained to the extent that requiring the user to input text in order to authenticate during the authorisation flow is impractical. It enables OAuth clients on such devices like smart TVs, media consoles, digital picture frames and printers, to obtain user authorisation to access protected resources by using a user agent on a separate device.
RFC 8693