ITACACSAuthorization::GetAVPairs

Called when server processes authorization packet and requests extension for attribute-value pairs.

HRESULT GetAVPairs(
	[in] long tag,
	[in] TAC_AUTHORPARAMS * authorParams,
	[in] BSTR service,
	[in] BSTR protocol,
	[out] unsigned long * outpSize,
	[out] AVPAIR * * outpPairs,
	[out] BSTR * explainString,
	[out] unsigned char * tacacsStatus);

Parameters

tag

[in] Unique value identifying TACACS+ packet in whose context this method is called.

authorParams

[in] Authorization packet data.

service

[in] Requested service. It is the value taken from service=x attribute-value pair.

protocol

[in] Requested protocol. It's used with some service values. It is taken from protocol=x attribute-value pair and can be an empty string (be NULL) if protocol AV pair is not present.

outpSize

[out] If extension returns attribute-value pairs, this parameter must be set to the number of attributes pointed by outpPairs array.

outpPairs

[out] If extension returns attribute-value pairs, this parameter must be set to the array of pairs allocated by calling CoTaskMemAlloc.

explainString

[out] If extension does not authorize a user, this parameter may be allocated calling SysAllocString as a string describing the reason.

tacacsStatus

[out] Must be set to the result of authorization.
Possible values are:

• TAC_PLUS_AUTHOR_STATUS_PASS_ADD (authorization successful)
• TAC_PLUS_AUTHOR_STATUS_PASS_REPL (authorization successful)
• TAC_PLUS_AUTHOR_STATUS_FAIL (authorization failed)
• TAC_PLUS_AUTHOR_STATUS_ERROR (internal error)

TAC_PLUS_AUTHOR_STATUS_PASS_ADD and TAC_PLUS_AUTHOR_STATUS_PASS_REPL are not distinguished by server and are treated as successful access results.

Return Values

If extension returns error code, authorization error status is sent back to NAS as if tacacsStatusis set to TAC_PLUS_AUTHOR_STATUS_ERROR.

Thread Safety

This method is called in context of WORK thread. (See Server Threads Model for details.) You should synchronize data which is shared with other threads.

Memory Management

Memory for authorParams fields, service, protocol is allocated and freed by server, so extension must not change them.

Memory for explainString and outpPairs may be allocated by extension and is freed by server.

Example Code

This code does not allow user John to ping 217.127.2.4 IP address and specifies 15 minutes timeout for his shell session.

STDMETHODIMP CTest::GetAVPairs(
	long tag, TAC_AUTHORPARAMS * authorParams,
	BSTR service, BSTR protocol,
	unsigned long * outpSize, AVPAIR * * outpPairs,
	BSTR * explainString, unsigned char * tacacsStatus)
{
	if (wcscmp(authorParams->user,L"John")==0 && wcscmp(service,L"shell")==0)
	{
		*outpSize=2;
		*outpPairs=reinterpret_cast<AVPAIR*>(
			CoTaskMemAlloc(sizeof(AVPAIR)*2));

		(*outpPairs)[0].attribute=SysAllocString(L"cmd");
		(*outpPairs)[0].value=SysAllocString(L"ping 217.127.2.4");	
		(*outpPairs)[0].mandType=M_MANDATORY;
		(*outpPairs)[0].access=A_DENY;
		
		(*outpPairs)[1].attribute=SysAllocString(L"timeout");
		(*outpPairs)[1].value=SysAllocString(L"15");	
		(*outpPairs)[1].mandType=M_MANDATORY;
		(*outpPairs)[1].access=A_PERMIT;
	}
	
	return S_OK;
}

See Also

ITACACSAuthorization, List of TACACS+ Attribute-Value Pairs, Authorization concepts, TACACS+ authorization packet processing