Sm_AgentApi_LoginAdv()

This function performs session login and session validation.
casso127
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. This function works just like
Sm_AgentApi_Login()
. Apart from the existing behavior, this function supports the Authentication Chain scheme login. If no Authentication Chain is used, there is no difference between
Sm_AgentApi_Login()
 and 
Sm_AgentApi_LoginAdv()
.
If no Authentication Chain is used, input attribute count is 0 and Array Input Attribute should be NULL.
Syntax
int SM_EXTERN Sm_AgentApi_LoginAdv(
    const void* pHandle,
    const char* lpszClientIpAddr, /* optional */
    const Sm_AgentApi_ResourceContext_t* pResourceContext,
    const Sm_AgentApi_Realm_t* pRealm,
    const Sm_AgentApi_UserCredentials_t* pUserCredentials,
    const long lNumInAttributes,
    const Sm_AgentApi_Attribute_t* pInAttributes, /* optional */
    Sm_AgentApi_Session_t* pSession,
    long* pNumOutAttributes,
    Sm_AgentApi_Attribute_t** ppOutAttributes,
    const char* lpszTransactionId, /* optional */
    void* pReserved /* reserved */
    );
Parameter
I/O
Description
pHandle
I
Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().
lpszClientIpAddr
I
(Optional) The IP address of the client that the user is logging from. 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.
NumInAttributes
I
(Optional) The number of attributes in ppAttributes. 0 if no Authentication Chain is used.
pInAttributes
I
(Optional) A pointer to an array of response attribute definition structures. NULL if no Authentication Chain is used.
pSession
O
A User Session definition structure.
pNumOutAttributes
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 chain authentication scheme.
lpszTransactionId
I
(Optional) The ID that the agent uses to associate application activity with security activity. The Policy Server logs this ID.
Return Values
This function returns the following attributes, when available:
  • 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
In case the Resource is protected with Authentication Chain scheme, and
Sm_AgentApi_LoginAdv()
 call returns SM_AGENTAPI_CHALLENGE, to get the Fallback/next authentication scheme details, the following Response attributes can be returned when Policy Server triggers the next authentication in the chain. Hence, in case of Authentication Chaining these attributes are populated by Policy Server and should be read to get the details of the next chained authentication scheme.
  • SM_AGENTAPI_ATTR_AUTHCHAINSPEC. Set with ChainSpec for Authentication Chain.
  • SM_AGENTAPI_ATTR_CHAINREALMCREDENTIALS. Set with the credential type collector, similar to Sm_AgentApi_Realm_t (
    nRealmCredentials
    )
  • SM_AGENTAPI_ATTR_CHAINFORMLOC. Set with Challenge URL where to redirect to collect credential, similar to Sm_AgentApi_Realm_t (
    lpszFormLocation
    )
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. To perform Authentication Chaining, supply ChainSpec as input attribute to the call. ChainSpec is required by Policy Server to process any Authentication Chaining login along with User Credentials.
Sm_AgentApi_LoginAdv() returns attributes in the Sm_AgentApi_Attribute_t structure. Call Sm_AgentApi_FreeAttributes() to release the Output 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. 
Refer the following sample code to user Authentication Chain acheme using
Sm_AgentApi_LoginAdv().
For example:
See the sample application smtestauthchain.cpp for an example of this function.