Developer Community

How it works, Briefly

The identity authentication work-flow is very similar to other authentication as a service systems. In fact it is even somewhat simpler because we have fewer calls and redirects. This simplicity is due to the fact that identity tracking is based on SSL Client Certificates and not Cookies, which is much more reliable and secure method for tracking.

Mainstream Approach

By far, the most popular way of tracking sessions are browser cookies. The AAAS provider will store cookies in your browser to track your authentication status, the destination site will store cookies in your browser to track authentication status within their site, and in the back, there is an API communication between the site and the AAAS to track your overall authentication status, which ultimately relies on these cookies. This API communication is not based on redirects, your browsers is unaware of it, but when something is not right, for example you are not authenticated into the AAAS provider, a redirect is necessary. These redirects are difficult to track, unreliable and very insecure, because they carry tracking information over environments the security of which cannot be controlled.

Identity plus Approach

The identity uses SSL Client Certificates and public key cryptography (PKI) to track devices, which is the most reliable and secure method of information exchange available for browsers today. There are no cookies involved in the process either. identity tracks clients through their certificate and the API communication with your service is done through dual authenticated SSL, which means your service is also authenticated via SSL Client Certificate. Also, for browsers that do have a certificate installed, you can simply remove cookie based tracking yourself, and rely solely on the identity uid of users. With this method in places, even in the case when a redirect is necessary, the communicated information is encrypted both ways, which means that although it travels through insecure environment (we cannot change that), there is just simply no way for anybody to intercept or alter the data or impersonate any of the parties. As such, there is no need for login tokens, refresh tokens, temporary tokens or any other security work around, which greatly simplifies work-flow.

Therefore, in spite of the fact that we have fewer calls and a simpler logic, the result is a much more secure authentication mechanism.

The work-flow

The full activity diagram is somewhat more crowded and complicated but it essentially portrays the same flow as depicted in the banner picture of this page: continuous, no-redirect backbone for normal situations and a few branches for the exception ones.

  • Browser arrives on site
  • Site reads the certificate of the client
  • Site issues a background API Call to identity
  • Site receives response and processes it
  • Case 1: Certificate is valid and cleared for sign in

    • Continue and log the user in
  • Case 2: Certificate needs validation, for various reasons such as (when it expired or the owner did not use it for some time or he or she deliberately asked to be verified every single time)

    • In this case we redirect to identity to perform the validation
  • Case 3: There is a lack of certificate or the certificate was revoked (a big red flag)

    • We can handle this outside the main work-flow, either simply deny connection, redirect away from sensitive area, ask the user to get a Free identity certificate or other maneouver.
  • Cases 1 and 2 will merge back together and both end up on your site with an authenticated device (a valid SSL Client certificate), in the first case because we never left, in the second one because identity redirects the browsers back once the validation is done.

This concludes the flow, and if you are using the api wrapper package, you can implement the entire thing with only a few lines of code. Please consult the documentation for further details.


Like in any other AAAS scenario, identity serves as the the middle man in the authentication process. This means both the person who is being authenticated and the server who wishes to authenticate the person, need to have a relationship with the AAAS provider.

People (On the browser side)

With identity, this relationship is 2 Factor, so to speak, the user needs to have an identity account and he or she needs to keep an up to date identity issued client certificate in his or her browser. The identity particularity is that these certificates are free to issue in any number and they contain no personally identifiable information. They are like a key that is compatible with all browsers and SSL enabled system.

The trust component of the certification is not provided by identity, but rather by the community, a distributed trust system mediated by identity plus. In fact if you are looking at this because you are on the server side, you are going to become a valuable member of this system, because the trust you place in your users will be added to the community and together you will form a powerful shield which differentiates malicious entities from legitimate users.

Sites (On the server)

Similarly, on the server side you need to have an identity account and to identify your service(s) you will need to have API Client Certificates. These are also SSL client certificates, which cryptographically identify each of your services and enable encryption for all communication between identity and them.

These API certificates do not bear any cost, what's more, if your site is for personal use only or otherwise not-for-profit, you can use the entire service for free. If you are a business user you will be charged per number of authenticated users in a billing period, not on the number of authentications themselves. The amount depends on the volume of users you authenticate, $0.9 / user / year or even lower. Please contact sales for a personalized offer. for an estimation.


For any other details you can consult the documentation and feel free to ask if you have any unanswered question.

Best Practices >