Sm_AgentApi_Login()

Programming Guides › Programming Guide for C › Guidance for the Agent API in C › Agent API Function Declarations (C) › Sm_AgentApi_Login()

Sm_AgentApi_Login()

This function performs session login and session validation.

The Policy Server authenticates user credentials during session login and validates the session specification during session validation. Whether the Policy Server performs session login or session validation depends on whether a session specification is defined in the field lpszSessionSpec of the structure Sm_AgentApi_Session_t, as follows:

If the session specification exists, the Policy Server performs session validation. During session validation, if the lpszSessionSpec field has a length, the Policy Server takes the following actions:
- Verifies that the session has not expired based on the nMaxTimeout field of Sm_AgentApi_Session_t.
- Checks the IP address.
- Verifies that the user is in the user directory and has not been disabled.
If the session specification does not exist, the Policy Server performs session login. During session login, if the session ID is specified, it will be used as the session ID upon successful authentication.

Syntax

int SM_EXTERN Sm_AgentApi_Login (
   const void*                            pHandle,
   const char*                            lpszClientIpAddr,
   const Sm_AgentApi_ResourceContext_t*   pResourceContext,
   const Sm_AgentApi_Realm_t*             pRealm,
   const Sm_AgentApi_UserCredentials_t*   pUserCredentials,
   Sm_AgentApi_Session_t*                 pSession,
   long*                                  pNumAttributes,
   Sm_AgentApi_Attribute_t**              ppAttributes
);

Parameter	I/O	Description
pHandle	I	Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().
lpszClientIpAddr	I	The IP address of the client that the user is logging from. This is an optional parameter. If the client IP begins with a star (*), the Policy Server logs the IP address but does not validate it against a session specification.
pResourceContext	I	A pointer to a resource definition structure.
pRealm	I	A realm definition structure.
pUserCredentials	I	A user credentials definition structure.
pSession	O	A User Session definition structure.
pNumAttributes	O	The number of attributes in ppAttributes.
ppAttributes	O	A pointer to an array of response attribute definition structures. This function returns the following attributes, when available: SM_AGENTAPI_ATTR_AUTH_DIR_OID SM_AGENTAPI_ATTR_AUTH_DIR_NAME SM_AGENTAPI_ATTR_AUTH_DIR_SERVER SM_AGENTAPI_ATTR_AUTH_DIR_NAMESPACE SM_AGENTAPI_ATTR_USERMSG SM_AGENTAPI_ATTR_USERDN SM_AGENTAPI_ATTR_USERUNIVERSALID SM_AGENTAPI_ATTR_IDENTITYSPEC See Remarks for information about the attributes that are set when a resource is protected by an anonymous authentication scheme.

Return Values

SM_AGENTAPI_YES. The user was authenticated.
SM_AGENTAPI_NO. The user was not authenticated.
SM_AGENTAPI_CHALLENGE. A challenge is required for authentication.
SM_AGENTAPI_NOCONNECTION. The initialization was not done.
SM_AGENTAPI_FAILURE. The server could not be reached.
SM_AGENTAPI_TIMEOUT. The function timed out.

Remarks

Response attributes can be returned when authentication events occur. Both well-known and policy-based attributes can be returned, as described in Response Attributes. For example, upon successful authentication, a response could return the user’s DN.

When a resource is protected by an anonymous authentication scheme, only the following attributes are set:

SM_AGENTAPI_ATTR_USERDN. Set with the SessionID for the anonymous session.
SM_AGENTAPI_ATTR_IDENTITYSPEC. Set with the globally unique identity ticket for the anonymous session.

Supply only the required credentials (as determined by a call to Sm_AgentApi_IsProtected(), which should be called before Sm_AgentApi_Login()). Unused fields in the user credentials structure must be zero-initialized.

Sm_AgentApi_Login() returns attributes in the Sm_AgentApi_Attribute_t structure. Call Sm_AgentApi_FreeAttributes() to release the attributes.

On successful login, the Sm_AgentApi_Session_t structure is populated with the session specification. If you allocated memory for this structure, it is your responsibility to deallocate it.

Example

See the example application smagentexample.cpp for an example of this function.