Developer Community

Best Practices

This is a brief check-list of practices that are meant to make the best of your identity service. We're going to updated it with common problems and solutions, so if you have a questions you cannot find the answer to, please feel free to send it to us.

Updating Certificates

Your API certificate has an expiration date, which is usually one year from the moment of issuing. You will receive a notification prior to this event, but it is your duty to renew the certificate and update it on your server. Please make sure you keep up to date information in your profile so that our notifications reach you. If your API certificate expires the SSL system will not accept it your service will not be able to connect to the identity API interface, which can result in business disruptions. However, you do not need to wait until your certificate expires. These are not Server SSL certificates and you will not be charged for renewing a them even if you are running a business environment. As a best practice, for safety, you should renew your API certificates when they reach two thirds of their life. This is also a good security measurement.

Reverse - Proxies

There are two ways reverse proxies can be used in conjunction with Identity plus: pass through mode, and SSL

In case you are using a reverse proxy for your server, the recommended way is HTTPS Pass-Through mode, or TCP relaying because the server can only detect the client certificate if the server itself is running over HTTPS. If HTTPS is off-loaded on the reverse proxy, your application is in fact running on HTTP and you lose access to client certificates.

That said, reverse proxies can forward the / some client certificate details, like CNAME to the downstream server in http headers. CNAME is all that is needed to verify the client certificate against the identity API, therefore this is a valid way of doing it, however, this does require extra implementation and there is one important note:

  • You will no longer have MASSL between the server and the client, only between the proxy and the client. It is therefore of paramount importance that the connection between the server and the proxy be strictly local connection or a second MASSL channel. Otherwise MITM attacks may occur.

Implementation Check-List

  • Create Identity+ Account
  • Issue & install device certificate for your browser
  • Add & verify your domain
  • Issue & save API certificate for your application (grab the password as you can only do that at the time of issuing)
  • Download the API Reference Implementation. If one does not exist for your programming language use the Generic ReST API as guide
  • Test your implementation with this page. Test all the functions on your user. Make sure you use a development API Certificate. That way, when you revoke it, all changes made to your user with that certificate will be undone.

For SSL Enabled Server

  • Download the identity certificates and install them in your trust store. We recommend you install all certificates from the chain
  • Restart your web server
  • Test your implementation again
  • If the certificates are installed properly and the server request & recognizes the identity client certificate, you will not see the redirect URL in your browser. Everything will work in the back-end. Also, in the Request Details tab the Method field will say "Certificate"".


  • Before going live, test your application with a browser that does not have Identity Plus client certificate to make sure you are not locking out people who do not have certificates.
  • If you wish to use identity plus certificates all over your site, redirect users nicely to identity plus to get their free certificate
  • You can enforce the use of client certification from your web server but this will block connections that don't have one at tcp level not giving you the chance to treat the case. This can increase security but we only recommend this for closed circle applications.
  • Consult the identity+ developer resources for further suggestions & best practices
< How it works, Briefly API Dependencies (Getting Ready) >