Hypermedia Authentication API demo client

Hypermedia Authentication API demo client


What is the Authentication API

If you browsed the examples directory of the Curity Identity Server recently you may have stumbled upon a folder named api-driven. Inside, you’ll find resources about an authentication API exposed by the Identity Server. The API allows you to create authentication flows straight from your client, without the need of resorting to the browser, but still maintaining the same level of security which is granted by OAuth and OpenID Connect frameworks. What is more it is a hypermedia API, thus it enables a hypermedia-driven flow, where the server drives the client through the steps required to authenticate the user. These steps can be dynamic and do not require any modification on the client side when the server changes the authentication steps. As long as the client can understand the hypermedia representation of resources sent by the server, it can proceed with the flow.

Hypermedia Authentication API available from version 6.0

If you can't find the api-driven directory inside of $INSTALL_DIR/examples make sure you are using at least version 6.0 of the Curity Identity Server.

Apart from the documentation, in the directory you’ll also find an example client that you can use to check the possibilities that the API offers. In this article we’ll show you how to run the demo application and how you can easily tailor the client to your needs.


In order to run the demo application you need to make sure of a few things.

  1. Use at least version 6.0 of the Curity Identity Server. Although the Hypermedia Authentication API was first introduced as a beta in version 5.2, it has been improved and is in stable status since version 6.0.

  2. Configure the Identity Server at least with the example configuration. We assume in this tutorial that you run your instance of Curity Identity Server at localhost and the default port 8443. If not, you will have to adjust some settings where https://localhost:8443 is used to reflect the address that you actually use.

  3. Prepare a client. Below are the requirements for some values the client should have set. You can change these values to anything you like, but you will then have to adjust those values in the demo application. Make sure you have a client, which:

    • Has the name haapi-public-client.
    • Has at least the client credentials, code and Hypermedia Authentication API capabilities enabled.
    • Has a redirect URI registered: https://localhost:7777/client-callback.
    • Has an allowed origin registered: https://localhost:8443.
    • Has the Authentication Method set to no authentication.
    • Has at least the read scope.
    • Has the Require Proof Key option disabled. This can be found in the Client Application Settings group, in the Advanced tab. Note that whenever you change the Authentication Method to no authentication, for security reasons, the Require Proof Key option gets automatically enabled.
    • Has at least two Authentication methods enabled, so you’ll be able to see an authentication method selector.
  4. The client needs to have an additional capability enabled in order to use the API. In the client configuration, add the Hypermedia Authentication API capability.

HAAPI capability

  1. The client must be a public client in order to use some functionality needed by the API. This means that in the General section in Authentication Method it should have the value no authentication.

  2. Client attestation needs to be configured on the client. Find the Client Application Settings section and expand Advanced.

    1. Scroll down a bit to find Attestation, make sure it’s enabled.
    2. In the attestation type drop-down choose Web.
    3. Next to Web Policy choose Create, give it a name (web-policy for example)
    4. Turn on the option Disable Origin Verification and click Close

    The attestation policy is created and selected. One last thing is to turn on Disable Attestation Validation for test purposes.

    NOTE: Don’t forget to Commit the changes.

  3. In the demo-client.html file in the examples/api-driven folder set proper client name and token endpoint URL. You should set it in the config map found around line 135. Enter the following values if you use the default Curity configuration and the client mentioned before:

const config = {
    clientId: 'haapi-public-client',
    tokenEndpoint: 'https://localhost:8443/oauth/v2/oauth-token'
  1. Still in the demo-client.html, around line 91, you can find the starting value for the authorization request. As this is an input field it can be changed when running the client, but for ease of use you can change the value here.

    If you use the default Curity configuration and the client settings mentioned above, use this value:


Running the Demo

In order for the demo application to work it must be run from the same domain as the instance of Curity Identity Server. To achieve that, copy these three files: demo-client.html, demo-client.js and driver.js, to the directory idsvr/usr/share/webroot in the folder where you run your Curity Identity Server from.

Here’s a video showing the demo application in action.

There are many authorization flows and methods that can be used with Curity Identity Server, it is thus important that the client should dynamically choose next steps in the authentication and authorization flow, and avoid hard-coding as much as possible.

Change behavior and appearance of the authentication flow

One of the advantages of using API driven authentication is the ease of making changes in the behavior and visual side of the client. All the responses from the API are sent as JSON, enabling you to display the results exactly as the client needs, not in a way they’ve been rendered by the backend. That is especially useful in case of native apps, as native components can be used to display steps of the authentication flow, instead of HTML.

Changing the behavior

Currently, whenever the API sends a redirect response, we show it to the user and ask them to click to move further. This is done in the demo application to show each step separately. Normally the client would perform the redirects automatically. To achieve that, modify the file demo-client.js (remember to modify the file which is served from the webroot directory). Find the lines with following code (which renders the redirect button):

if (apiRedirectUri) {
    console.log(`API redirect detected, URI is ${apiRedirectUri}`)

Then change the contents of the if statement to:

if (apiRedirectUri) {
    console.log(`API redirect detected, URI is ${apiRedirectUri}`)
} else {

Now, instead of seeing a Redirect component, the user will be redirected automatically to the new URI.

Changing the appearance

The demo client consists of a few different component-like functions which are responsible for creating appropriate DOM elements. These functions are called from the generatePage function. Let’s modify the Selector method, so it displays some nice icons, instead of a list of names. Exchange the Selector method for the following:

function Selector(action) {
    const iconGoogle = "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0MS42NiA0Mi41MSI+PGRlZnM+PHN0eWxlPi5jbHMtMXtmaWxsOiM1MTdiYmQ7fS5jbHMtMntmaWxsOiMzMWE3NTM7fS5jbHMtM3tmaWxsOiNmYWJiMDk7fS5jbHMtNHtmaWxsOiNlNzQzMzY7fTwvc3R5bGU+PC9kZWZzPjxnIGlkPSJMYXllcl8yIiBkYXRhLW5hbWU9IkxheWVyIDIiPjxnIGlkPSJMYWdlcl8xIiBkYXRhLW5hbWU9IkxhZ2VyIDEiPjxwYXRoIGNsYXNzPSJjbHMtMSIgZD0iTTQxLjY2LDIxLjczYTE4LjEyLDE4LjEyLDAsMCwwLS40NS00LjM1SDIxLjI2djcuODlIMzNhMTAuNDMsMTAuNDMsMCwwLDEtNC4zNCw2LjlsMCwuMjYsNi4zMSw0Ljg5LjQzLDBjNC0zLjcsNi4zMy05LjE2LDYuMzMtMTUuNjMiLz48cGF0aCBjbGFzcz0iY2xzLTIiIGQ9Ik0yMS4yNiw0Mi41MWEyMC4yNCwyMC4yNCwwLDAsMCwxNC4wNy01LjE1bC02LjctNS4xOWExMi42MiwxMi42MiwwLDAsMS03LjM3LDIuMTIsMTIuOCwxMi44LDAsMCwxLTEyLjEtOC44M2wtLjI1LDBMMi4zNSwzMC41NmwtLjA4LjI0YTIxLjIzLDIxLjIzLDAsMCwwLDE5LDExLjcxIi8+PHBhdGggY2xhc3M9ImNscy0zIiBkPSJNOS4xNiwyNS40NmExMy4zMSwxMy4zMSwwLDAsMS0uNy00LjIsMTMuOSwxMy45LDAsMCwxLC42OC00LjIxdi0uMjhMMi40OCwxMS42MWwtLjIxLjFhMjEuMiwyMS4yLDAsMCwwLDAsMTkuMDlsNi44OS01LjM0Ii8+PHBhdGggY2xhc3M9ImNscy00IiBkPSJNMjEuMjYsOC4yMmExMS44LDExLjgsMCwwLDEsOC4yMiwzLjE2bDYtNS44NUEyMC4zNywyMC4zNywwLDAsMCwyMS4yNiwwYTIxLjIzLDIxLjIzLDAsMCwwLTE5LDExLjcxbDYuODcsNS4zNEExMi44NSwxMi44NSwwLDAsMSwyMS4yNiw4LjIyIi8+PC9nPjwvZz48L3N2Zz4=";
    const iconForm = "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1Ny4xIDQzLjQ3Ij48ZGVmcz48c3R5bGU+LmNscy0xe2ZpbGw6I2ZmZjtzdHJva2U6IzYyNmM4Nzt9LmNscy0xLC5jbHMtM3tzdHJva2UtbWl0ZXJsaW1pdDoxMDt9LmNscy0ye2ZpbGw6IzYyNmM4Nzt9LmNscy0ze2ZpbGw6bm9uZTtzdHJva2U6IzY0NmU4Mjt9PC9zdHlsZT48L2RlZnM+PGcgaWQ9IkxheWVyXzIiIGRhdGEtbmFtZT0iTGF5ZXIgMiI+PGcgaWQ9IkxhZ2VyXzEiIGRhdGEtbmFtZT0iTGFnZXIgMSI+PHBhdGggY2xhc3M9ImNscy0xIiBkPSJNMjgsNDNINC41YTMuODcsMy44NywwLDAsMS00LTMuNjl2LTMxSDI4LjU1Ii8+PHBhdGggY2xhc3M9ImNscy0xIiBkPSJNMjgsNDNINTIuNmEzLjg3LDMuODcsMCwwLDAsNC0zLjY5di0zMWgtMjgiLz48cGF0aCBjbGFzcz0iY2xzLTEiIGQ9Ik0yOC41NSw4LjI5SDU2LjZWNC4xOUEzLjcsMy43LDAsMCwwLDUyLjkxLjVINC4xOUEzLjcsMy43LDAsMCwwLC41LDQuMTl2NC4xSDI4LjU1Ii8+PGNpcmNsZSBjbGFzcz0iY2xzLTIiIGN4PSI0Ljg4IiBjeT0iNC40IiByPSIxLjM3Ii8+PGNpcmNsZSBjbGFzcz0iY2xzLTIiIGN4PSIxMC42NCIgY3k9IjQuNCIgcj0iMS4zNyIvPjxjaXJjbGUgY2xhc3M9ImNscy0yIiBjeD0iMTYuNCIgY3k9IjQuNCIgcj0iMS4zNyIvPjxsaW5lIGNsYXNzPSJjbHMtMyIgeDE9IjE1LjkzIiB5MT0iMjIuNDUiIHgyPSIxNS45MyIgeTI9IjI5Ljc2Ii8+PHJlY3QgY2xhc3M9ImNscy0zIiB4PSIxMC4xOCIgeT0iMTkuMDUiIHdpZHRoPSI0MC41MyIgaGVpZ2h0PSIxNC4xOSIgcng9IjMuNCIvPjwvZz48L2c+PC9zdmc+";
    const iconDefault = "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyOC40IDI4LjQiPjxkZWZzPjxzdHlsZT4uY2xzLTF7ZmlsbDpub25lO30uY2xzLTEsLmNscy0ye3N0cm9rZTojNjI2Yzg3O3N0cm9rZS1taXRlcmxpbWl0OjEwO30uY2xzLTJ7ZmlsbDojZmZmO308L3N0eWxlPjwvZGVmcz48ZyBpZD0iTGF5ZXJfMiIgZGF0YS1uYW1lPSJMYXllciAyIj48ZyBpZD0iTGFnZXJfMSIgZGF0YS1uYW1lPSJMYWdlciAxIj48cGF0aCBjbGFzcz0iY2xzLTEiIGQ9Ik0yMi42OSwyNS4xMXYtMmE0LDQsMCwwLDAtNC00aC04YTQsNCwwLDAsMC00LDR2MiIvPjxjaXJjbGUgY2xhc3M9ImNscy0yIiBjeD0iMTQuNjQiIGN5PSIxMS4wMyIgcj0iNC4wMiIvPjxwYXRoIGNsYXNzPSJjbHMtMSIgZD0iTTE0LjIuNUExMy43LDEzLjcsMCwxLDEsLjUsMTQuMiIvPjwvZz48L2c+PC9zdmc+";

    const parentElement = document.createElement('div');
    const titleElement = document.createElement('h3');
    titleElement.textContent = action.model.title;

    const optionsElement = document.createElement('div');

    action.model.options.forEach(option => {
        const linkElement = document.createElement('a');
        linkElement.style = "margin-right: 10px;";
        linkElement.href = "#";
        linkElement.onclick = () => apiRequest(option.href);
        const icon = document.createElement('img');
        icon.style = "height: 35px";

        switch (option.kind) {
            case 'google':
                icon.src = iconGoogle;
            case 'html-form':
                icon.src = iconForm;
                icon.src = iconDefault;
        icon.title = 'Login with: ' + option.title;

    return parentElement;

The selection screen will now show icons instead of names. What is more important, the change has been done only in the client code. There was no need to update any templates on the server side. This can, for example, allow you to have different clients displaying the authentication flows differently, while still using the same instance of the Curity Identity Server.

You can see the result of the changes in code in this short video:


Thanks to the demo client you can have a test drive of the Hypermedia Authentication API and quickly check what this feature allows you to do with the authentication flows. We’ve also shown how easy it is to tailor the authentication flows to your needs, by changing just a few lines of the client code.

Should you have any questions or comments on the API-driven authentication, don’t hesitate to contact us.

Let’s Stay in Touch!

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

Keep up with our latest articles and how-tos using RSS feeds