Session Namespace
The Session namespace allows API clients to manage session tokens
including creating, deleting and obtaining information about sessions.
- The Session.create command creates session token in exchange
for another authentication token.
- The Session.delete command
invalidates a session token.
- The Session.get retrieves
information about a session token.
The call to the Session.create command 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 Session.create command. The Session.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 Session.create command. 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 Session.create command to exchange a
SAML token for a API session token. A session ends under the following
circumstances: - Call to the Session.delete command.
- 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 Session returns the following errors: - Unauthenticated error
for any errors related to the request.
- ServiceUnavailable error
for all errors caused by internal service failure.
List of commands:
Create Command
dcli com vmware cis session create
Description
Creates a session with the API. This is the equivalent of login. This
command 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.
Example
dcli com vmware cis session create
Delete Command
dcli com vmware cis session delete
Description
Terminates the validity of a session token. This is the equivalent of
log out.
A session identifier is expected as part of the request.
Example
dcli com vmware cis session delete
Get Command
dcli com vmware cis session get
Description
Returns information about the current session. This command expects a
valid session identifier to be supplied.
A side effect of invoking this command may be a change to the session's
last accessed time to the current time if this is supported by the
session implementation. Invoking any other command in the API will also
update the session's last accessed time.
This API is meant to serve the needs of various front end projects that
may want to display the name of the user. Examples of this include
various web based user interfaces and logging facilities.
Example
dcli com vmware cis session get