The Identity + API, Version 1

Because of it's nature, the Identity + service can serve either as a substitute or can live alongside your current single or two factor authentication system, adding to its security. The Identity + system is in itself a two factor authentication mechanism (password / PIN + SSL client certificate), but it is extremely inconspicuous and therefore, will add very little overhead to the user. Once the certificate is installed on the client and authenticated through Identity +, it becomes relatively transparent. Unless the certificate is flagged or the user deliberately chooses to introduce his Identity + password / PIN, every time, the certificate will be used to identify his device and the user will walk through as if there were no barriers. There are no tokens, no SMSs, the very device it uses, becomes an authentication tool itself.

Getting Ready (Dependencies)

There are a couple of dependencies imposed by the SSL / TLS system which need to be in place in order to be able to detect client certificates yourself.

Run HTTPS

The obvious first requirement is that you need to run your site on HTTPS, and for this you need to have an SSL Server certificate which Identity + does not provide. There are no additional requirements imposed by the Identity + system, you can use any certificate provider and any type of certificate (domain validation, extended validation) that browsers accepts.

It is important to mention that in case you do not wish to, or can't spend money on the certificate, you can simply turn to "Let's Encrypt" an emerging certificate authority which not only gives domain validated certificates for free but they also provide various levels of automation for certificate issuing and renewal to make the process more user friendly.

If you are unable to run HTTPS, you are unable to import the Identity + certificates into your trust store or if for any other reason you cannot detect identity + client certificates, please refer to the HTTP Legacy section which is a work-around for such cases.

Recognize Identity + Issued Client Certificates

The SSL / TLS certificate requires that a trust relationship exist, not only encryption. For this to be true in a dual authenticated manner, the server needs to trust the Certificate Authority, that issued the client certificate the same way as the browsers trusts the CA that issued the server certificate. While most browsers come with pretty much all recognized authorities installed the server side catches up a little bit slower. Additionally, some browsers are buggy and will not return the client certificate unless it is directly signed by a trusted certificate, meaning it is not enough if the server contains the Identity + root certificate. So to be on the safe side, we recommend you import all three Identity + authority certificates from the chain into your trusted certificate store. Follow the instructions on the Developer Resources / Download & Import Certificates from where you can also download the certificates.

Get Your Identity + API Certificate

To connect to the identity + API Web Service you will need an API certificate which you can obtain from the advanced section within your Identity + account.

API certificates are also SSL client certificates, as in this B2B case, your server is a client to Identity +. As such, the entire communication between your service and the identity + service will take place over dual authenticated SSL at all times.

API certificates are account dependent, which is the way identity + identifies your service. There is no need for further tokens or identification keys, the API certificate contains everything we need to identify your service at each request. The API certificates are also domain dependent. You can issue these certificates yourself from your identity + account, but first you need to add the domain and validate it's ownership. You can have a mixture of business and personal domains and they will be subject to different billing systems (Free in case of personal and paid in case of a business)

Grab the Reference API

The Identity + service is a ReST service, so in principle you do non need any special code to connect to it, however, there can be additional higher level implementations that make implementation work easier. Please consult our reference API section for such libraries. This library is a community driven open, source software package that can be downloaded, modified and used without any limitations. If a library is not available for your language, please use this reference documentation to implement one from scratch or translate it from a similar language. If that were the case, we'd appreciate if you could make your implementation available for free for other people to use. Should you decide to do that, you can publish it on our repository.

Operating Mode

The Identity + system assumes that you manage your relationship with your users locally. We do not manage this complexity, therefore if you need it, you need to manage it yourself. You can off-load the entire authentication to Identity +, but as a bare minimum, you will need to store a user name to differentiate between your users and unknown visitors. The line between these two gets somewhat blurred within the context of Identity +, though, and from now on, will have to count three categories: those that are truly unknown, those that are known because they have an account with your service, and those that are not known but have an Identity + certificate. While these latter users remain anonymous, you are going to have access to valuable information about them through identity + which will help you make your service safer. If you need to contact your users, you will also need to keep the contact information of your users. The Identity + system is extremely privacy conscious and does not divulge any personally identifiable information about the user.

Single-Sign-On (SSO) Mode

In case you opt for a single sign on, rather than adding another layer of authentication, there is no need to store a password or any other secret within your system. This is a convenient choice for the cases when there is no need for better security or there isn't sufficient expertise or resource for on-premises credential management. The Identity + is a two factor authentication system in itself, it will require the use of a certificate, which locks the account onto the users devices and a pin / password should the user chose to have one or for idle accounts. This is many times more secure than any locally managed password-only based system can provide.

Multi-Factor Mode

Whether chose to off load the identification of the user to Identity + (SSO mode) or you add your own factor of authentication, the implementation is very similar. In fact the Identity + part of it is the same, the only difference would be that after the Identity + authentication, instead of the application you will redirect your user to your second factor of authentication. A password based authentication does not bring too much value, as Identity + is already checks for a password, a different token based or out of band authentication can add to the security of your system. The order of the authentication cannot be reversed. Identity + will inevitably come first, because it operates on TLS (transport level), lower than any authentication mechanism in place today, so it is would not make sense to reverse the order.

The principle behind this is extremely simple. When you get a visitor, that you intend to log in, you need to issue a call to Identity + before you perform any other login operation. The Identity + service will verify the user's identity, and its relationship with your application which from your standpoint can end in two ways:

  1. This visitor is linked with one of your users, in which case the previously associated user's unique id is returned to you.
  2. In this case, there is no local user linked with this identity+ account, this user is foreign to you and a registration must be performed on your site.

Both cases are extremely simple, but they will be treated separate for the cases when you operate on https, or simple http.

HTTPS Based Certificate Detection

This is by far the better case when it comes to security and the flow of process, because in this scenario you can have access to your visitor's Identity + certificate and the communication between your service and the Identity + service is done via the backend API alone and so there is no need for any redirects, provided the user has an Identity + certificate installed. If the user has a valid certificate, it will walk through the Identity + authentication seamlessly, you will receive it's local user id and it can be logged right in. This needs to be re iterated, there are no cookies involved, no java script and no redirects. Should you chose to perform second factor authentication locally every time, or for certain places you can do that without interference with the Identity + api, but by that point you will already know the Identity + of your visitor.

HTTPS Early Stage Detection

There is a third situation to the earlier enumeration, which is only available to HTTPS operating mode, but which is very important aspect of identity + and needs to be mentioned separately.

We've mentioned before that users may come to your site that are not logged in and they land on a public page which is not subject to authentication, but the user does have an Identity+ certificate. In case you operate on HTTPS mode and have access to this certificate, you should issue a silent request to identity +. We call this silent because, you may choose not to enforce it, meaning that if the certificate is for any reason invalid or needs validation (Identity + 2nd factor authentication), you do not go through with a redirect, but rather treat it as a semi-known visitor. It may even be the case that this visitor has an account with your service, therefore if the certificate is not expired or revoked you will have what we call an early stage detection, because you will have access to the identity of your user as the first thing in your application.

Identity + Based Session Tracking

Because the client certificate is available at every level (by the time you are in application layer, which is where all the code works), you can choose to enable session tracking using the user identity rather than relying on cookies. This has several advantages both as a security measure, because cookies are vulnerable to theft by javascript, but also in dynamics. Cookies are browser dependent, the identity + session on the other hand is device agnostic. Regardless of the device the user is connecting from, you will receive the same local user id back, therefore you can have sessions that span all devices of the user. The user can start doing things on his or her desktop and then continue it on the mobile seamlessly.

On some programming platforms, if you track the session based on user id, you need to disable the automatic cookie based session and implement custom session management. This can have several performance benefits as it gives you better control over the sessions which are the biggest RAM consumers in a web application.

HTTP Certificate Identification

This functionality is applicable only for the situation when the server runs HTTP, you are unable to import the Identity + certificates into your trust store or when for any other reason you cannot detect identity + client certificates. If this is not the case, please skip to the API Methods directly.

If this is your case, you can employ the Identity + redirect Legacy Detection API, to detect the Identity + id certificate of the visitor, which consists in a single redirect. Unfortunately, it is impractical to use this method for all visitors, therefore this method should only be used when a log in is imminent, to avoid unnecessary redirects for users that do not have an identity + certificate and they do not wish to sign into your service either. If you still wish to detect the certificate for every user, we recommend you do it asynchronously, using an iframe, which is slightly more complicated but it avoids annoying redirects.

While it introduces an additional redirect, this detection method is reliable and secure. The Identity + system uses PKI for redirects as well, therefore you can have the certainty that the response can only come from Identity + and nowhere else.

Legacy Certificate Detection Request

To obtain the anonymous identifier from the client certificate when you are unable to ready certificates yourself, we need to redirect the user to an Identity + endpoint which reads the certificate if any, and returns the anonymous id in a redirect response. Both the request and the response will be encoded as url parameters, therefore there are some limitations when it comes to size;

----------> your page -----> redirect to Identity + api ----+
	                                                    |
your page with id in parameter <-------- redirect <---------+                        

In Identity +, all redirects use PKI for security reasons, therefore while simple, you will need to perform the following steps in the correct order

  1. Create a redirect request JSON construct, see below.
  2. Transform it to bytes using UTF-8 encoding
  3. Encrypt the bytes with your API Client Certificate's private key. Remember, we do not have your private key, we will use your public key to decrypt the message. Since this is not a typical public / private key scenario, in the senses that only we know your public key, the communication between us remains safe.
  4. Transform the resulting bytes to a string using Base64 URL Encoder to form the ${resulting payload} of the request
  5. Put together the redirect URL and redirect the user, see below;

Redirect request

    {"Redirect-Request":{
        "return-url":"${return url}",
        "salt":"${salt}"
    }}
  • Return URL: The URL you wish to return to in case of success. We recommend this be the landing URL (query included if necessary).
  • salt: 6 to 10 characters of random data. This field does not carry any valuable information, it is only meant to alter the outcome of the encryption in case there are two requests with the same meaningful content. This makes cracking encryption keys a lot more difficult in case somebody is monitoring traffic.

redirect url

The URL's you redict to must have the following format and parameters:

	https://api.identity.plus/anonymous-id?api=${api certificate sn}&payload=${resulting payload} 
  • End Point: https://api.identity.plus/anonymous-id
  • API Certificate SN: The serial number of your API certificate. You can extract it from the certificate and it is a decimal representation of the integer number found there, not the regular hexadecimal representation.
  • payload: the payload obtained from the previous process

They are a few rules that apply to redirect URL's:

  • The redirect url must have the same domain as the domain your api is registered with.
  • The redirect url may contain a query string but it cannot be too long, you should only store a local state id rather than entire data sets, as both encryption and base 64 encoding will inflate the original text considerably.
  • The resulting URL, signature included cannot be longer than 2000 characters, this is a limitation imposed by some browsers and this is the reason for the previous rule as well.

The validity of the identity + certificate is not verified at this step, you will need to issue a verification API request once the anonymous id has been obtained.

Legacy Detection Response

The response will arrive as encrypted JSON object embedded in an url parameter having the following construct.

{"Anonymous-ID":{
    "outcome":"OK 0103 Identity Plus certificate found via legacy method",
    "anonymous-id":"${anonymous id}",
    "salt":"${salt}"
}}
  • Anonymous ID: The URL you wish to return to in case of success. We recommend this be the landing URL (query included if necessary).
  • salt: 6 to 10 characters of random data. This field does not carry any valuable information, it is only meant to alter the outcome of the encryption in case there are two requests with the same meaningful content. This makes cracking encryption keys a lot more difficult in case somebody is monitoring traffic.

In case no certificate was detected, the response will be a simple response object (see Simple responses), and if any other error occurred there will be no redirect. For convenience a JSON response will be displayed in the browser.

Because Identity + sends the response PKI encrypted, you will need to perform the following steps in the correct order to obtain the response. Essentially, it is backwards with what we did for the request.

  1. Get the idp-api-response parameter from the request, which will be appended to your designated redirect URL
  2. Transform it to bytes using URL Base 64 Decoding
  3. Decrypt the bytes with your API Client Certificate's private key. Remember, we do not have your private key, so we use your public key to encrypt the response. Since we are the only ones to know your public key, you can be certain the response comes from us.
  4. Transform the decrypted bytes to String using UTF-8 encoding
  5. Parse the resulting string into JSON object and get the response.

API Methods

Client certificate based authentication is extremely powerful method of authentication. It is more powerful than any other form of authentication, because it resides a level lower, at connection level, rather than application level. This is why, the Identity + service, can, and needs to be your first form of authentication. The SSL client certificate is presented right at the moment of first contact between the visitor's browser and your server, so should you choose to deny connection to a user that does not have an Identity+ certificate, you can simply cut the connection without any further communication. This makes your application impenetrable basically because the visitor is unable to send a single bit of data to your system after that.

However, because the certificate is anonymous, in respect of people's privacy, once you obtained the client's anonymous id, you will have to issue an API request to Identity + to find out to which of your user's it belongs to, if any. You can perform this request asynchronously, however, since it is an extremely low latency communication (we only transfer a small amount of data), and because it only needs to be perform once per session, we recommend you do this synchronously. That way by the time you give your visitor your first byte of data you already know something about him, potentially his local user. This reduces your exposure to potentially malicious visitors, who come without a valid Identity + certificate, such as would be the case of a DOS attack.

Should a rejection be the case, instead of bytes you can return 404 or 500, or a 300 redirect to an off site, and the HTTP connection to your critical infrastructure will be destroyed, again without exchanging a single bit of data. To be able to perform this redirect or rejection it is important that your http response stays uncommitted, so you need to perform this check before everything, right after configuration.

Validating A Certificate

To perform this operation, as a first line of business in your code, before committing the http response, you need to:

  • Obtain the Client Certificate.
  • Verify the certificate against the Identity + public certificate. If you only have the Identity + public certificate in your server's trust store this operation is redundant, because the validation has already been made before you even see the connection, but just in case, it is prudent to perform it.
  • Obtain the Certificate Subject
  • Analyze the subject name components
  • The single C filed will always be set to "Identity + Anonymous Certificates" for ease of identification
  • The OU fields will contain additional validation points for certificate. The protocol is not included but it is always https://
  • The single CN (common name) field will contain the Identity + anonymous identifier
  • The single O (organization) filed will always be "Identity +"
  • Get your active client certificate from (memory cache, database or disk)
  • Using your SSL API certificate, issue an HTTPS API request to the identity + validation url

The API request will be wrapped as an HTTP GET request with a JSON formatted content:

URL: https://${validation url}/${api version}
Request Type: GET
Content-type: application/json
Encoding:UTF-8
Content:
    {"Identity-Inquiry":{
        "anonymous-id": "${anonymous identifier}"
    }}

For Example if the Certificate Subject is this: "C=Identity + Anonymous Certificates, CN=TEST-TEST-TEST-TEST-TEST-U3VZ2-UBOYG-54SXT-HVA8X-LYQM3, O=Identity +, OU=api.identity.plus

  • Validation url: https://api.identity.plus/v1
  • Anonymous Subject: "TEST-TEST-TEST-TEST-TEST-U3VZ2-UBOYG-54SXT-HVA8X-LYQM3" (the CN value in the example above)

There is no need to add any other information to the request. Since you used your client certificate to communicate with Identity +, there is no need for further client ID or secret. The API certificate is your ID, it contains all the information necessary to bind the communication to your Identity + API account, and the designated domain. The communication between you and the server is conducted over dual authenticated https and therefore completely private

Identity Profile Response

This is the response returned for most operations unless there are problems with the verified identity or the operation performed. Whether this is an identity verification or an update to the identity, the system will answer back with an up to date version of the Identity + Profile.

If there is a local user within the given domain, associated to the identity + account to which the verified id belongs, this will be returned in the response, which also comes JSON encoded. So let us treat this case first as it is the simplest one.

Content-type: application/json
Encoding:UTF-8
Content:
	{"Identity-Profile":
	    "outcome":"OK 0002 Subject anonymous certificate valid and user uid associated",
	    "local-user-id":"my-local-user-id",
	    "trust-sponsors":[
	        "www.example-mail-service.com",
	        "www.example-on-line-shop.com",
	        "www.example-bank.com",
	        "etc."
	    ],
	    "sites-frequented":4,
	    "average-identity-age":474,
	    "max-identity-age":956,
	    "trust-score":2.09,
	    "intruder-score":0.00,
	}}
  • Request outcome: A machine reference code followed by a human readable message for convenience. Please see all outcomes here.
  • Local User ID: When a local user id was previously associated to this identity the id will be returned.
  • Local User Secret: When a secret was previously associated to this identity for this local user it will also be returned.
  • Trust sponsors: A list of other sites the Identity + account is associated to. This list is hand picked by the visitor (owner of the Identity + account) from his total list of sites. If a site is there, it means the user has an account on that site, but if the list is empty it could mean the user does not wish to advertise his presence on any sites. When a local user is associated, the field will always be returned even if it is empty.
  • Sites Frequented: Total number of sites this identity has an account with
  • Average Identity Age: This will tell you the average age of these accounts
  • Maximum Identity Age: This will tell you the maximum age of these third party accounts, not the age of the Identity + account.
  • Trust Score: This is a normalized score calculated based on the trust score reported by each site. Please see normalization in the Annexes section to see how this is calculated.
  • Intruder Score: This is a normalized score calculated based on the intrusion reports collected from each site. Please see intrusions analysis for more explanation at the Annexes section.

Valid Certificate With No User Associated

In case there is no prior association of user, the server will only return the status of the anonymous certificate, which in this case is valid. The associated user field and the user secret are not sent in this case, considering that there is no user to send. However, the reputation of the account is sent along in the response.

  • Outcome: OK 0001, The code corresponding to this situation.
  • All the other fields from the "Valid certificate with user associated Response" case except for the local user id and local user secret, which are missing

This situation essentially means that your visitor is an unknown individual, but one that bears a valid Identity + certificate, potentially with some reputation. This visitor may very well be a total stranger, a one time visitor whom you do not wish to log in, it could be a potential new member, or an existing member whom you did not yet associate with his or her Identity + account. Based on your application you can ignore the visitor, perform a new user registration (sso case), or try to log in the user the classical way and associate the existing user (if any) with his or her identity + account.

Simple Responses

For actions that do not return a profile response, such as an error or validation issue, the response will contain a simple outcome tat contain only the response code and the human readable message for convenience. With the exception of the Legacy HTTP Identity Detection Response, which is not used in the case of an HTTPS system, these are the only two response types Identity + will return.

Content-type: application/json
Encoding:UTF-8
Content:
    {"Simple-Response":{
        "outcome":"PB 0003 Identity Plus anonymous certificate needs validation"
    }}
  • Request outcome: A machine reference code followed by a human readable message for convenience. Please see all outcomes here.

Associating Local User With Identity + Account

Identity +, is an anonymous system. It will supply no personal information about the individual visiting your site, it only supplies the association between this visitor of yours and his personal devices, which are linked with SSL client certificates to his or her Identity + account. Therefore, if the visitor comes with a completely new device, one that was never used with your site, but one that has an Identity + client certificate, you will still receive the user id just as if he or she visited you with the original device. The abstraction is done on the Identity + site and you will receive back the user you associated with this identity. This way you can lock out from this user's account any device that is not linked with the given Identity + account, supplying your users with unprecedented security.

However, if the identity + account is not associated with one of your users you need to perform an association first. You can chose one of the options mentioned before:

  • Log in and associate: If you already use an authentication system, be that local (password or token) or as a service (like OAuth or OpenID), you can walk the user through his regular log in and upon success, issue a user association request to Identity +.
  • Off load authentication to Identity +: If you are not already use an authentication system, and you opted for Identity + SSO solution you can simply perform a new user registration: Create a random local user id in your database, and trigger the association with that user same way as in the previous step. Essentially, you simply skip the local authentication. Later whatever information you gather form your user, you associate it in your database with this random id, because whenever the user visits you with his or her identity + certificate, you will receive this id as reference.

Once you do have the user id you want to associate this identity + id with, you need to issue the association call to Identity+.

URL: https://${validation url}/${api version}
Request Type: PUT
Content-type: application/json
Encoding:UTF-8
Content:
    {"Local-User-Information":{
        "anonymous-id": "${anonymous identifier}",
        "local-user-name": "${uid}",
        "local-user-age":"${days}",
        "tokens-of-trust":"${count}"
    }}
  • We have a PUT request, you will be storing stuff in the Identity+ system
  • Validation url: https://api.identity.plus/v1
  • Anonymous Id: Is same as before, the CN value from the example anonymous certificate subject, It will of course be different for each user: "TEST-TEST-TEST-TEST-TEST-U3VZ2-UBOYG-54SXT-HVA8X-LYQM3")
  • Local User Name: Is a unique identifier for your locally stored user. In respect of user's privacy we recommend you do not use personally identifiable elements here. User name, email address, while all unique and frequently used to uniquely identify users in the database, they may constitute violation of privacy. We recommend you use a random string, or a numeric record id, or some other unique element, but which does not contain any personal information of your local user
  • Local User Age: How many days since this user registered at your site. In case of SSO this will be zero.
  • Tokens Of Trust: You may want to give an initial tokens of trust to this user for every good deed (good comment, purchase, blog post, bug report, etc.) the user has performed on your site so far. For simplicity, since this is a historical value, we will consider this a sum of all the deeds with each deed being 1. To see how tokens of trust points are calculated and normalized please refer to tokens of trust normalization in the Annexes section.

As a response, the system will return an updated profile response, containing the newly associated local user id, or an error if this identity + account is already associated with a local user.

Placing an off-site secret

The Identity + system allows you to associate an off site secret for your accounts. This could be a password, an encryption key or any other information you wish to store in a different place than your system for security reasons.

URL: https://${validation url}/${api version}
Request Type: PUT
Content-type: application/json
Encoding:UTF-8
Content:
    {"User-Secret":{
        "local-user-name":"my-local-user-id",
        "secret":"${some secret}"
    }}
  • We have a PUT request, you will be storing stuff in the Identity+ system
  • Validation url: https://api.identity.plus/v1
  • Local User Name: Is a unique identifier for your locally stored user.
  • Secret: A sequence of characters no longer than 1024 bytes.

As a response, the system will return an updated profile response, or an error if this identity + account is not associated with a local user.

To remove a secret simply perform the call with an empty secret

Adding Tokens Of Trust

It is advisable to report back on the activity of the Identity + account on your site. This is a collaborative system and with time, this feature can oust out bots, therefore returning the benefit to you multiplied by the power of community. It is a simple asynchronous API request that you send to Identity + each time the user does something positive on your site.

URL: https://${validation url}/${api version}
Request Type: PUT
Content-type: application/json
Encoding:UTF-8
Content:
    {"Trust":{
        "local-user-name":"my-local-user-id",
        "tokens-of-trust":"${count}"
    }}
  • We have a PUT request, you will be storing stuff in the Identity+ system
  • Validation url: https://api.identity.plus/v1
  • Local User Name: Is a unique identifier for your locally stored user. No need to send the certificate any more, because at this point the API assumes you have already identified and associated the user. The reason why we use the local user name instead of the certificate is so that you are able to add tokens of trust to your members even when they are not on your site, in a delayed gratification scenario.
  • Tokens Of Trust: The number of points you wish to award the user for this one deed. Please see normalization in the Annexes section to correctly calculate how to award your users.

As a response, the system will return an updated profile response, or an error if this identity + account is not associated with a local user.

Deleting a Local User

This would probably be a rare occasion and unnecessary since you will not be charged for idle accounts even on a business plan, but just in case you need to perform proper clean-up you can disassociate a user from the identity + account.

URL: https://${validation url}/${api version}
Request Type: DELETE
Content-type: application/json
Encoding:UTF-8
Content:
    {"Local-User-Reference":{
        "local-user-name":"my-local-user-id"
    }}
  • We have a DELETE request, as you will be removing stuff from the Identity+ system
  • Validation url: https://api.identity.plus/v1
  • Local User Name: Is a unique identifier for your locally stored user.

As a response, the system will return an updated profile response, or an error if this local user is not associated with an identity + account .

Please be mindful, the Identity + API will not ask you whether you are sure you want to delete the user. For an SSO implementation you will not be able to re-associate the user if you do delete it by accident, as you will have no local information to validate the user against.

Reporting an Intrusions

Should the situation arise, sites have the possibility to report back uncivil behavior to identity +, which will be associated with the account and certificate and in more serious cases it can result in blocked certificates or accounts.

URL: https://${validation url}/${api version}
Request Type: PUT
Content-type: application/json
Encoding:UTF-8
Content:
    {"Intrusion-Report":{
	    "intruding-certificate-uid":"${intruding-certificate-uid}",
	    "severity":"${severity}",
	    "message":"${text message}",
	    "intruded-url":"${intruded-url}",
	    "intruder-ip-address":"${intruder-ip-address}",
	    "intruding-request-headers":[
		    "${http header 1}",
		    "${http header 2}",
		    "${http header 3}",
		    "${http header 4}"
	    ],
	    "additional-information":"${info}"
    }}
  • We have a PUT request, you will be storing stuff in the Identity+ system
  • Validation url: https://api.identity.plus/v1
  • Intruding Certificate uid: The id of the offending certificate. The report needs to be performed in the context of a certificate. At this point it is not unreasonable to assume that we are not dealing with an actual user but rather a bot, or a malicious entity with a stolen certificate. Therefore we are not in fact reporting on a user, but rather on a certificate. The user has the possibility to manually revoke this certificate in case he or she will suspect a certificate being compromised.
  • Severity: The nature of the user's transgression {mistake | inappropriate | intrusive | monetary-damage | material-damage | personal-damage | social-damage}. The number of intrusion points added ranges from (0) for a "mistake", which is more like a negligence on the account of the offender, to (6) for "social-damage", an action that cause damage to more than one person.
  • Message: A message to the user, no longer than 500 characters. There is no need to contact the user, the Identity + system automatically does that on your behalf and communicates the message and the intrusion event.
  • Intruded URL: The URL of the page the intrusion occurred on.
  • Intruder IP Address: The IP address of the intruding request was coming from.
  • Intruding Request Headers: The HTTP Request Headers found in the intruder request.
  • Additional Information: Any additional information you may want to associate to this intrusion, with a limit of 2048 bytes.

As a response, the system will return a profile response of the identity + account and any local user associated, if any.

This is a very important feature which if used properly can eliminate misconduct on sites. The identity + account is a powerful ally. Once linked to various accounts across the web it is very difficult and time consuming to disconnect. Because of this, it aggregates all the trust that each site invest in the individual, providing people with a reputation, which you will be informed of at first contact and which is important to them. Playing with this reputation may cost them a lot, therefore regular visitors will be unlikely to behave ungentlemanly, giving you the possibility to benefit from the trust of the community that is awarded to them. Uncivil people on the other hand will be flagged and because it is difficult to build reputation, they will be able to do very little misdeed before getting banned. This is the power of distributed trust.

Please do not abuse this feature. Only use it if it is justified. Claims of unjustified reports might be investigated and if you cannot substantiate your side of the story you may incur warnings or a sanction.

Conflict Resolution

There will be situations when the user presents inadequate certification for the your needs, be that the lack of a certificate or a certificate with issues on it. In this case we will need to resort to a redirect to the Identity + site to resolve these conflicting situations. These are very simple redirects which only contain a return url. Upon redirect, the Identity + system will detect the problem and will try to resolve it. In case the problem is resolved, the service will return the user to the specified URL, otherwise it will not. This is why it is important to make the distinction between the situation when there is no certificate (the visitor does not have an identity + account) or a certificate with issues.

No Certificate

If the visitor does not have an Identity + certificate installed and you decide to require one for the requested page, we will have to redirect the user to Identity + to acquire one. This is one of a few redirects that you need to handle. It is important to treat this situation separately because we need to ask the user whether he or she would like to be redirected (considering they are not familiar with the Identity + system). This also gives you the occasion to decide what you will do when the user returns with a valid certificate (perform a registration, or an SSO sign-up). Remember, there will be no need to subsequent redirects, as the user only comes back with a valid certificate once it leaves your site.

In Identity + all redirects contain only encrypted information for security reasons, therefore while simple, you will need to perform the following steps in the correct order

  1. Create a redirect request JSON construct, see below.
  2. transform it to bytes using UTF-8 encoding
  3. Encrypt the bytes with your API Client Certificate's private key. Remember, we do not have your private key, we will use your public key to decrypt the message. Since this is not a typical public / private key scenario, in the senses that only we know your public key, the communication between us remains safe.
  4. transform the resulting bytes to a string using Base64 URL Encoder to form the ${resulting payload} of the request
  5. put together the redirect URL and redirect the user, see below;

Redirect request

    {"Redirect-Request":{
        "return-url":"${return url}",
        "salt":"${salt}"
    }}
  • Return URL: The URL you wish to return to in case of success. We recommend this be the landing URL (query included if necessary).
  • salt: 6 to 10 characters of random data. This field does not carry any valuable information, it is only meant to alter the outcome of the encryption in case there are two requests with the same meaningful content. This makes cracking encryption keys a lot more difficult in case somebody is monitoring traffic.

The URL's you redict to must have the following format and parameters:

Redirect URL

	https://my.identity.plus?api=${api certificate sn}&payload=${resulting payload} 
  • Endpiont: https://my.identity.plus. The endpoint in this case is different than the detection endpoint which uses the API service.
  • API Certificate SN: The serial number of your API certificate. You can extract it from the certificate and it is a decimal representation of the integer number found there, not the regular hexadecimal representation.
  • payload: the payload obtained from the previous process

They are a few rules that apply to redirect URL's:

  • The redirect url must have the same domain as the domain your api is registered with.
  • The redirect url may contain a query string but it cannot be too long, you should only store a local state id rather than entire data sets, as both encryption and base 64 encoding will inflate the original text considerably.
  • The resulting URL, signature included cannot be longer than 2000 characters, this is a limitation imposed by some browsers and this is the reason for the previous rule as well.

The Identity + service will verify the validity of the redirect, will handle the certificate issue locally and upon completion will redirect back accordingly. If the signature is not valid the request will go dead. No response and no redirect will be issued. As such, there is no need for any additional information as a response, the Identity + service will simply redirect you to the specified URL with no additional parameters.

Since this is a redirect and therefore there we have diminished control, it is advisable that at that point you issue a secondary validation API request just in case. The request takes very little bandwidh and can re-assure you that the proper steps were taken to validate the certificate and nobody interfered with the procedure. If this is the case, there will be no more redirects as the certificate will have been validated upon the first redirect and so there should be no disruptions for the user.

Flagged Or Expired Certificate

In case of the flagged or expired certificate the procedure is exactly the same as in case of no certificate at all. The only difference is that in this case, the user is already familiar with the Identity + system and therefore there is no need to ask him / her about the redirect. In most cases, the redirect will be deliberately requested by the user as second factor authentication.

Again, the user will not be redirected to your site in case the certificate conflict cannot be resolved. This is considered a danger situation, which could put your site at unnecessary risk.

Revoked Certificate

This is a potentially dangerous situation. Certificates usually expire they are not revoked, so if you encounter one, this means the owner deliberately revoked it for serious reasons, such as suspected certificate compromise. It is also unlikely that the owner of the certificate continues using the certificate after being having revoked it personally, so the logical conclusion would be that the encounter of a revoked certificate is most likely a case of identity theft. A certificate being stolen or recovered from an incorrectly disposed devices and used to impersonate the rightful owner. As such we recommend you either redirect the user identity + the regular way, or you simply drop the connection with no further notice.

Annexes

Activity Diagram

Possible Return Codes

  • OK 0000 Acknowledged
  • OK 0001 Subject anonymous certificate valid
  • OK 0002 Subject anonymous certificate valid and user uid associated
  • OK 0100 Subject user successfully associated to Identity Plus identity
  • OK 0101 Subject user disassociated
  • OK 0102 Subject user updated
  • OK 0103 Identity Plus certificate found via legacy method
  • PB 0000 No Identity Plus anonymous certificate
  • PB 0001 No Identity Plus certificate found via legacy method
  • PB 0002 Expired Identity Plus anonymous certificate
  • PB 0003 Identity Plus anonymous certificate needs validation
  • PB 0004 Revoked Identity Plus anonymous certificate
  • PB 0005 Intruder Certificate
  • PB 0006 Unknown Identity Plus anonymous certificate
  • PB 0007 Crypto Failure package was tempered with
  • ER 0000 Undetermined error
  • ER 0001 Unknown request error
  • ER 0002 No such operation for object
  • ER 0003 Subject user name is already associated
  • ER 0004 Subject user name is already associated to a different identity
  • ER 0005 Subject user name was never associated
  • ER 0006 Return URL is too long
  • ER 1100 No Identity Plus API certificate presented
  • ER 1101 Unknown Identity Plus API certificate
  • ER 1102 Expired Identity Plus API certificate
  • ER 1103 Revoked Identity Plus API certificate
  • ER 1104 Number of verifiable identities exceeded
  • ER 1105 idle Identity Plus API certificate
  • ER 1106 General Identity Plus API Problem

Tokens Of Trust Normalization

You may consider giving more tokens of trust for more difficult chores (a blog post for instance that drove your traffic). No need to over do it (1 point for simple chores, 5 - 10 points for very complicated ones). The points you award to one of your users, will be veted against the average number of points you issue and that will, indicating how good you think one user is relative to all your users