Managing Tokens

Listing Authentication Tokens

In order to list your active authentication tokens, perform a GET on the token path using an existing authentication token or using HTTP basic authentication to validate the request.

GET http://{domain}/.TOKEN/?format=json 
Cookie: token=d9f8378f71e79b77831f65d9e6891af6

HTTP/1.1 200 OK 
Gateway-Request-Id: F48303758301E570
Castor-Object-Count: 3 
Content-Type: application/json; charset=utf-8 
Content-Length: 651
[
  {"x_token_domain_meta":"{domain}", "x_owner_meta":"john",
   "last_modified":"2012-06-22T05:39:44.854100Z", 
   "lifepoint":"[Sat, 23 Jun 2012 05:39:44 GMT] reps=2,[] delete", 
   "name":"7e742e12fb7e070b44266df1a1bf2efe"},
   ...
]

GET http://{domain}/_admin/manage/tenants/tenant256/tokens/
Authorization: Basic Z2NhcmxpbjpmdW5ueQ==

Removing an Authentication Token

In order to logout and remove an authentication token, perform a DELETE on the full token path and authenticate the request with a token or with HTTP basic authentication.

DELETE http://{domain}/.TOKEN/53dfb96dc6d5b9cacd174e3649cba6d5
Cookie: token=22f57e203c10cf86d2dfd9564b1413f5

DELETE http://{domain}/_admin/manage/tenants/tenant256/tokens/53dfb96dc6d5b9cacd174e3649cba6d5
Authorization: Basic Z2NhcmxpbjpmdW5ueQ==

If you delete a token and use the same token that you are deleting to authenticate the request, the Gateway will return a Set-Cookie header to clear your token. This is useful when implementing logout pages for web browsers.

DELETE http://{domain}/.TOKEN/53dfb96dc6d5b9cacd174e3649cba6d5
Cookie: token=53dfb96dc6d5b9cacd174e3649cba6d5

HTTP/1.1 200 OK
Gateway-Request-Id: 9855371AA8411781
Set-Cookie: token=; path=/
Content-Length: 0

Clearing Tokens for Locked Accounts

Because identity management systems are poor at signalling that an account has been locked, Gateway allows unexpired tokens to continue to work for locked accounts. For a removed account, the token will stop working as soon as it expires from cache.

However, for an account that is expired (locked) but not removed, extra measures are needed to ensure that its tokens stop working:

PAM Authentication:

This method is for those using a PAM as a front-end for traditional Unix authentication.

1. Lock the user account by change the password: passwd -l USERNAME
2. Change the username: zzzUSERNAME

LDAP Authentication:

1. Standardize an attribute within one of the schemas that apply to the user record for which enabled user accounts will always have set to a known value. 

2. Design a test for the value. 

   Tip

   Although you can use a negative test to find disabled accounts, there is less risk of mistakes with the affirmative method (attribute is value).

   For example, you can use the pwdPolicy schema with the pwdLockout attribute and use the userFilter to require the pwdLockout attribute to be true.

Token Examples

The token administrator defined in the root IDSYS configuration file is allowed to use the x-owner-meta argument in order to perform token listing for any user. Administrators wishing to disable a user account and log them out of the system can do so by locking their LDAP account and then removing any existing authentication tokens for that user.

The following examples show how the token administrator lists and deletes another user's tokens.

Token administrator superuser@admindomain.example.com listing the authentication tokens for user john:

GET http://{domain}/.TOKEN/?format=json&x-owner-meta=john 
Auth: superuser@admindomain.example.com:superpassword

HTTP/1.1 200 OK 
Gateway-Request-Id: 29172D0FDCAB19DE
Castor-Object-Count: 1 
Content-Type: application/json; charset=utf-8 
Content-Length: 221
[
  {"x_token_domain_meta":"{domain}", 
   "x_owner_meta":"john",
   "last_modified":"2012-06-24T07:14:53.671600Z", 
   "lifepoint":"[Mon, 25 Jun 2012 07:14:53 GMT] reps=2,[] delete", 
   "name":"b71805b6c862860bfed892c653cbc4b5"}
]

Using the tokens discovered during the listing operation, the token administrator then issues deletes for each of the tokens in exactly the same way the user deletes their own tokens.

DELETE http://{domain}/.TOKEN/b71805b6c862860bfed892c653cbc4b5 
Auth: superuser@admindomain.example.com:superpassword

HTTP/1.1 200 OK 
Gateway-Request-Id: 4628361DE8318726
Content-Length: 0

Notice that the token administrator lists tokens the same way any user does and is able to specify an arbitrary user with the x-owner-meta query argument. The delete operation is the same pattern whether performed by the user or the token administrator.