com.vmware.cis.session

The session service allows API clients to manage session tokens including creating, deleting and obtaining information about sessions.

  • The create operation creates session token in exchange for another authentication token.
  • The delete operation invalidates a session token.
  • The get retrieves information about a session token.

The call to the create operation is part of the overall authentication process for API clients. For example, the sequence of steps for establishing a session with SAML token is:

  • Connect to lookup service.
  • Discover the secure token service (STS) endpoint URL.
  • Connect to the secure token service to obtain a SAML token.
  • Authenticate to the lookup service using the obtained SAML token.
  • Discover the API endpoint URL from lookup service.
  • Call the create operation. The create call must include the SAML token.

See the programming guide and samples for additional information about establishing API sessions.

Execution Context and Security Context

To use session based authentication a client should supply the session token obtained through the create operation. The client should add the session token in the security context when using SDK classes. Clients using the REST API should supply the session token as a HTTP header.

Session Lifetime

A session begins with call to the create operation to exchange a SAML token for a API session token. A session ends under the following circumstances:

  • Call to the delete operation.
  • The session expires. Session expiration may be caused by one of the following situations:
    • Client inactivity - For a particular session identified by client requests that specify the associated session ID, the lapsed time since the last request exceeds the maximum interval between requests.
    • Unconditional or absolute session expiration time: At the beginning of the session, the session logic uses the SAML token and the system configuration to calculate absolute expiration time.

When a session ends, the authentication logic will reject any subsequent client requests that specify that session. Any operations in progress will continue to completion.

Error Handling

The com.vmware.cis.session returns the following errors:

create

POST /com/vmware/cis/session
POST /com/vmware/cis/session?~action=create

Creates a session with the API. This is the equivalent of login. This operation exchanges user credentials supplied in the security context for a session identifier that is to be used for authenticating subsequent calls. To authenticate subsequent calls clients are expected to include the session key.
Request:
Representations:
POST /com/vmware/cis/session

Parameters:
None

Response:
Representations:
{
    "value": "secret string"
}
<?xml version="1.0" ?>
<ns0:Create-Result xmlns:ns0="http://vmware.com/cis/session" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <value>secret string</value>
</ns0:Create-Result>

Parameters:
Name Type Required Description
result secret Yes Newly created session identifier to be used for authenticating further requests.

Errors:
Type Description HTTP Status Code
unauthenticated if the session creation fails due to request specific issues. Due to the security nature of the API the details of the error are not disclosed.

Please check the following preconditions if using a SAML token to authenticate:

  • the supplied token is delegate-able.
  • the time of client and server system are synchronized.
  • the token supplied is valid.
  • if bearer tokens are used check that system configuration allows the API endpoint to accept such tokens.
 401
service_unavailable if session creation fails due to server specific issues, for example connection to a back end component is failing. Due to the security nature of this API further details will not be disclosed in the error. Please refer to component health information, administrative logs and product specific documentation for possible causes. 503

Copyright © 2014. All Rights Reserved.