Managing Tokens

Listing Authentication Tokens

Perform a GET on the token path using an existing authentication token or using HTTP basic authentication to validate the request to list active authentication tokens.

Listing domain tokens

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"},
   ...
]

Listing tenant tokens

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

Removing an Authentication Token

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

Deleting a domain token

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

Deleting a tenant token

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

The Gateway returns a Set-Cookie header to clear the token if a token is deleted and the same deleted token is used to authenticate the request. This is useful when implementing logout pages for web browsers.

Deleting a domain token with itself

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

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

Note

The operation must be authenticated using either the token within a Cookie header or by using a valid user and password in an Authentication header with the request when using the token in the URI path. The audit log reflects the name of user that owns the token if the cookie is used or the name of the authenticated user if HTTP basic authentication is used.

Clearing Tokens for Locked Accounts

Gateway allows unexpired tokens to continue to work for locked accounts because identity management systems are poor at signalling that an account has been locked. The token stops working as soon as it expires from cache for a removed account.

Extra measures are needed to verify the tokens stop working for an account that is expired (locked) but not removed:

PAM Authentication:

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

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

LDAP Authentication:

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

Tip

Although negative test can be used to find disabled accounts, there is less risk of mistakes with the affirmative method: attribute is value.

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 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 the LDAP account and then removing any existing authentication tokens for the 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:

Discovering tokens

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 tokens.

Deleting token

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

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

Notice 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.

Best practice

Use the token administrator's credentials when accessing or deleting tokens for other users so the audit log reflects the token administrator performed the operations.