The Oracle BI Administrator requests that the developer create a dynamically loadable authentication module according to the Oracle BI Authenticator API specification. This section contains the APIs that the authenticator needs to implement. For more information about implementation, refer to About Authenticating Users Using Initialization Blocks.

All of the APIs take SAChar, which is defined as follows:

typedef wchar_t SAChar;

Other related type definitions are defined as follows:

typedef unsigned int SAUInt32;

enum

{

SAAuthenticatorTrue,

SAAuthenticatorFalse,

SAAuthenticatorNotSupported

} SAReturnType;

A header file is provided for all of the types that will be used in the dynamically loadable authenticator. All of the following APIs need to be thread-safe:

• SAUInt32 SAAuthenticatorGetVersion()

  Description: This returns the current version of the authenticator. The version number is predefined as 1.

  • Arguments

    None

  • Return value

    The version number is predefined as 1.

• void SAAuthenticateFreeString(SAChar *p)

  This function is a utility function that frees up memory pointed by p.

  • Argument

    Input

    p

    A pointer to a SAChar string

  • Return value

    None.

• void SAAuthenticateFreeStringArray(SAChar **pp)

  This function is a utility function. It frees up memory as pointed by pp.

  • Argument

    Input

    pp

    A pointer to a SAChar array

  • Return value

    None

• SAReturnType SAAuthenticatorInit(const SAChar * pConfigParams, SAChar **ppErrorMessage)

  This function performs some basic initialization to the authentication module. It will be called from Oracle BI Server only once.

  • Arguments

    Input	pConfigParams	This points to the parameters to be passed to the authenticator. The string is a concatenation of the Configuration parameter and decrypted version of the Encrypted parameter.
    Output	ppErrorMessage	This contains the error message, if an error occurs. The authenticator writer needs to allocate memory for the error message.

  • Return value
    • If the initialization is successful, the return value is SAAuthenticatorTrue.
    • If the initialization fails, the return value is SAAuthenticatorFalse and the error message is stored in *ppErrorMessage.

      NOTE:  The authenticator framework is responsible for freeing up the memory allocated for ppErrorMessage.

• SAReturnType SAAuthenticatorLogin(const SAChar * pUserID, const SAChar *pPassword, SAChar **ppErrorMessage)

  This function authenticates a user.

  • Arguments

    Input	pUserID	User's login name
    Input	pPassword	User's password
    Output	ppErrorMessage	This contains the error message, if an error occurs. The authenticator writer needs to allocate the memory for the error message.

  • Return value
    • If the authentication is successful, the return value is SAAuthenticatorTrue.
    • If the authentication is unsuccessful, the return value is SAAuthenticatorFalse and the error message is stored in **ppErrorMessage.

      The authenticator framework is responsible for freeing up the memory allocated for ppErrorMessage. This API cannot return SAAuthenticatorNotSupported.

• bool SAAuthenticatorIsAValidUser(const SAChar * pUserID, SAChar **ppErrorMessage)

  This function determines whether the specified user id is a valid.

  • Arguments

    Input	pUserID	User's login name
    Output	ppErrorMessage	This contains the error message, if an error occurs. The authenticator writer needs to allocate the memory for the error message.

  • Return value
    • If the user id is valid, the return value is SAAuthenticatorTrue.
    • If the user id is invalid, the return value is SAAuthenticatorFalse and the error message is stored in *ppErrorMessage.

      The authenticator framework is responsible for freeing up the memory allocated for ppErrorMessage.

      NOTE:  This API cannot return SAAuthenticatorNotSupported.

• SAReturnType SAAuthenticatorGetUserProps(const SAChar * pUserID, const SAChar **ppKeys, SAChar *** pppValues, SAChar **ppErrorMessage)

  This function contains a list of property values. When the key is GROUP and the user belongs to multiple groups, values need to be semicolon delimited.

  • Arguments

    Input	pUserID	User's login name
    Input	ppKeys	It points a null-terminated array of strings indicating which properties' values to return.
    Output	pppValues	It points to a null-terminated array of strings which has the properties' values corresponding to ppKeys. The authenticator writer needs to allocate the memory for the array.
    Output	ppErrorMessage	This contains the error message, if an error occurs. The authenticator writer needs to allocate the memory for the error message.

  • Return value
    • If the function call is successful, the return value is SAAuthenticatorTrue. The Oracle BI Server authenticator framework is responsible for freeing up the memory allocated for pppValues.
    • If function call fails, the return value is SAAuthenticatorFalse and the error message is stored in *ppErrorMessage. The Oracle BI Server authenticator framework is responsible for freeing up the memory allocated for ppErrorMessage.

      NOTE:  This API cannot return SAAuthenticatorNotSupported.

• SAReturnType SAAuthenticatorGetAllGroups(SAChar *** pppGroups, SAChar **ppErrorMessage)

  This function gets a list of all groups.

  • Arguments

    Output	pppGroups	It points to a null-terminated array of strings that are the groups to which the user belongs. The authenticator writer needs to allocate the memory for the array.
    Output	ppErrorMessage	This contains the error message, if an error occurs. The authenticator writer needs to allocate the memory for the error message.

  • Return value
    • If the function call is successful, the return value is SAAuthenticatorTrue. The Oracle BI Server authenticator framework is responsible for freeing up the memory allocated for pppGroups.
    • If function call fails, the return value is SAAuthenticatorFalse and the error message is stored in *ppErrorMessage. The Oracle BI Server authenticator framework is responsible for freeing up the memory allocated for ppErrorMessage.

      NOTE:  This API can return SAAuthenticatorNotSupported if it is not supported.

• void SAAuthenticatorShutdown()

  This function performs some cleanup up when Oracle BI Server shuts down. It will be called from Oracle BI Server only once.

  • Arguments

    None

  • Return value

    None