Skip to content

Latest commit

 

History

History
253 lines (181 loc) · 24.5 KB

CAMARA-AuthN-AuthZ-Concept.md

File metadata and controls

253 lines (181 loc) · 24.5 KB
Raw

Authentication and Authorization Concept for Service APIs

Table of Contents

  1. Introduction
  2. Difference between Authentication and Authorization
  3. API Gateway pattern
  4. Authentication and Authorization details
    1. OAuth2 with TLS
    2. OIDC
  5. Documentation and Specs
  6. Summary
  7. References

Introduction

APIs are the most popular way of exposing business functions of an enterprise to the outside world and it digitally transforms a business. They are now the tool of choice for accessing data and functionality both inside of and between companies. However, this also comes with the risk of exploitation. API providers cannot assume “well behaved” users. API consumers may use the API to find weak points, overload the platform (DDOS) or may try to use brute force by cracking authentication/authorization.

This cannot be avoided by measures on consumer side. The API providers must be able to handle these scenarios and ensure that the services provided are reliable and secure by following zero trust security guidelines. Hence security with respect to API development cannot be an afterthought and must be part of the process from the very beginning.

Some of the infamous 1 API breaches over the past years show that the kind of authentication(AuthN) & authorization(AuthZ) implemented was not sufficient to prevent these breaches. The ForgeRock 2021 Breach Report reveals that attacks involving usernames and passwords increased a staggering 450% in 2020 from 2019, translating into more than 1 billion compromised records in the U.S. alone.

In this document we will not delve into all aspects of API security but rather focus on the authentication and authorization concept for the Service APIs.

Difference between Authentication and Authorization

Authentication 3 refers to the process of confirming identity. In authentication, a user or an application prove they are, who they say they are, by providing valid credentials for verification. Authorization 2 refers to the process of verifying what a user has access to. While often used interchangeably with authentication, it represents a fundamentally different function. In authorization, a user or application is granted access to an API after the API determines the extent of the permissions that it should assign. Usually, authorization occurs after identity is successfully validated through authentication so that the API has some idea of what sort of access it should grant.

It is also important to reflect on a step before authentication (step 0) - onboarding. This is also referred to commonly as partner/consumer onboarding.

User identity

On what refers to CAMARA APIs to be exposed by Telco operators, the End user is the human participant who uses the application from a consumption device. And the User is the client/subscriber of the telco operator, identified by a unique user identifier (e.g. subject identifier sub in OpenID Connect terminology). The user is the resource owner. Usually the user corresponds to the end user, but this is not always the case. For example, a parent may be the user of a mobile subscription for their children. Therefore, the Authentication process allows to confirm/validate user identity (i.e. the operator subscriber).

It is important to differentiate the identification of a user from the identification of a device or UE. For example, the same user could have multiple associated devices. This means that multiple identifiers may correspond to a unique user.

API Gateway pattern

An API implementation typically includes the business logic of the offered service. If the API includes all the security and exposure specific logic into an API, it will end up making the implementation too complex. The API gateway resides between the backend service (resource service) and the API consumer and it intercept all the requests from the consumer to the service. The API Management system integrates with an identity and access management system to ensure that all users accessing the system are authenticated and authorized to use the platform.

This pattern (together with an API management system) has other advantages:

  • Helps to hide the complexity and diversity of your internal architectures
  • Provides one stop place for API discovery
  • Enables organization level policy enforcement and protects the backend services
  • Accelerates API adoption rate
  • Improves partner/developer onboarding timelines with self service capabilities

APIM

Authentication and Authorization details

Basic Authentication was the first web authentication scheme (specification first published in 1999, see RFC7617 for the updated version). While its simplicity is an advantage (the browser handles the client-side logon), it has security downsides - password is sent in the request headers (in base64 encoding) for every request and can be cached/stored by the browser.

Some APIs use API keys for authorization. An API key is a token that a client provides when making API calls. The key can be sent in the query string, as a request header or as a cookie.

These simplistic methods cannot protect the API against today's sophisticated security attacks by bad actors.

There are several limitations to these methods:

  • The username password at least needs to be shared between 2 parties.
  • The stolen passwords and keys can be exploited by the attacker for significantly long period of time before it gets noticed
  • API keys might have no expiry
  • Since API keys and passwords are part of the requests, they could be prone to man in the middle attacks

To address these vulnerabilities, the OAuth standard was introduced.

OAuth2 with TLS

OAuth2 (RFC6749) is the industry-standard protocol framework for authorization (also known as an access delegation protocol). Over the years it has become the most popular authorization mechanism for APIs. (Any reference to OAuth in this document should be understood as OAuth2). The long list of providers is a testament to its widespread acceptance in the industry. OAuth2 relies on authentication scenarios called flows (or grant types), which allow the resource owner to share the protected content at the resource server without sharing their credentials. OAuth2 is not about authentication but rather about delegation.The OAuth2 server issues access token which are used by the client applications to access protected resources on behalf of the resource owner. The protected resources need not know who the client application is but rather what permissions it has been delegated. The protected resource can validate this at its end.

OAuth2 access tokens are issued to allow limited access to specific resources for a specified period of time and may be revoked by the user that granted permission, or by the server that issued the token. OAuth2 provides several flows suitable for different types of API clients. It mandates use of encryption (TLS ) to protect confidential resources. Though not explicitly specified, TLS is expected to be used for all API traffic.

Roles defined by OAuth2

  • Resource owner: An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user.
  • Resource server: The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.
  • Client: An application making protected resource requests on behalf of the resource owner and with its authorization. The term "client" does not imply any particular implementation characteristics (e.g., whether the application executes on a server, a desktop, or other devices).
  • Authorization server: The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

Client Types defined by OAuth2

OAuth2 defines two client types, based on their ability to authenticate securely with the authorization server (i.e., ability to maintain the confidentiality of their client credentials):

  • Confidential: Clients capable of maintaining the confidentiality of their credentials (e.g., client implemented on a secure server with restricted access to the client credentials), or capable of secure client authentication using other means.
  • Public: Clients incapable of maintaining the confidentiality of their credentials (e.g., clients executing on the device used by the resource owner, such as an installed native application or a web browser-based application), and incapable of secure client authentication via any other means.

Access tokens, ID tokens and refresh tokens

  • Access Tokens: An access token represents the delegated permissions that the resource owner (the user) has given the client application. An access token could contain information about the user who delegated permission, but it does not actually represent the user. An access token also does not represent or give any indication of a user having authenticated. Access tokens should be signed and encoded as JWT (Json Web Token), with the bearer type specified. As access token is intended for a protected resource, the protected resource should be responsible for understanding and validating the token.
  • ID Tokens: An ID token contains the identity of the resource owner. It describes the authentication event that took place at the identity provider. It contains information such as how and when the user last authenticated. It is always signed and encoded as a JWT.
  • Refresh tokens: A refresh token is used to reauthorize the granted access by allowing the client application to obtain an access token without the user credentials. The refresh token would be used when the previous access token expires and is no longer valid. An access token generally has a short lifespan to limit the damage that can be done if it were compromised. A refresh token helps improve the experience of the API consumers by not asking them for credentials on a too frequent basis. Protocol Flow

Please note that the ID token mentioned above is not a part of Oauth2 specification. It is defined in the OpenID connect (OIDC) specification described later in the document.

Token Validations: Token introspection is elaborated in detail in RFC7662. Below are listed the standard checks that must be part of token validations:

  • Signature of the token
  • Expiry of the token (exp_claim)
  • Issuer recognized as a trusted issuer (iss_claim)
  • Consumer whitelisted in ACL list (azp_claim)

For ID token, audience, time of token issue, nonce etc. should be included as a part of the validations. If any of the validation steps fail, the request must be denied with an appropriate error message.

Protocol Flow : An abstract protocol flow for OAuth2 is illustrated below:

Oauth2

Relevant Authorization grants

An authorization grant is a credential representing the resource owner's authorization (to access its protected resources) used by the client to obtain an access token. Out of the grants defined under OAuth2 we recommend:

  • Client Credentials grant: (when user resource is NOT involved & the client belongs to confidential category)
  • Authorization Code grant: (when user resource is involved)

Extensions

  • Token exchange grant: (RFC8693) It is used when multiple participants are involved with impersonation (using subject_token) or/and delegation (actor_token) requirements and the existing grant options limit possible inputs/outputs
  • Device code grant: (RFC8628) It is used when two separate devices are involved, one asking for authorization, and the other device on which authorization is actually granted but it is input constrained The implicit and password grant types are other options specified by OAuth2 when user resource is involved but they are already considered legacy.
  • Bearer JWT grant (jwt-bearer): (RFC7523) It is used to request an access token when a client wishes to utilize an existing trust relationship, expressed through the semantics of the JWT, without a direct user-approval step at the authorization server. It uses the "Assertion Framework for OAuth 2.0" (RFC7521) to define assertions (JWT) as authorization grants with OAuth 2.0.

Client Credential Grant

The client credential grant is used for server to server use cases involving trusted partners or clients without any protected user data involved. In this method the API invoker client is registered as a confidential client with an authorization grant type of client_credentials.

cc

OIDC

As already mentioned earlier OAuth2 is not authentication. OpenID Connect 1.0 (OIDC) is a standard from the OpenID Foundation that extends the OAuth2 protocol with a simple identity layer on top. It allows both protocols to work together, providing both Single Sign-On (SSO) and authorization to access APIs on the user’s behalf. OpenID Connect achieves this using identity tokens, and a new API - user info endpoint.

It enables Clients to verify the identity of the End-User based on the authentication performed by an OpenID provider, as well as to obtain a basic profile information about the End-User in an interoperable and REST-like manner. OIDC defines a sign-in flow that enables a client application to authenticate a user, and to obtain information (or "claims") about that user, such as the username, email, and so on. User identity information is encoded in an ID token.

OIDC

OIDC provides a framework for identity providers to support a wide range of authentication methods/factors that can be used to verify the identity of the user:

  • Username and Password: The user provides the client application with a username and password. The client application then sends the username and password to the identity provider, which verifies the user's identity and returns an ID token to the client application.
  • SMS One-Time Password (OTP): The user provides the client application with a phone number. The client application then sends the phone number to the identity provider, which sends an SMS message to the user's phone number. The user enters the code from the SMS message into the client application, which sends the code to the identity provider. The identity provider verifies the code and returns an ID token to the client application.
  • Network-based authentication: An authentication mechanism based on the identification of the endpoint of a network connection (e.g., by the observed IP address of the user device connected to the network). Network operators know which user is associated with a network resource at any given time, such as the mobile phone number associated with a particular cellular connection.
    This is particularly interesting in the context of CAMARA APIs exposed by network operators. For example, it is the authentication method defined for the Number Verification API without any user interaction in the process (aka "silent" auth).
  • Multi-factor authentication (MFA): MFA combines two or more authentication factors to increase security. For example, a combination of a password and a push notification to a registered mobile device. MFA is often used to provide an extra layer of security for sensitive applications such as banking.

In fact, there are many more authentication methods/factors that can be used with OIDC, which can have different levels of security based on the factors they rely on to verify a user's identity (e.g., biometrics, hardware security keys, social identity providers such as Google, Facebook, etc.).

Authorization code grant

The authorization code is a temporary code that the client will exchange for an access token. The code is obtained from the authorization server. The user gets to know about the information requested by the client and can then approve or deny the request. The application requesting for the access token must supplement the request with the client secret. This reduces the risk that the authorization code can be exploited if intercepted by a bad actor.

AC

PKCE (security related Oauth2 extension)

Proof Key for Code Exchange (PKCE is specified in RFC 7636) is an extension to the authorization code flow to prevent Cross Site Request Forgery (CSRF) and authorization code injection attacks. This extension utilizes a dynamically created cryptographically random key called "code verifier". A unique code verifier is created for every authorization request, and its transformed value, called "code challenge", is sent to the authorization server to obtain the authorization code. The authorization code obtained is then sent to the token endpoint with the "code verifier", and the server compares it with the previously received request code so that it can perform the proof of possession of the "code verifier" by the client. This works as the mitigation since the attacker would not know this one-time key, since it is sent over TLS and cannot be intercepted.

OIDC Client-Initiated Backchannel Authentication (CIBA) flow

CIBA 10 is an authentication flow like regular OpenID Connect. However, unlike OpenID Connect, there is direct Relying Party to OpenID Provider communication without redirects through the user's browser. It decouples the concept of a Consumption Device (on which the user interacts with the Relying Party) and an Authentication Device (on which the user authenticates with the OpenID Provider and authorizes the request). CIBA allows a Relying Party that has an identifier for a user to obtain tokens from the OpenID Provider. The user starts the flow with the Relying Party at the Consumption Device, but authenticates and authorizes request on the Authentication Device. Authentication could even be initiated without user action on the consumption device. As the end user does not provide authentication credentials directly to the consumption device, supporting this flow requires the OpenID Provider to have some mechanism of initiating user authentication out-of-band from the interaction with the consumption device.

Documentation and Specs

Several developer surveys explain how important API documentation is to the success of an API. These surveys also highlight that missing or unclear documentation on authentication and authorization for an API can deter most consumers/developers to get started with the API. The API documentation template contributed within Camara alliance has already added the authentication section as mandatory to highlight its importance.

The Camara APIs specs are contributed in OAS3 format 9. This specification format natively supports specifying security schemes based on OAuth2 and OIDC which allows a standard way for Camara API contributors to define the scheme supported by their APIs.

The YAML OAS3 specification uses the securitySchemes and security keywords for describing security properties. SecuritySchemes are used to define all security schemes the API supports, and security is used to apply specific schemes to the whole API or individual operations. All security schemes used by the API must be defined in the global components/securiySchemes section.

The following example shows how OpenID Connect security schemes are defined:

openapi: 3.0.0
(...)
# Define the security scheme type and attributes
components:
  securitySchemes:
    openId:   # <--- Arbitrary name for the security scheme. Used to refer to it from elsewhere.
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
# Apply security globally to all operations
security:
  - openId:   # <--- Use the same name as specified in securitySchemes
      - t_read
      - t_write
      - admin

The security section then applies the chosen security scheme to your API. The actual scopes required for API calls need to be listed here. These may be a subset of the scopes returned by the discovery endpoint. If different API operations require different scopes, security can be applied on the operation level instead of globally. This way relevant scopes for each operation can be listed:

    paths:
      /sessions/{sessionId}:
        get:
          summary: `Get session information`
          security:
            - openId:
              - t_read
          ...
        delete:
          summary: `Free  resources  related  to  QoS  session`
          security:
            - openId:
              - t_write
          ...

Summary

Security and reliability rank very high in an API world. The complexity of modern systems make it a must to integrate these aspects into the products from their inception. As mentioned earlier, these dimensions cannot be designed into the system as an afterthought. AuthN and AuthZ are two most prominant building blocks when designing a secure and reliable system. It is therefore critical to use industry tested and adopted frameworks when implementing these concepts. Depending on the Service API use cases, we expect the APIs contributed to the Camara project use the above specified means of authentication and authorization frameworks to support interoperability and to offer a reliable and secure experience to our Camara API consumers.

References

Open guides and specifications

1 https://auth0.com/docs/authentication "Authentication"
2 https://auth0.com/docs/authorization "Authorization"
3 https://swagger.io/docs/specification/authentication/ "Security schemes (Swagger OpenAPI Guide)"
4 https://oauth.net/articles/authentication/ "OAuth authentication"
5 https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securitySchemeObject "Security Scheme Object"
6 https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityRequirementObject "Security Requirement Object"
7 https://openid.net/specs/openid-connect-core-1_0.html "OpenID Connect Specification"
8 https://openid.net/specs/openid-connect-discovery-1_0.html "OIDC Discovery Specification"
9 https://spec.openapis.org/oas/v3.1.0 "OAS3" 10 https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html "CIBA"

RFCs