FastAuthentication :: Docs

Contacting the server

The server is contacted by web application through the URI https://base/server:action/lpublic=public-token, e.g.: https://fastauthentication.org/server:book/lpublic=555-b79c58bf116303b3

Available actions are book (to book an authentication session), verify (to verify an authentication status).

The possible input formats are json and HTTP POST (UTF-8 encoded POST data).

Regardless of the format, the content must be a set of keys/values, e.g.:

json: { "key1":"value 1", "key2":"value 2", …}

Content must always include server private key with parameter name “lprivate”.
Provide it always in POST content, never use a GET parameter for it, for security reasons: POST body content is encrypted by HTTPS, and this voids also the “man-in-the-middle” attack. JSON string must be well-formed.
All properties and all non-numeric values must be quoted with the standard «"».
Unquoted keys/values or quotation performed with the single «'» will produce an error.
Content-Type is expected to be “application/json”.

“book”: Booking an authentication session

In order to book an authentication session application server must contach {{label:productName}} server.
The URL to POST is: https://base/server:book/lpublic=public-token

Parameters that can be used, with both HTTP POST or JSON POST, are:

lprivate: mandatory, the server private key
kforce: optional, defaults to false. Every non-false value (false are epty strings or “0”, typical true is “1”) forces the user to re-authenticate also if already authenticated.
lcallback: optional, the URI the client will be redirected in case of success (defaults to customer’s “lcallback” value if missing or empty)
lcallbackfail: optional, the URI the client will be redirected in case of failure (defaults to customer’s “lcallbackfail” value if missing or empty)
lre: optional, a regular expression that digital identities must match in order to be authenticated.
Defaults to customer’s “lre” value if missing or empty.
In case resulting “lre” value is missing or empty all identities are allowed.
The regex is checked against ldisplay property of the identity, see below.
Use “.*” value if you want to override a non-empty customer’s “lre” value.
Syntax is basic Perl regex, case insensitive. E.g.: "lre":"^[^@]+\@([^.]+\.)*mycompany\.(com|org|co\.uk)$"
Another example, excluding telegram and twitter: "lre":"^[^@#]".
The user will have the option to pick an authenticated identity only among the identities matching the lre.

E.g.: post to https://base/server:book/lpublic=967-badae3567f630b60 a JSON like this:

{
	"lprivate" : "dcdd5e57e888ac904dc009d18c1ea89c59889c3e68bfb3f7",
	"lcallback" : "http://mycompany.com/myapp/auth.php?type=success",
	"lcallbackfail" : "http://mycompany.com/myapp/auth.php?type=failure"
}

JSON POST must use a Content-Type «application/json», UTF-8 encoded.

Or the equivalent HTTP POST:

lprivate=dcdd5e57e888ac904dc009d18c1ea89c59889c3e68bfb3f7&lcallback=http%3A%2F%2Fmycompany.com%2Fmyapp%2Fauth.php%3Ftype%3Dsuccess&lcallbackfail=http%3A%2F%2Fmycompany.com%2Fmyapp%2Fauth.php%3Ftype%3Dfailure

In case lpublic/lprivate keys mismatch an HTTP 401 error is returned.

If the booking process is succesful (server public/private keys match), the response will be a JSON like this:

{
	"client" : {
		"auth" : "authentication-URI",
		"reauth" : "authentication-URI"
	},
	"server" : {
		"verify" : "verification-URI",
		"append" : "parameter-name"
	}
}

The meaning is:

response.client.auth is the URL user’s browser should be redirected
response.client.reauth is the URL user’s browser should be redirected to force re-authentication.
If «kforce» was requested in booking parameters then re-authentication will be always used.
response.server.verify is the URL your server should call to verify authentication.
Appending to this URL the value of parameter name response.server.append which is returned by user’s browser at “lcallback” URI.
response.server.append is the name of the parameter returned by user’s browser at “lcallback” URI.
Such parameter value that should be appended to response.server.verify for verification.

Currently response.server.append is normally valued “lauthsession”.
In case you want to skip holding the temporary response from book process you can assume this value to be static.
It will vary only in case your “callback” URI contains yet an “lauthsession” GET parameter.

Once the authentication session has been booked redirect user’s browser to the appropriate response.client.auth or response.client.reauth URL, e.g.: https://base/auth:index/ltoken=token

Authentication session has a maximum duration of 5 minutes.

About “lcallback”

Once tha authentication process is complete, user’s browser will be sent to customer’s “lcallback” URI.
It will be a GET request, added with the “lauthsession” parameter.

“lcallback” parameter can be declared at “book” level, if not it will default to “lcallback” parameter defined at customer level.

The “lcallback” parameter is a string representing a complete URI.
Starts with protocol (hopefully “https”), can use GET parameters as well as an “#” part.
At user redirection a parameter is added for “lauthsession” code.

Customizing “lcallback” URI

There is the option to use the literal text “{{token}}” within “lcallback” string to identify auth-session-token.
In this case response.server.append is valued “{{CustomURI}}” and no longer used, while the “lauthsession” value replaces “{{token}}” text in callback URI without any other consideration.
This syntax allow the parameter to be part of URI, GET parameters as well as of “#” hashmap, e.g.:

"lcallback":"https://mycompany.com/register.php?fastauthValue={{token}}"
"lcallback":"https://mycompany.com/myapp/#returnedSession:{{token}}"
"lcallback":"https://mycompany.com/cgi/startsession/{{token}}/"
"lcallback":"http://register{{token}}.mycompany.com/dns-ops/startsession/"

The value of the token will be the “lauthsession” value necessary to verify the actual authentication.

“verify”: Verify the success of an authentication session

Once authentication process is over, if succesfull user’s browser will be redirected to customer’s application server at the “lcallback” URI.

Content must include server private key with parameter name “lprivate”.

The “lauthsession” parameter will be added (GET) to such URL, this parameter is named in response.server.append described above (in «book»).
Append such parameter value to response.server.verify URL returned by «book» process and issue a POST request to verify the actual authentication.
The resulting URL to POST will be something like: https://base/server:verify/lpublic=public-token/lauthsession=auth-session-token

Currently book’s response.server.append is normally valued “lauthsession”.
In case you want to skip holding the temporary response from book process you can assume this value to be static.
It will vary only in case your “callback” URI contains yet an “lauthsession” GET parameter.

It’s mandatory to add the “lprivate” parameter valued with your server’s private key.
You can use json or HTTP POST (UTF-8 encoded POST data) to add it.

Optionally HTTP POST data or JSON POST data could also contain the “lauthsession” pair key/value, in this case it’s not necessary to report it in URL. E.g.:

URL: https://base/server:verify/lpublic=public-token

HTTP POST data: lprivate=lprivate server key&lauthsession=lauthsession token
or
JSON POST data: {"lprivate":"lprivate server key","lauthsession":"lauthsession token"}

JSON string must be well-formed.
All properties and all non-numeric values must be quoted with the standard «"».
Unquoted keys/values or quotation performed with the single «'» will produce an error.
Content-Type is expected to be “application/json”.

The response will be a JSON like one of these:

{
	"status":"success",
	"authenticated": {
		"ldisplay":"identity string",
		"lidentity":"identity details",
		"ltype":"id-type, e.g: email"
	}
	"verifiedby": {
		"ldisplay":"identity string",
		"lidentity":"identity details",
		"ltype":"id-type, e.g: email"
	}
}

{
	"status":"failure",
	"error":"description"
}

The «error» key is included always and only in case of authentication failure.

The «authenticated» and «verifiedby» keys are included always and only in case of authentication success.

“authenticated” is the identity the user has choosen to use
“verifiedby” is the identity he used to perform actual authentication (they could differ).

Both «authenticated» and «verifiedby» are valued with:

“ldisplay” property: the actual user’s authenticated digital identity,
e.g.: user’s email address, “@telegramName” or “#twitterScreenName”
“lidentity” property: identity details (e.g.: “twitter:numeric id@screen name”)
“ltype” property: the type of identity (“mail”, “twlegram”, “twitter”)

In both cases more informations could be included.

In case of error additional fields could be used for debugging, while in case of successful authentication you could have:

{
	"status":"success",
	"authenticated": {"lidentity":"identity","ltype":"id-type, e.g: email"},
	"name":"Person name, e.g.: John Doe",
	"alt":[
		{"lidentity":"identity","ltype":"id-type, e.g: email"},
		{"lidentity":"identity","ltype":"id-type, e.g: email"}
	],
	"xFastAuthentication":{
		"authID":"UUID",
		"personID":"UUID"
	}
}

Optional additional properties are:

name: the display name of the authenticated person, if defined.
The value of the name is provided by user.
alt: an array of additional/alternative verified identities of the same person, if any.
In case your web application cannot accept the authenticated identity it’s up to you to decide whether you want to crawl alternative identities to see if you can match an acceptable one.
The authenticated user can decide which identities can be shared among the authenticated identities belonging to him/her.
xFastAuthentication: fields belonging to the set of {{label:productName}} system(s):
- authID: the distinguished ID identifying the “authenticated” identity in {{label:productName}} system(s).
- personID: the distinguished ID identifying the person (if any) in {{label:productName}} system(s).

All the additional/alternative identities provided with “alt” have been verified.
In case your web application cannot accept the authenticated identity it’s up to you to decide whether you want to crawl alternative identities to see if you can match an acceptable one.

“pushid”: Push a custom ID for authenticated user

Once a user is authenticated customer’s web application server can “push” on the authenticated person profile a custom ID.

This can be done by POSTing to URI https://base/server:pushid/lpublic=public-token/ a JSON like this:

{
	"lprivate":"server private key",
	"lauthsession":"auth-session-token",
	"jidentity":{
		"lidentity":"your custom ID",
		"ltype":"Your custom type"
	}
}

The custom identity will be associated to the user in session
Identities are unique. In case the same custom identity is already associated to some user (including the same user) the request will fail
The custom identity will be only available for this user with the same customer
The custom identity will be available on the next user authentication
All fields in JSON are mandatory except jidentity.ltype, which defaults to “custom”

In order to associate an authenticated user to a custom identity, you could:

Book the authentication
Send the user to authentication
Verify the authentication

In case the verification doesn’t report a suitable ID you can desume from “authenticated” or “alt”, you can:

Push the custom ID on the session
Verify again authentication

The response of second verification will include in “alt” array the custom identity, without a new authentication for the user.

Beware of custom IDs: in case the custom ID string is the same of another authentication (e.g.: an email) then you’re opening a security breach: someone could authenticate with the same ID, and act as the authenticated person with your server.
Always use a custom ID that cannot be confused with a “regular” authentication, e.g.: “username#appname.company”.

{{label:productName}} :: Docs :: Server

{{label:productTagline}}

Documentazione lato server

Server documentation