Description

The VerifyCredentials API can be called to verify User's (or Account Owner's) credentials by simply checking the request's signature, to generate a unique token that can be used to identify a user or to renew an existing user token.

What is a Token?

In apstrata, all requests must be authenticated. There are three methods for authenticating apstrata requests:

1. Default signature: This is the most secure method of authentication because it requires hashing all content of a request along with the secret of the account or the password of the user and then sending the hash. (read more)

2. Simple signature: This is the easiest method of authentication. It requires hashing a few select parameters along with the secret of the account or the password of the user and then sending the hash. It is recommended for testing and for applications that do not have access to all parameters, like files, in a request. (read more)

3. Token-based authentication: This is the recommended method of authentication for applications that make most requests with apstrata users, as opposed to owners, for use with SSL encrypted connections over HTTP POST. It provides a similar experience to sessions since a Token is generated and renewed over a period of time, without the need to generate a signature for every request. (read more)

A Token can be used to authenticate a user in place of a signature. This allows the creation of applications that do not need access to the users password which is required for signature generation. Tokens provide a layer of simplicity, but must obey the following restrictions:

1. Token-based authentication is enabled for user requests only. Owner requests must use signatures.

2. Token-based authentication is enabled under secure (https) connections only.

Tokens can be created or renewed using VerifyCredentials and can then be passed as a parameter to requests instead of the signature.

When no longer needed, Tokens can be deleted and cleared using DeleteToken

1- Validating credentials: The validation can be requested for users or account owners, to do so one needs to call the VerifyCredentials API by simply signing the request. It will return a success response if the credentials are valid and an INVALID_SIGNATURE otherwise.

2- Generating a token: Account owners are not allowed to call generate tokens, it has to be a user request sent over https. To do so, a user will have to call VerifyCredentials by signing the request and passing the parameter apsdb.action=generate. (See the table below for more information about the allowed request parameters). The token will be returned upon success.

3- Renewing a token: Account owners are not allowed to renew tokens. Token renewal can only be made through https. To do so, a user will have to call VerifyCredentials using token authentication instead of signing the request, passing his username as a parameter (apsws.user) and passing the parameter apsdb.action=renew. (See the table below for more information about the allowed request parameters). The token passed to the request will be renewed and the new token will be returned upon success.

Why use tokens instead of signatures?

Consider a site that contains more than just a single page (and signature-based authentication). A user authenticates (user/pass) on one page, and his credentials must be used to sign all his requests. All pages the user opens must have access to the password so they can sign all requests to apstrata. The password must somehow be made accessible to all pages and/or be available to the webapp (in plain text) to sign requests to apstrata. Tokens provide a viable alternative. A user requests a token and can only use it over a secure (https/post) channel. The token can be used instead of the signature for most functionality. The token can be stored in a cookie and the user's web browser will automatically forward the token with every request made - the webapp will not need to keep track of the user's password, and no client-side Javascript or cookie is required to make the token accessible by all pages of the site.

A simple way for a Javascript-enabled application to use tokens is through the Apstrata Javascript library ApstrataSDK which handles tokens with the TokenConnection class. Using TokenConnection connections ensures the proper use of tokens since it only takes user credentials once and does not store the password anywhere while still allowing the token-based session to be shared across multiple pages. The class also handles the token renewal mechanism which, by default, requires the token to be renewed every 30 minutes and invalidated every 2 hours. Successful and failed logins, logouts, and API calls are all clearly documented in code and published by this class using the Dojo publish method; this allows applications to subscribe to any event handled by the connection in case it needs to set customized functionality. An example of this is when a token is invalidated and the application needs the user to login again, then a "logout" event is published and an application can subscribe to that channel and show the login screen.

Specific Request Parameters

(Refer to Common Request Parameters)

Name	Description	Required	Default	Possible Values
apsws.user	Should be sent in case of verifying credentials of a user or generating/renewing a user token.	No
apsdb.authToken	Should be sent in case of renewing a token for a user. It contains the token that should be renewed.	No
apsdb.action	Should be sent in case of generating or renewing a user token.	No		generate/renew
apsdb.tokenExpires	Should be sent in case of generating a token. It contains the relative time in seconds after which the token expires and becomes unusable.	No	1800 seconds (30 minutes)	Relative time in seconds. It should always be less or equal to 86400 seconds (24 hours).
apsdb.tokenLifetime	Should be sent in case of generating a token. It contains the relative time in seconds after which the token cannot be renewed. After that amount of time, a signature will be needed to be able to generate a new token.	No	7200 seconds (2 hours)	Relative time in seconds. It should always be less or equal to 604800 seconds (1 week).
apsdb.bindReferrer	Should be sent in case of generating a token. It specifies if the token should be bound to the referrer.	No	true	true/false
apsdb.tokenInCookie	Should be sent in case of generating a token. It specifies if the token should be returned in a cookie in the response header.	No	false	true/false

Specific Response Elements

(Refer to Common Response Elements)

The following specific "result" element is a child of the common root element "response" and a sibling of the common "metadata" element. It will be returned only in the case where a user has asked to generate or renew a token.

{
	"result": {
		"apsdb.authToken": "hash string representing a token",
		"apsdb.tokenExpires": "token expiry time in seconds",
		"apsdb.tokenLifetime": "token lifetime in seconds"
	}
}

Note: If the apsdb.tokenInCookie request parameter is true, then the token will be returned as cookie in the response header.

Specific Logical Errors

(Refer to Common Logical Error Codes)

Error	Message	Status Code
INVALID_PARAMETER	The parameter [paramName] is not allowed in VerifyCredentials Or The parameter [paramName] can only have one value Or The parameter [paramName] is not allowed when generating a new token Or Account has enforced binding to referrer when generating tokens Or The parameter [paramReferrerName] can only be [true] or [false]	400
INVALID_REQUEST	VerifyCredentials must not be called anonymously Or Token-based authentication is not allowed for account owners Or Token-based authentication is not allowed over non-secure connections Or Token-based authentication with cookies requires a referrer to be set Or A token must be sent in order to renew	400
INVALID_ACTION	An action can only be [generate] or [renew]	400
MALFORMED_REFERER	Invalid originating referrer from the Referer header [RefererHeaderString]	400
INVALID_PARAMETER_VALUE	The parameter [paramName] must be less/greater than [paramSettingValue] Or The (Configuration) parameter [paramName] is not a valid number	400
INVALID_TOKEN	Could not find the token [token]	400
TOO_MANY_TOKENS	The total number of tokens must not exceed [tokenLimit]	400
INTERNAL_ERROR	Failed to update user tokens for user [username]	500

Examples

Sample Request to generate a token

Request URL: http://sandbox.apstrata.com/apsdb/rest/[AuthenticationKey]/VerifyCredentials?apsws.time=[timestamp]&apsws.authSig=[signature]

POST parameters:

apsws.user=john
apsdb.action=generate
apsdb.bindReferrer=true
apsdb.tokenExpires=1800

Sample Response

Success XML:

<response>
	<metadata>
		<requestId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</requestId>
		<status>success</status>
	</metadata>
	<result>
		<apsdb.authToken>1FFB2081F4E4A0680D72E469AEDB79AC</apsdb.authToken>
		<apsdb.tokenExpires>1800</apsdb.tokenExpires>
		<apsdb.tokenLifetime>7200</apsdb.tokenLifetime>
	</result>
</response>

Failure XML:

<response xmlns="http://www.apstrata.com/services/schemas/apstrata_database_response.xsd">
    <metadata>
        <requestId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</requestId>
        <status>failure</status>
        <errorCode>[errorCode]</errorCode>
        <errorDetail>[failMsg]</errorDetail>
    </metadata>
</response>

Sample JSON Response

{"response": {
  "metadata": {
    "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "success"
  },
  "result": {
    "apsdb.authToken": "51D589FE0FC258CE714242060C9CA04E",
    "apsdb.tokenExpires": "1800",
    "apsdb.tokenLifetime": "7200"
  }
}}

Sample Request to renew a token

Request URL: http://sandbox.apstrata.com/apsdb/rest/[AuthenticationKey]/VerifyCredentials?apsws.time=[timestamp]&apsws.authSig=[signature]