Amplify API Management Keys and OAuth

Understand your API security need: OAuth or OpenID Connect?

Understand your API security need: OAuth or OpenID Connect?

OAuth and OpenID Connect are two common topics on API security space. However, there is still confusion usage of these protocols on the internet. I have seen large enterprises designed OAuth on their way to fulfill their goals. To secure our applications, we need a good understanding of our tools and what problems it is designed to solve. Some people use OAuth for Authorization, some use for Authorization + Authentication. So, I decided to clear the confusion in this article.

The old way of Delegated Authorization

Let’s talk about the old way of delegated authorization. You will not find many examples of implementation of the Delegation Authorization old way. Have you ever used awardwallet.com? It is an application that helps you track all of your reward program accounts in one place so that easier for you to manage all of your airline’s frequent flyer programs, hotel loyalty programs, etc.

The way it works, you have to provide login credentials of your airline’s frequent flyer accounts and hotel’s loyalty accounts, so that this app can log in to the airline’s system or hotel’s system to get your account details.

Now think about how much security risk you are taking by providing all the credentials to the AwardsWallet. I think it is enormous. Whose fault is this for this poor design? I think the airlines and the hotels haven’t adapted OAuth’s delegated authorization feature yet for their loyalty member/frequent flyer program.

See also: Rethinking API security to meet today’s threats

What is OAuth?

OAuth is an authorization framework that allows a client app(could be third party application) to retrieve information from another system using a token which is valid for a limited time. Now, there could be a case where the application users authorize the client app to retrieve information on their behalf. For example, you (user) are logging into Yelp.com (third party app) using your google account. In this case, OAuth provides a way for delegated authorization which means OAuth provides a way for the client app (Yelp.com) to gain access to a user’s protected resources without asking the user (your) to provide its login credentials to the app.

Authentication vs Authorization

When a connection is successful with client and server, Authentication provides the information about the client, like who the client is? So, in Authentication, the server verifies the client credentials which can be passed in different forms in the HTTP request. If the client failed to authenticate, the server returns HTTP 401 to the client in the response.

Whereas, asking for Authorization details to the Client, you are checking if the Client is authorized to make the API call.  So, in the Authorization check, we verify the client’s access by decoding some kind of token passed in the HTTP request. If client is not authorized to make the API call, server returns HTTP 403 in the response.

It is not necessary you need to check the Authentication of the client before checking the Authorization details. In most cases, only Authorization is check works just fine with REST API.

OAuth Protocol Flow

OAuth or OpenID Connect?

This shows the interaction between the four roles. Now, you might be confused about all the terminologies used in the above diagram. Let’s deep dive into OAuth and describe OAuth terminologies.

See also: Beyond certifications: take a holistic approach to security for API-enabled IT 

OAuth 2.0 terminology

  • Resource Owner: End-user in the process. When you log in to Yelp.com using your google account and you are granting access to yelp to access your basic profile, in this case, “You” are the resource owner. Basically, a resource owner is someone who is capable of granting access to an application on his/her behalf.
  • Client: This is the client app. In the above example, Yelp is the client and the resource owner (“You”) must grant access to the Client(“Yelp”). When Client registers in the developer portal, a client id/secret is issued by the Authorization Server.
  • Authorization Server: The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization. In typical use cases, Octa, Ping or any IDP works as Authorization Server.
  • Resource Server: The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens. This is the server where your APIs( protected resources) are hosted.
  • Authorization Grant: 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. This specification defines four
    grant types; authorization code, implicit, resource owner password credentials, and client credentials. Check out the next table for deep dive into different grant types and their use.
  • Redirect URI: This is the client application’s URI where the Authorization Server will send the authorization code. Sometimes, this called callback URI.
  • Access Token: Access tokens are credentials used to access protected resources. An access token is a string representing an authorization issued to the client. The string is usually opaque to the client. Tokens represent specific scopes and durations of access, granted by the resource owner, and enforced by the resource server and authorization server.

OAuth 2.0 Grant Types and when to use

Grant TypeDescriptionUse cases
Client CredentialsClient requests for the access token by sending its client id/secret to the authorization server and once the access token is issued, the client app uses the access token to make the API call to the protected resources.

OAuth or OpenID Connect?

  • Typically used for B2B use cases.
  • The client app is the resource owner.
  • Typical use cases are intranet app but work with highly trusted internet applications that are written by the internal developer or trusted partner’s application developer.
Authorization codeOAuth or OpenID Connect?
  • Typical use case when untrusted apps are written by third-party developers who do not have a trusted business relationship with the API provider.
  • Requires users log-in to the resource server
  • Client app needs to be registered in the resource server and the client app never gets hold of user login credentials.
ImplicitThis is similar to the Authorization code flow, except the authorization server sends the access token instead of the authorization code directly to the client app after capturing consent from the user.

OAuth or OpenID Connect?

An example is your company website where you will log in and see information related to you.

  • Typical use case when trusted apps written by internal or trusted third-party developers.
  • Requires users log-in to the resource server
  • Client app needs to be registered in the resource server and the client app never gets hold of user login credentials.
PasswordIn this case, the user provides login credentials to the client app and the client app makes OAuth token call to the Authorization server to get the access token. The benefit of using the password of grant type over basic authentication is, in this case, client app makes only one call with userid/password over the trusted network, from next call onwards, it uses the access token to make the API call.
  • Typical use case when mobile app developed by internal developers and there is end-user involved to log in, user credentials are stored in the mobile device.
  • Requires app to be registered with the service provider.

Obtain and Use of an access token

Request

Response

Once the client receives the access token, it is valid until 1 hour(3600 sec). The client can make a call to resource server using the token like this

OpenId Connect

Problem Statement: When Login with Facebook or Google introduced for the first time , sometime in 2014, OAuth is not only used for Authorization, in many cases, it was used for Authentication. This means when the Client gets the access token from the authorization server, the client wants to know a few user information like name, address, etc. This a fair ask from clients in my opinion. And to be honest, most of this user information is already available in the authorization server, so the authorization server is capable of sending the info back to the client. Now, OAuth is not designed for Authorization (permission, scopes, easier access to the protected resources), not for Authentication. So, it is bad to send the user information. It is bad because there is no standard way to send the user information back to the client. Every implementation will be different which will create a bigger mess. And this is the major problem using OAuth for Authentication. OpenId Connect is going comes in play when you need to pass user info after client authorization.

So,

  • OAuth is for Authorization, which means no user information will be returned in the response of the access token call. If the OAuth token response looks like the below, then consider this OAuth implementation doesn’t follow the OAuth standard and it is bad.

  • OpenId Connect is for Authentication

OpenId Connet is a kind of add-on top of OAuth 2.0. What OpenId Connect adds

  •  It issues an ID token
  •  UserInfo endpoint for getting more user information. Basically it means if an Authorization server understands ID token, it can provide more user information when the client makes /userInfo endpoint with the ID token.
  • Standardized implementation
  • Standard set of scopes.

When an ID token is issued, it is typically very long and often the type of the token is JSON web token or JWT. For example,

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImp0aSI6IjUzMzVkNWZlLTk4ZTYtNDM5NC1hM2QyLTQ0OGE3MGFlZjMzYiIsImlhdCI6MTU3MjY0Nzc4NCwiZXhwIjoxNTcyNjUxMzg0fQ.KaHVrhfh9u9oswgdrMau3Z9TEXMt7bOYnrqt5stJqnc

As you noticed, I have color-coded the token in three different sections. Even though it looks like gibberish, it has a very specific format. If you decrypt the token www.jsonwebtoken.io you will see something like this.

So the JWT format is something like below.

  • This has header information which includes what type of token it is. What algorithm is used to generate the token
  • The payload has all the user information, when the token is issued, expire time, etc. Sometimes, the payload is called claims.
  • Signature is a very important part of the JWT token. It verifies if the token has been changed or altered in flight. So it confirms the token’s integrity. Because of the signature, the ID token can be verified without depending on the Authorization Server. So it is a self-contained token.

See also: Axway’s commitment to security: achieving Common Criteria EAL4+ certification for API Gateway

Conclusion: OAuth or OpenID Connect?

The access token represents a delegated permission that a resource owner gave permission to a client application to access its protected resources on its behalf for a limited time. Access token does not represent a user, that’s why access token can’t be used for Authentication.

Can OAuth protocol be used to return user information? Yes, it can be used by hacking the protocol definition, but it is a BAD idea to do this as the protocol does not provide any standard way of proving user information. So, you will be ended up implementing OAuth in your own way (Custom OAuth). What is the solution then? Use OpenId Connect which is built on top of OAuth provides a solution to user Authentication.

Read more: How to Implement OAuth with PKCE using Okta & API Management

API protection: Learn how to create a fortress around your data.