IdmaAuthentication

Methods dealing with authenticating a user to a DMA system or document space.

This interface is implemented by a System or DocSpace object which requires authentication of users. If such authentication is not required, the interface need not be implemented.

IdmaAuthentication::AuthenticateUser

This method must be supported in every implementation of this interface.

Syntax
DmaRC IdmaAuthentication::AuthenticateUser (
pDmaString pStringIn,
ppDmaString ppStringOut)

Parameters

This method is used to authenticate the user to the DMA System (via the typical ODBC BrowseConnect style dialog). The caller can test whether authentication is required by specifying a NULL value for pStringIn and testing for a return value of DMARC_ALREADY_AUTHENTICATED. This method may only be used to initially authenticate a user or test for whether a user is already authenticated, it cannot be used to change a user’s authentication once set. Attempts to do so will return DMARC_ALREADY_AUTHENTICATED.

Other methods on a DMA system object may fail with a return code of DMARC_NOT_AUTHENTICATED if called before the user is authenticated via this method.

The DMA Connection Authentication mechanism is best described as a protocol. The client submits a request message (pStringIn) and the service responds with a response message (pointed to by pStringOut). Each of these messages is encoded in a DmaString and syntactically conforms to the following BNF syntax based upon the ODBC SQLBrowseConnect syntax:

request-message ::= connection-string

response-message ::= connection-string

connection-string ::= attribute[";" connection-string]

attribute ::= [ "*" ] keyword "=" value

keyword ::= dma-keyword | provider-keyword

dma-keyword ::= { "SCHEME" | "UID" | "PWD" | "KRB-VERSION" |

    "KRB-PRINCIPAL" | "KRB-TICKET" | "KRB-AUTH" } [ ":" localized-identifier ]

provider-keyword ::= identifier [ ":" localized-identifier ]

value ::= "{" value-list "}" | "?" | identifier

value-list ::= identifier [ ":" localized-identifier ] 

     [ "," value-list]  

identifier and localized-identifier consist of one or more characters. keyword is to be case insensitive. An asterisk preceding a keyword indicates that the keyword is optional and need not be present in the next request message.

DMA Authentication Schemes

The service response to an empty request message shall indicate which DMA authentication schemes the service supports. DMA 1.0 defines two authentication schemes and allows providers to extend the set of DMA authentication schemes. The DMA-BASIC scheme provides for a typical user-id and password based authentication. The DMA-KERBEROS scheme provides a mechanism for the client to provide the service with a Kerberos ticket and authenticator.

input connection string = ""

output connection string = "SCHEME={DMA-BASIC, 

     DMA-KERBEROS,<other>}"

return code =  DMARC_NEED_MORE_DATA
 

Note: the service responds with one or more schemes. <other> denotes a scheme not standardized by DMA and must not start with the "DMA-" prefix.

DMA-BASIC Authentication

The Client selects the DMA-BASIC scheme:

input connection string = "SCHEME=DMA-BASIC"

output connection string = "SCHEME=DMA-BASIC; 

     UID:UserName=?; PWD:Password=?"

return code =  DMARC_NEED_MORE_DATA
 

The Client provides userid and password:

input connection string = "SCHEME=DMA-BASIC; 

     UID=Joe DMA;PWD=DMA4ME"

output connection string = NULL

return code = DMARC_SUCCESS
 

DMA-KERBEROS Authentication

The DMA-KERBEROS scheme supports different versions of Kerberos. A Kerberos scheme authentication message exchange follows:

Client selects the DMA-KERBEROS scheme:

input connection string = "SCHEME=DMA-KERBEROS"

output connection string = "SCHEME=DMA-KERBEROS; 

     KRB-VERSION={4,5,DCE}"

return code =  DMARC_NEED_MORE_DATA
 

Client selects the DMA-KERBEROS version DCE:

input connection string = "SCHEME=DMA-KERBEROS;

     KRB-VERSION=DCE"

output connection string = "SCHEME=DMA-KERBEROS;

     KRB-VERSION=DCE;

     KRB-PRINCIPAL=DmaSystem@realm;

     KRB-AUTH=?;KRB-TICKET=?"

return code =  DMARC_NEED_MORE_DATA
 

The response supplies the client with a Kerberos principal identifier via the KRB-PRINCIPAL value and requests that the client supply an appropriate Kerberos Authenticator and Ticket via the KRB-AUTH and KRB-TICKET values respectively.

The Client responds:

input connection string = "SCHEME=DMA-KERBEROS;

     KRB-VERSION=DCE;

    KRB-PRINCIPAL=DmaSystem@realm;

     KRB-AUTH=<Base-64>;

     KRB-TICKET=<Base-64>"

output connection string = NULL

return code = DMARC_SUCCESS
 

where <Base-64> is a Base64 encoding per RFC 1521 of the Kerberos Authenticator and Ticket encrypted values.

Return Values

IdmaAuthentication::AutoAuthenticateUser

Support for this method is optional.

Syntax
DmaRC IdmaAuthentication::AutoAuthenticateUser ( )

This method is used to request authentication without any caller supplied parameters. DMA System and Document Space implementations are not required to but may implement this behavior. DMA does not specify the implementation of the AutoAuthentication method, however such implementation may be predicated upon prior established authentication state or environmental state.

A client can prevent automatic authentication by not calling this method and instead utilize the IdmaAuthentication::Authenticate method to perform explicit authentication.

Other methods on a DMA system object may fail with a return code of DMARC_NOT_AUTHENTICATED if called before the user is authenticated via this method or the IdmaAuthentication::Authenticate method.

Return Values