API Designer

API stands for Application Design Interface

An API is a Software interface, a building block that works behind the scenes to connect
different applications and systems so they can share information.

Benefits of API usage:

• New Revenue – Not very common

• Reach of retention of clients – More common. Facilitate the reach of customers
o NPR & eBAY are good examples
• Faster Partnerships – Fast integration to partners
o Green Button Alliance → provides standard ways to use customer data
• Mobile and Omnichannel
o Linked to reach and retention
o Consistent access
• Interaction Analysis → Provides feedback regarding how users are using the services
• Outsourced Innovation → Public shared APIs. Allows anyone to use the API and can
allow mor innovations
• Self-Service Integration
• Organization Agility → Maximize delivery services

APIs needs to be aligned with business strategy, goals and audience

Lifecycle of APIs include: creation, deployment, promotion, optimization, discovery, acquisition

and consumption

Provisioning: Enterprises are responsible for a continuous sequence of API strategy, design,
creation, orchestration, protection, testing, deployment, promotion, and monitoring.
Continuous API management enables each of these steps with functionality that also addresses
security, scalability, and manageability concerns.

Key metrics and goals are:

• API deliverable roadmap and cross project reference

 • Easy of usage
• Define the target users of the APIs
• Identify the developers that can attract users and clients to the API
• How to retain the users, clients and developers
• How to continually enhance DX (Developer experience) for the API
• What tools are needed to be provided for the developer community to assist with the
API
• Easy to track and manage the API calls

Scalability and evolution should do:

• Anticipate possible changes to the business

• Provide multiple perspectives from API stakeholders
• Define appropriate constrains

There should not be:

• Obsess for standards

• Care exclusively about tech
• Favor models over reality

Key questions:

• What operational metrics are needed for the API?

• What business metrics are needed for the API?
• How to use these metrics to increase agility?
• How to control API access without adding new barriers?
• Who are the individuals involved and how to protect API?
• What are the API threats? Three main vectors:
o Parameters: Exploit data sent into API. Like SQL Injection
o Identity: Abuse of authentication, authorization and session.
o MITM
• Key security practices:
o Validate parameters: Validate incoming data against a schema
▪ Business schema tools use market broad options that might not be
effective for the risk scenario
o Threat Detection: Antivirus for files, scan loaded scripts, decode base64
o Turn on SSL/TLS and when need, deploy client side certificate
o Deploy user and app identity management
o Preference for OAuth usage
o Separate API implementation and API security in TIERS
o Deploy API Gateway to control and validate traffic
• Open ID Connect
• FIDO

Requirements for API minimum security

• Analytics and monitoring

• Identity and Security model
• Infrastructure and Operations
 • Management platform

API Styles:

• Tunnel Style (SOAP – Simple Object Access Protocol): Tunnel APIs on calling functions
o Created in 2001 and tight to HTTP
o Uses WSDL
o Focus on function/Methods
o Build components (DLL, etc)
o Publish WSDL
o Code generate proxy class via WSDL
o Use proxy class in client
o Much used for legacy

• URI (CRUD – Create Read Update Delete): Simple way to invoke requests. It can be an
open door for hacking.
o Created in 1995
o Focus on Objectives/Entities
o Design public identifiers
o Design query rules
o Use HTTP as operations

• Hypermedia (REST – Representational Sate Transfer): Similar to URI but used rich
content types, hyperlinks, etc. to create interactions focused on tasks and not on objects
o Created in 2001
 • Event Driven/Reactive: Includes Websocket. Transmit data between a client and server
with low overhead.
o Emphasis on event notification
o Asynchronous

• GraphQL: Allows clients to explicitly tell the API how to present the data without the
need to create a large collection of requests and responses
o Created by Facebook
• gRPC: language agnostic that require client and server to agree on the payload.
o Created by google

API Peter Morville Honeycomb objectives

Layered Architecture Style

• Security layer
• Caching Layer
• Representation Layer
• Orchestration Layer

Basic API Design Approach

• Determine Goals
• Identify Users
• Design Interface
• Evaluate
• Implement

Terms:

• URI: Uniform Resource Identifier

• URN: Uniform Resource Name (USERNAME)
API SECURITY
APIs by nature are more transparent than web services, making the structure more vulnerable
if API security features are not deployed.

API can be of 3 basic types:

• Private ➔ Used only internally

• Public ➔ Focus on external developers
• Partner ➔ Hybrid

Attack surface is in any stage that interacts with the API

Cross-site scripting:

• Loads malicious scripts into trusted websites to send users via the site
• Usually via browsing side scrip

Denail of Service:

• Makes resources unavailable

MITM:

• Intercepts communications between two systems

Cross-site Request Forgery

• Forces the users to execute unwanted actions on a WEB app that the user is
authenticated

Injection

• Loads queries via interaction fields

Overflow

• Overwrite memory fragments

Mitigating API Threats

• Rate Limiting
o Prevent DoS
o Restrict number of requests based on IP, Identity and resouce
• Message Validation
o Prevent Injection
o Validates incoming and outgoing messages
o Schema validation can be performed after message is received
• Encryption & Signing
o Prevents Spoof and MITM
o Can be performed at transport level via TLS and/or message level via XML-
signature
• Access Control
o Restricts usage of APIs based on user identity
o Makes authentication and authorization

SAML is old and basic secure

OAuth and Open ID provides more granularity of control to enable delegate authorization and
identity token management
Basic authentication the user and password are in request reader

Digest authentication Password can be encrypted, but server can downgrade to basic

OAuth 2.0
Industry standard authorization protocol that permits a user to grant an application access to a
protected resource without exposing the user`s password.

An OAuth access token is issued and accepted for user authorization at the API endpoint.

Puts the user in control in delegating access to applications

OAuth2.0 Authorization Flow – Authorization Code

During the registration of an APP into an API, is important to define a Scope of authorized
actions.
Authorization Server can be internal or external, Like google, facebook, Linkdin, etc.

Authorization flow has a set of sets described below:

1- User logs into the application

2- Application sends a request to the Authorization Server
3- Authorization Server asks user to authorize the request
4- User authorizes the app
5- Authorization server grants authorization code to App
a. Authorization alone is not enough for the app to get the resources
b. The App than exchanges with the Authorization Server to gain an Access token
c. The access token contains the scope of what can be accessed
d. Defining the scope within the Access Token, limits the access
e. The scope also limits what can be done with the resource access
6- App sends the token to the Resource server to gain access to the resource
7- Resource server provides the access as defined in the scope of the token

In no step of the process, a user credential is exposed to the resource server

Credentials are kept between the Authorization Server and Resource owner (client)

OAuth is NOT an authentication protocol

OAuth2 can be used to login into external partners like google or facebook, but it CANNOT
be considered as an authentication protocol. They are delegated for login only.

OAuth 2.0 supports 4 grants types of authorization:

• Authorization Code
o Used for Web Apps or app with a scope access defined to a resource on
behalf of an end user whose identity must remain private
o For this to work, the client exchanges the authorization code for a token
o Implementation is complex and needs upfront research and business cases
• Implicit
o Instead of issuing an authorization code for a token, the client app has a
predefined token
o The authorization server does not authenticate the client
o It is optimized for Java Scripts applications
o Recommended for internal applications
 o Not recommended for external apps
• Resource Owner Password Credentials
o To be used ONLY when there is a high degree of trust between the
resource owner and the client application
o Recommended to be used only when all other options are not available
o Weakest option against hackers
o Credentials are provided only once
• Client Credentials
o Used when client is working on its own behalf
o Use cases are applications that does not require interactions with the end
user
o Best for Daemon, command line interactions and IOTs

Best used with repeatable deployment tools for APIs with OAuth2.0 Too complex to make it
isolated.

OAuth 2.0 is a framework

Tokens can contain authentication detail, but it is not defined and not required.

Authentication, in best scenario, is set with Open ID Connect

Also the framework does not specifies how:

1- Resource and authorization server interact

2- How clients register with authorization server
3- How authorizations endpoints are discovered
4- How the scope is defined

If requirement is mandatory to control API access, OAuth 2.0 is the best option

Standalone usage of OAuth 2.0 causes problems:

• Not possible to authenticate the bearer of the token

• Token does not contain user information
• Trust is assumed for anyone with the token

Solution is to have OpenID Connect since it applies OAuth to an identity resource, identity is a
set of attributes. With this, one person can have multiples identities.
An ID Token will be generated in addition to the access (authorization) token, and acts like an
encrypted fingerprint.

The authentication process validates messages that are also called “CLAIMS”. Additional
information can also be used can also be requested by the scope.

Open ID CONNECT has a variety of claims, named as Profile parameters.

Every new request of an authenticated user can be validated by a userinfo endpoint within the
Authorization server. If the information cannot be validated, the request resource will not be
able to be fully delivered.

OAuth 2.0 Threats

Threat models are separated in groups for Client and endpoint.

RFC 6819 contains threat model considerations.

Best practices are:

• RFC 7469: Public Key Pinning Extension for HTTP

• RFC 7591: OAuth 2.0 Dynamic Client Registration Protocol
• RFC 8414: OAuth 2.0 Authorization Server Metadata
• RFC 7662 and 7009: Token Introspection, Token Revocation
• RFC 8693: OAuth 2.0 Token Exchange
• RFC 8471: Token biding Protocol
• RFC 8473: Token biding over HTTP
• RFC 7800: Proof-of-possession key semantics for JWT
• ID 13 – OAuth 2.0 Security Current Best Practice

Client Threat Model

• Attacker obtaining Client Secrets

o Mobile and IOT usually has no secret, and the token can be easily analyzed
o APP key and app secret are expose
• Attacker obtaining access and refresh tokens
• Attacker phishing for credentials using compromised or embedded browser
• Open redirect on a client

Best action is to apply Access Control.

In traditional app, credential are stored in client side. They are usually stored in the web
message and are visible to the browser and can be decompiled.

Access control for API is to keep the credential always on the server side (Authorization and
resource), implement monitoring and detection and establish credentials during client hand
shake and registration

Endpoint (server) Treat Model

• Phishing by faking authorization server

• MITM to the resource server
• User giving too much access scope
• Malicious clients obtain existing authorization by fraud
 • Open redirection

Best action is to apply certificate pinning (RFC 7469), Whitelist Redirect URI, Proof Key for Code
Exchange - PKCE (RFC 7636). Is a key line of defense to prevent hijacking a server.

1- Client needs to generate a secret that works as a code verifier

2- Client sends an authorization code request with a hashed secret and a hashing method
3- Client request access token with the code_verifier.
4- Server validate the code_verifier using code_challenge

Token Threat Model

• Eavesdropping access token

• Obtaining access token from authorization database server
• Disclosure of client credentials during transmissions
• Obtaining client secret from authorization database server
• Obtaining client secret by online guessing

Best action is Token Biding (RFC 8471, 8473, 7800)

OpenID Connect
OpenID connect flow is based on the OAuth2.0 authorization flow. It uses similar components
such as resource owner (end User), Client App, Authorization server and resource server.

The main difference is that in addition to the access token, the ID token is issued and used in
the authentication flow for the client app to retrieve resources on behalf of the resource
owner.

The Open ID protocol suite is divided in the following implementation levels:

• Minimal

• Dynamic

Gets details about location of the OpenID provider, also know as a discovery request.

Can dynamically register with the end user

 • Complete

Contains session management specification and get/post

When to log off the users

JSON WEB TOKEN (JWT)

JWT is used to secure transmit information between parties. It is part of Javascript Object
Signing and Encryption that also contains:

• JWT (JSON Web Token)

• JWS (JSON Web Signature)
• JWE (JSON Web Encryption)
• JWA (JSON Web Algorithms)
• JWK (JSON Web Key)

JWT has a header that specifies authorization and signatures, the payload that specifies
standard and custom claims and signature that elaborates the mechanism used to sign the
JWT.

JWT has some features that are promoting its usage. These are:

• Support for signature and encryption

 • Stateless and self-contained
• Compact and easily passed around
• Agnostic to program language
• Ideal for REST/HTTP APIs

Key benefits are that it works based on claims and provide authentication and authorization. It
can be portable to be used anywhere and can be stored in the client. It provides message level
encryption and signing.

It also is good because it has small size and is simple do deploy.

But JWT has issues and problems. Mains are the difficulty to revoke a token and its
management, the security of the token and overhead and performance.

JavaScript Object Signing and Encryption (JOSE)

1- Job is signed it verifies the integrity of the claims contained within the JWT
2- Encryption is set and will hide all the claims from parties not set in the token
a. After encrypted, the token becomes a payload of the JWE object
b. Encryption is set using PKI structure
3- Object is signed with the private key of the request server
4- Object is encrypted with the public key of the recipient or with a shared secret
5- Uses the defined algorithm for effective encryption

To open the Token, the process runs backwards:

1- The message is decrypted using the authorization server private key or the stablished
secret key
2- The extracted payload is passed as a signed job and verified against the requester
public key

The header of JWT identifies the algorithm in use.

The payload contains tokens information and claims

The signature presents the encoded signature presents on the header

A JTI (JSON Token Identifier) can be used to avoid for been replay.

A refresh token can be set to revalidate the original token. It can be set with a limit of times it
can be executed and with a time limit for the access token to be used.

JWT vs SAML
JWT is simetrical signed using HMAC

SMAL 2.0 and 1.1 is more complex and is relies in PKI only

JWT has a much less verbosity, making it better for HTTPS signing apps than SAML

In Stateful condition, the server must maintain apps state to support it when tokens are in use
and with SAML. Using JWT state of the application is not needed. The resource server validates
the client token against it private key.

JWT benefits and problems

• Signed and encrypted
o Message is signed and encrypted
o Not possible to assure user log in/log off
▪ Option is to change the secret to force token not been able to be used
• To use this approach is maybe best to use stateful options
• Stateless
o Good for apps bur can cause problem for security
o Been stateless make it difficult for revocation
▪ Work around is to set a short timeout
▪ Limit token refresh
• Self-contained
o Since the signing key is listed in the token, if one is copied from a client, it
could be used to attempt the creation of a false token
• Compact
o Don’t let the Header alone drive verification.
o Use an adequate key size
o Enforce the need of algorithm
• Easily passed around
o Use custom claims to make it difficult to impersonate
o
• Protocol versatility
• Language agnostic
• Common data format
• Ideal for REST/HTTP APIs