How to change authentication failure response message content type in WSO2 API Manager

With WSO2 API Manager, when calling an API with an expired tokens we are getting a SOAP response like following by default, the content type is XML.

    
       
           900904
           Access Token Inactive
           Access failure for API: /Authenticate, version: 1.0.0 with key: bb50cf86703ef76d4f4c3018ca74f115
       
    

If an application is expecting JSON response, API Manager has to send JSON version of authentication failure response. You can do this by changing

to

in [API_Manager]/repository/deployment/server/synapse-configs/default/sequences/_auth_failure_handler_.xml file After the change you will get

{
    "fault": {
        "code": "900904",
        "message": "Access Token Inactive",
        "description": "Access failure for API: /weatherApi, version: 1.0.0 with key: asPZCocnJt7m6KnAqGNNPH97fdga"
    }
}

Why OAuth 2.0 Dynamic Client Registration Protocol needed

APIs are playing key role in Connected Business. A Connected Business can grow revenue and outperform peers by increasing customer engagement, enhancing productivity, and seizing market opportunity.


For enterprises, securing and governing these APIs is not straightforward. It requires new approaches to access, protection and management, which requires the adoption of new technologies such as OAuth.

Introduction to Oauth

OAuth is an open standard to authorization. OAuth provides client applications a 'secure delegated access' to server resources on behalf of a resource owner. It specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials. OAuth is a protocol layered on top of HTTP and HTTP/S enables a user of both a composite application and a service to grant partial access to the service to the application. It is based on a three party trust federation: user-application, user-service and application-service.

OAuth 1.0

OAuth 1.0 was published in December 2007 and quickly become the industry standard for web-based access delegation.



OAuth 1.0 was largely based on two existing proprietary protocols Flickr’s API Auth and Google’s AuthSub. The majority of failed OAuth 1.0 implementation attempts are caused by the complexity of the cryptographic requirements of the specification. The fact that the original specification was poorly written didn’t help, but even with the newly published RFC 5849, OAuth 1.0 is still not trivial to use on the client side. The convenience and ease offered by simply using passwords is sorely missing in OAuth.

For example, developers can quickly write Twitter scripts to do useful things by using their username and password. With the move to OAuth, these developers are now forced to find, install, and configure libraries in order to accomplish what was before possible with a single line of cURL script.

OAuth 1.0 requires that the protected resources endpoints have access to the client credentials in order to validate the request. This breaks the typical architecture of most large providers in which a centralized authorization server is used for issuing credentials, and a separate server is used for API calls. OAuth 1.0 requires the use of both set of credentials: the client credentials and the token credentials which makes this separation very hard.

OAuth 2.0

OAuth 2.0 is the next evolution of the OAuth protocol and is not backwards compatible with OAuth 1.0. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.

OAuth 2.0 doesn't support signature, encryption, channel binding, or client verification. It relies completely on SSL for some degree of confidentiality and server authentication.

This is a main criticism against OAuth from client applications that were not browser based. For example, in OAuth 1.0, desktop applications or mobile phone applications had to direct the user to open their browser to the desired service, authenticate with the service, and copy the token from the service back to the application. The main criticism here is against the user experience. With OAuth 2.0, there are now new ways for an application to get authorization for a user.

OAuth 2.0 no longer requires client applications to have cryptography. This hearkens back to the old Twitter Auth API, which didn't require the application to HMAC hash tokens and request strings. With OAuth 2.0, the application can make a request using only the issued token over HTTPS.

OAuth 2.0 signatures are much less complicated. No more special parsing, sorting, or encoding.

OAuth 2.0 Access tokens are "short-lived". Typically, OAuth 1.0 Access tokens could be stored for a year or more (Twitter never let them expire). OAuth 2.0 has the notion of refresh tokens. While I'm not entirely sure what these are, my guess is that your access tokens can be short lived (i.e. session based) while your refresh tokens can be "life time". You'd use a refresh token to acquire a new access token rather than have the user re-authorize your application.

Finally, OAuth 2.0 is meant to have a clean separation of roles between the server responsible for handling OAuth requests and the server handling user authorization.

Because OAuth 2.0 is more of a framework than a defined protocol, OAuth 2.0 implementations are less likely to be naturally interoperable with any other OAuth 2.0 implementations. Further deployment profiling and specification is required for any interoperability.

OAuth 2 Profiles

OAuth 2.0 introduced two extension points via grant types and token types. The profiles for OAuth 2.0 are built on top of this extensibility. According to the OAuth 2.0 core specification, all OAuth clients must be registered with the OAuth authorization server and obtain a client identifier before any interactions. The aim of the Dynamic Client Registration OAuth 2.0 profile is to expose an endpoint for client registration in a standard manner to facilitate on-the-fly registrations.

OAuth 2.0 Dynamic Client Registration Protocol

The abstract OAuth 2.0 client dynamic registration flow illustrated by following 4 steps which describes the interaction between the client or developer and the endpoint.

1. Optionally, the client or developer is issued an initial access token giving access to the client registration endpoint. The method by which the initial access token is issued to the client or developer is out of scope for this specification.
2. Optionally, the client or developer is issued a software statement for use with the client registration endpoint. The method by which the software statement is issued to the client or developer is out of scope for this specification.
3. The client or developer calls the client registration endpoint with the client's desired registration metadata, optionally including the initial access token from (1) if one is required by the authorization server.
4. The authorization server registers the client and returns the client's registered metadata, a client identifier that is unique at the server, a set of client credentials such as a client secret if applicable for this client, and possibly other values.

Use Cases/Examples

• In Mobile Applications :

The Dynamic Client Registration OAuth 2.0 profile is extremely useful in mobile applications. Mobile client applications secured with OAuth have the client ID and the client secret baked into the application. These are the same for all installations for a given application. If a given client secret is compromised, that will affect all installations, and rogue client applications can be developed using the stolen keys. These rogue client applications can generate more traffic on the server and exceed the legitimate throttling limit, hence causing a denial of service attack. With dynamic client registration, you don’t need to set the same client ID and client secret for all installations. During the installation process, the application can talk to the authorization server’s registration endpoint and generate a client ID and a client secret per installation.

• UMA :

User-Managed Access (UMA) is a profile of OAuth 2.0. UMA defines how resource owners can control protected-resource access by clients operated by arbitrary requesting parties, where the resources reside on any number of resource servers, and where a centralized authorization server governs access based on resource owner policy.

The authorization server issues client credentials to the resource server. It is OPTIONAL for the client credentials to be provided dynamically through Dynamic Client Registration protocol alternatively, they MAY use a static process.

References

1. OAuth 2.0 Dynamic Client Registration Protocol https://tools.ietf.org/html/draft-ietf-oauth-dyn-reg-20
2. User-Managed Access (UMA) Profile of OAuth 2.0 http://tools.ietf.org/html/draft-hardjono-oauth-umacore-09
3. Advanced API Security: Securing APIs with OAuth 2.0, OpenID Connect, JWS, and JWE http://www.amazon.com/gp/product/1430268182/
4. http://en.wikipedia.org/wiki/OAuth
5. http://en.wikipedia.org/wiki/User-Managed_Access