Hypermedia authentication API explained.

What is Hypermedia Authentication API

On this page

OAuth and OpenID Connect has provided the industry with solid standards for OAuth and OpenID Connect has provided the industry with solid standards for authorization and authentication. Both standards are battle-tested and implemented across a vast number of websites and applications. Part of their success is the strong emphasis put on security. Thanks to the use of a browser and HTTP redirect mechanisms, the flows can remain secure from a number of threats. For example, when dealing with third party apps users don't have to enter their credentials directly in the app - in the browser they are redirected to the external authentication website. Using browser redirects also helps to mitigate attacks on the contents of the response.

OAuth and OpenID Connect limitations

But the use of a browser in OAuth and OpenID Connect flows is lately becoming a burden. For the last couple of years we've been steering away from traditional web-based apps to Single Page Applications and, more importantly, Mobile Apps. In those settings the necessity of using a browser during the authentication flow can pose some problems. The app need to have capabilities to both open the browser and then capture the redirect response - task which can be especially problematic for desktop applications. Having to open the browser additionally impacts User Experience - the user has to leave the original app to go to the browser. The need for redirects is also problematic to Single Page Applications, which generally want to avoid the need to reload the whole page. Some SPAs use iframes to complete OAuth flows to avoid page reloading, but this needs support for third-party cookies in the browser - a feature which the browsers are looking to remove in the near future to limit the possibilities for user tracking.

What can further impact User Experience is the fact that it is the Authorization Server, not the Client, which maintains the look and feel of the authentication process.

Resource Owner Password Credentials (ROPC)

A common approach to bypass the mentioned limitations is to use the A common approach to bypass the mentioned limitations is to use the OAuth password flow (ROPC). Although using this flow resolves some of the problems and can be especially helpful in applications which cannot handle a redirect response from the Authorization Server, it has it's own drawbacks. The ROPC flow is limited to only username and password stored by the given Authorization Server. It's not possible to use any external authenticators with this method, but what is more important, it's not possible to use any Stronger Customer Authentication methods, like Multi-Factor Authentication. Moreover, enabling this flow without any additional client app attestation can lead to serious security risks. It is then quite easy to impersonate the Client app and take advantage of the password flow, which can lead to the leakage of passwords of your users.

What is authentication?

The Resource Owner Password Credentials flow was present in the OAuth specification from the very beginning, but the authentication process has changed significantly since. Back in the days, a user presenting their login and password known to the Authorization Server, was enough to authenticate them. Nowadays, authentication is a complex state machine, which moves the user from one step to another, trying to establish their identity. Think of such a scenario: you allow your users to authenticate with either their password or a linked social media account. But if they authenticate using a social media account you want them to confirm the authentication with a second factor - a one-time code sent to their mobile. What is more, you don't want them to authenticate with the social media account, if they changed the country they last logged in from.

Complex authentication flow example

Such a complex authentication scenario cannot be simply replaced by the ROPC flow.

Hypermedia Authentication API is the solution

The Hypermedia Authentication API available in Curity Identity Server aims to solve the aforementioned problems:

  • Necessity of sending the user to the browser and using redirects.
  • Performing authentication as a complex state machine.
  • Letting the Authorization Server control the look and feel of the authentication process.

Thanks to the API, clients can interact with the Authorization Server directly, without the need of an intermediary user-agent (such as a browser) but still adhering to the flows standardised by OAuth and OpenID Connect frameworks. As the API responds with JSON it is now the Client which takes control of User Experience. For example, it enables mobile clients to use native components to render authentication steps, without the need of dealing with HTML. It also means that any changes to the look and feel of the authentication process are deployed on the Client side, not at the Authorization Server. This provides a better experience for the development and operations teams, which now don't have to implement and deploy changes in separate projects.

Because it is a hypermedia API, it is still the Authorization Server which controls the flow of the authentication process, and is able to create complex authentication flows. This also means that any changes to the flow, like adding new authentication methods or creating new conditions for an authentication, can be implemented on the server side without any code change needed at the Client. The Client consumes a hypermedia API, so it is able to react dynamically to any such changes.

The Hypermedia Authentication API helps you to introduce a separation of concern: let the Client handle the look and feel of the authentication process, and let the Authorization Server handle the authentication flow.

Flow with traditional OAuth: Traditional OAuth flow involving the client app, browser and authorization server

Flow with Authentication API: OAuth flow with API. Browser-less Authentication Flow

What about security?

Curity's Hypermedia Authentication API is designed to enable clients to overcome the OAuth and OpenID Connect limitations that stem from the need of using a browser, but to maintain at least the same level of security as when the browser is in use. Curity has developed a framework for guaranteeing the identity of the Client using client attestation mechanisms. What is more, Proof-of-Possession tokens are used instead of Bearer tokens, to further limit the danger of any request or response being leaked. Applying these techniques assures that the communication between the Client and the Authorization Server is neither intercepted nor possible to replay, even in case of public clients (like mobile applications).

To maintain high level of security and privacy for third-party applications the Curity Identity Server requires such applications to use Multi Factor Authentication and signed consent when using the Hypermedia Authentication API.

The attestation framework developed by Curity uses different implementations depending on the platform which the Client runs on - whether it's an Android app, an iOS app or a browser-based Single Page Application. You can have a look at the Hypermedia Authentication API Security in Detail whitepaper to learn more details of the attestation.


The Hypermedia Authentication API lets you make another step in increasing User Experience and security of your applications. It enables you to create a seamless experience for your users, as all of the authentication process can be fulfilled within the application, without the need of leaving the app to authenticate in the browser. At the same time you do not lose the flexibility or security offered by a traditional authentication flow handled by the Authorization Server.

If you want to try out the Hypermedia API, have a look at the example client, and don't hesitate to contact us, should you have any questions or comments about the Hypermedia Authentication API feature.

Join our Newsletter

Get the latest on identity management, API Security and authentication straight to your inbox.

Start Free Trial

Try the Curity Identity Server for Free. Get up and running in 10 minutes.

Start Free Trial