Authentication of Web APIs has three main characteristics, i.e. 1) the required credentials, 2) the used authentication protocol, and 3) the way of sending the authentication information, which are described as three classes in the proposed authentication ontology, i.e. AuthenticationMechanism, Credentials and TransmissionMedium respectively. The ontology is shown below. The AuthenticationMechanismclass has six subclasses corresponding to six types of common authentication mechanisms. AuthenticationMechanism should be associated with the concept of either Service or Operation through hasAuthenticationMecahsism property.
It relates to Credentials and TransmissionMedium through properties of hasInputCredentials and wayofSendingInformation respectively. The Credentials class has a number of subclasses including APIKey, Username, Password etc. required by different authentication mechanisms. The TransmissionMedium has three instances (ViaHTTPHeader, viaHTTPbody and ViaURI), used to describe that the credentials are sent by using only the URI or through constructing an HTTP header.
The authentication mechanisms used by most of Web APIs are differentiated by either the used authentication credentials (e.g. API key or username and password), or the transmission security protocol (HTTP Basic Authentication, HTTP Digest Authentication and OAuth), or a combination of those. In the authentication ontology, they were classified into the following six types, which are described as RDF(S) classes.
Direct class is used to describe the authentication mechanism which employs no transmission security protocol and relies only on using credentials. Typically, the credentials used in this type of authentication mechanism are API Key, or username and password, which are described into APIKey, Username and Password classes as subclasses of Credentials. The actual string name, used by every API to represent every type of credential, is an instance of the corresponding type, for example, "api_key", "APIKey" are instances of class APIKey.
HTTPBasic class describes the basic access authentication mechanism that came as a companion of HTTP/1.1 specification. It requires a username and password as credentials when making a HTTP request. Different from Direct, this authentication mechanism prescribes the transmission format of credentials as well as their transmission medium. That is, the credential string is username being appended with a colon and concatenated with the password. The resulting string is then encoded with the Base64 algorithm. The Base64-encoded string is transmitted in the HTTP header to the server. Once reaching the server, the credentials are Base64-decoded resulting in the colon-separated user name and password string.
HTTPDigest describes the authentication mechanism that follows the same process as the HTTP basic access mechanism but brings it further with credentials being encrypted through the application of MD5 cryptographic hashing together with usage of nonce values, i.e. a digest of the username and password which cannot be directly decoded. Similar to HTTPBasic, it prescribes the transmission format as well as transmission medium of the credentials.
OAuth describes the OAuth authentication mechanism that is the process in which a User grants access to his/her protected resources, hosted by a Service Provider, to a Consumer Application without sharing the credentials with the Consumer Application. To request access to protected resources, the Consumer Application uses tokens generated by the Service Provider instead of the User’s credentials, such as username and password. The process uses two token types, request token and access token, which are intermediary results of OAuth process (also known as token acquisition dance) initialized by a request with only Consumer Key, Consumer Secret as credentials. For Consumer Application with single-user use cases, some Service Providers, like Twitter, offer the ability to issue an access token directly for Consumer Application’s self-owned account without the need to implement the entire OAuth token acquisition dance. Instead, Consumer Application can pick up from the point where it works with an access token to make signed requests for Twitter resources. Also, for Service Provider that implements OAuth to protect resources that are not belonging to a particular user, such as Yelp, the Consumer Application can obtain an access token directly at registration time. In these cases, access token and access token secret become credentials that are required at the time the first request is raised to the Service Provider. The credentials involved in the OAuth process are described into classes of OAuthConsumerKey, OAuthConsumerSecret, OAuthToken, OAuthTokenSecret, which are subclasses of Credentials class. In a full OAuth dance, the Service Provider needs to expose three additional URLs, namely request toke URL, authorize URL and access token URL, to the Consumer Application for it, by calling, to obtain request token, direct user to authorize and obtain access token respectively. These URL, though pertinent to the Service Provider’s API, is more associated with the OAuth authentication mechanism than the API itself, and therefore should be described by the authentication ontology. Specific to the OAuth type of authentication mechanism, it has three additional properties of hasRequestTokenURL, hasAutherizeURL, hasAccessTokenURL to aid the annotation of OAuth-specific service properties.
WebAPIOperation is used to describe the cases where Web APIs implement their own operations, which need to be called, before being able to invoke other operations. Usual credentials like API Key, Username and Password might be required to call this particular operation. The number of Web APIs that use such authentication mechanism is rather small, counting for only 5% of our survey APIs.
SessionBased describes the authentication mechanism where the user has to obtain a unique session key through a login service call, which takes username and password as credentials. The user then must include the session key in each following requests, and make a logout call when done. This type of authentication is not well suited for Web APIs because it requires that the API clients keep track of the state, and make a minimum of three HTTP requests, in order to call one operation only. As reflected by our survey only 2% of the Web APIs use such authentication mechanism.
The authentication ontology is expected to serve the purpose of extending service description with authentication information by simply attaching it to the service and operation elements. One of the design principles, among many others, is not to be bound to any Web API description model, and hence the Service and Operation classes lack a namespace because they serve as placeholders that can be replaced by the service and operation elements of any Web API model, not necessarily the service ontology model proposed here. In this way, the ontology can be used as an extension to existing formalisms and remain independent from them. The extension of authentication ontology to any service model is defined as follows: the Service class, of any service model, relates to, through requiresAuthentication property, the ServiceAuthentication class, which has three instances including All, Some and None that are used to point out that the service requires authentication for all its operations, for only some of them or for none of them. These properties can be explicitly defined or deduced through reasoning mechanisms over the operation annotations. The Service or Operation class has relationship to the AuthenticationMechanism class through hasAuthenticationMecahsism property.
