Applications can expose their APIs over the internet via web services.  In order to use the web service, the calling application needs to authenticate, if that is required (An unsecured API would have no authentication.).  The authentication can be an application-wide authentication, such as you would obtain to use Google Maps, or for a specific user, like a userid and password or digital certificate used to interact with an ERP application like SAP.

In the second case user credentials need to be verified against an LDAP, Active Directory, or some other kind of user database.  That is where the user’s userid is stored and their password.  LDAP and Active Directory can also store digital certificates, called x.509.  You can think of those as similar to SSL where a pair of keys is used to decrypt and encrypt information.

The secure way of securing an API is to use tokens.  There are several types including OAuth, SAML, and JWT.

[See Also: Remarkable Digital Experience Made Possible by Tag Management]

Google, Facebook, Twitter, Dropbox, and Github use OAuth. Enterprise business applications often use SAML, which is older than the other techniques. Some applications use JWT. All of these use tokens.

Here we give a brief overview of using any of those to manage API security using tokenization.

Token Definition

Think of a token as a proxy for user credentials.  The idea is to present the API key, userid, password, or digital certificate to a secure vault, which is an infrastructure hardened against hacker attacks.  The secure vault hands off the token to the part of the application that does whatever it is supposed to do, like, perhaps, create a sales order in an ERP system.

Tokens are the principle by which credit cards can be processed.  This design is written by credit card industry’s standards body called The PCI Council.  The idea is to protect credit card numbers by not sending those either encrypted or in clear text to ecommerce systems. (Actually this secure means of processing credit cards is not implemented in the USA nor all of Europe due to various business reasons like pushback from retailers and banks who worry that any increase in complexity could cause them to lose business.)

OAuth Token Flow

OAuth is one way to protect web services and websites using tokens.  There are two versions:  OAuth 1.0 and 2.0.  They are not compatible with each other.

The technical standards for OAuth are in this RFC.

Suppose you go to a website that lets you log in using your Twitter, Google, or Facebook credentials. That is using OAuth.  Basically a server called a resource server obtains the API key and user credentials and issues a token which is then presented with subsequent requests to Twitter or whatever. The resource server is the vault server hardened against attack.  It is apart from the application.

[See Also: 6 Easy Ways to Start Working on OpenStack for Custom Development]

Here is an illustration from Twitter. The login mechanism (Login is called authentication or authorization, although technically they are not the same thing.) is the same for web services as for users using a browser.
The user credentials are presented base64 encoded in the Authorization header.  The Twitter OAuth resource server responds with a token.

The Twitter OAuth resource server responds with a token.

Since the user credentials are base64 encoded, they are easily decrypted by a hacker.  So they should be encrypted using SSL.  The token itself can be sent in clear text since it has a time limit and is tied to the user credentials and a specific task (e.g., an API function and session).  So the hacker would not find that useful for a replay attack.  (A replay attack is when a hacker steals session information, such the SSL key exchange, and uses that to pretend to be the authenticated user thus gaining access to the application.)


SAML places the userid, password, or digital certificate to be embedded in the XML message.  The token issued by SAML is called an assertion.  Since it uses XML it uses SOAP, so it is not supported with REST.  While it is an older technology, it is still widely used especially in large business applications.  SalesForce, for example, supports SAML.

SAML was developed mainly to allow a single user session to work across different domains.  That is called single sign on.  That way a user does not have to have the user login each time they move go from to nor maintain separate user databases.

The receiving web services or server must be configured to process the SAML payload in the SOAP message.  Most often this is done by putting an authentication device in front of the web server or a web agent inside the webserver, such as the CA Siteminder web agent.  That reads the SOAP message and authenticates the user against an LDAP user store and then strips off the SAML header.  Then the XML message is forwarded onto the web service with or without the SAML assertion added.  The web server returns the SAML assertion to the calling application.

Here is a rather complicated-looking example of the SAML XML format from SalesForce showing both the assertion, the digital signature, and X.509 key.  It’s only complicated because the signature and key are so long. If the userid and password were all that was there it would be much shorter.

SAML XML format from SalesForce

This SAML XML is put right inside the rest of the XML that is required by the web service, such as product number, store, account number, or whatever is required to process the transaction.

SAML and OAuth Together

REST has replaced SOAP for new applications, because it is easier to understand and program.
SAML and OAuth do not work together, yet.  However the standards for doing that are in draft.  This would allow an application that is already authenticated to a SAML authentication server to use that assertion to obtain an OAuth token.  In other words it would support a mixed SAML and OAuth environment.

JSON Web Token (JWT)

JWT uses an authorization header presented in JSON format.  The opensource tools for creating and working with these are here.

Here is a sample header from that same website.  This one says that this is a JWT token using the SHA256 hashing algorithm.

JWT token using the SHA256 hashing algorithm

Here is a sample payload:

sample payload

And the hash value:

hash value

All of that is encoded into a token like this:

encoded into a token

Which is then presented in subsequent requests to protected resources, such as a web service, in the Authorization Header:

Authorization Header

Here is a process flow diagram from the JWT website.

process flow diagram from the JWT website
So tokenization is the secure way to access API via web services.  Since there is no browser, there is no cookie to store these cookies, so it solves the state problem.

Everything you need to know about outsourcing technology developmentAccess a special Introduction Package with everything you want to know about outsourcing your technology development. How should you evaluate a partner? What components of your solution that are suitable to be handed off to a partner? These answers and more below.

Introduction Package

Source: zymr

Zymr blogger


Leave a Reply