Previous      Contents      Next
Sun Java System Identity Server 2004Q2 Developer's Reference

Chapter 2
Authorization Functions

This chapter provides a reference to the public functions you can use in developing custom authorization modules for Sun Java™ System Identity Server. Function summaries include a short description, syntax, parameters and returns.

The following functions are contained in the header file am_auth.h:

am_auth_abort()
am_auth_create_auth_context()
am_auth_destroy_auth_context()
am_auth_get_module_instance_names()
am_auth_get_organization_name()
am_auth_get_sso_token_id()
am_auth_has_more_requirements()
am_auth_init()
am_auth_login()
am_auth_logout()
am_auth_num_callbacks()
am_auth_submit_requirements()

---

am_auth_abort()

Aborts the authentication process.

Syntax

#include "am_auth.h"
AM_EXPORT am_status_t
am_auth_abort(am_auth_context_t auth_ctx);

Parameters

This function takes the following parameter:

Parameter	Description
auth_ctx	Handle of the auth context.

Returns

This function returns am_status_t with one of the following values:

Value	Description
AM_SUCCESS	If the abort process was successfully completed.
AM_INVALID_ARGUMENT	If the auth_ctx parameter is NULL.

---

am_auth_create_auth_context()

Creates a new auth context and returns the handle.

Syntax

#include "am_auth.h"
AM_EXPORT am_status_t
am_auth_create_auth_context(am_auth_context_t *auth_ctx,
        const char *org_name,
        const char *cert_nick_name,
        const char *url);

Parameters

This function takes the following parameters:

Parameter	Description
auth_ctx	Pointer to the handle of the auth context.
org_name	Organization name to authenticate to. May be NULL to use value in property file.
cert_nick_name	The alias of the certificate to be used if the client is connecting securely. May be NULL in case of non-secure connection.
url	Service URL, for example: http://pride.red.iplanet.com:58080/amserver May be NULL, in which case the naming service URL property is used.

Returns

This function returns am_status_t with one of the following values:

Value	Description
AM_SUCCESS	If auth context was successfully created.
AM_NO_MEMORY	If unable to allocate memory for the handle.
AM_INVALID_ARGUMENT	If the auth_ctx parameter is NULL.
AM_AUTH_CTX_INIT_FAILURE	If the authentication initialization failed.

---

am_auth_destroy_auth_context()

Destroys the given auth context handle.

Syntax

#include "am_auth.h"
AM_EXPORT am_status_t
am_auth_destroy_auth_context(am_auth_context_t auth_ctx);

Parameters

This function takes the following parameter:

Parameter	Description
auth_ctx	Handle of the auth context to be destroyed.

Returns

This function returns am_status_t with one of the following values:

Value	Description
AM_SUCCESS	If the auth context was successfully destroyed.
AM_INVALID_ARGUMENT	If the auth_ctx parameter is NULL.

---

am_auth_get_module_instance_names()

Gets the authentication module instances (or plug-ins) configured for an organization, or sub-organization name that was set during the creation of the auth context.

Syntax

#include "am_auth.h"
AM_EXPORT am_status_t
am_auth_get_module_instance_names(am_auth_context_t auth_ctx,
         am_string_set_t** module_inst_names_ptr);

Parameters

This function takes the following parameters:

Parameter	Description
auth_ctx	Handle of the auth context.
module_inst_names_ptr	Address of a pointer to am_string_set_t.

Returns

This function returns am_status_t with one of the following values:

Value	Description
AM_SUCCESS	If the submitted requirements were processed successfully.
AM_AUTH_FAILURE	If the authentication process failed.
AM_INVALID_ARGUMENT	If the auth_ctx parameter is NULL.
AM_SERVICE_NOT_INITIALIZED	If the auth service is not initialized.

Details

Supply the address of a pointer to a structure of type am_string_set_t. Module instance names are returned in am_string_set_t. Free the memory allocated for this set by calling am_string_set_destroy().

Returns NULL if the number of modules configured is zero.

---

am_auth_get_organization_name()

Gets the organization to which the user is authenticated.

Syntax

#include "am_auth.h"
AM_EXPORT const char *
am_auth_get_organization_name(am_auth_context_t auth_ctx);

Parameters

This function takes the following parameter:

Parameter	Description
auth_ctx	Handle of the auth context.

Returns

This function returns const char * with one of the following values:

Value	Description
Zero terminated string representing the organization	When user successfuly logs in.
NULL	If there was an error or the user has not successfully logged in.

---

am_auth_get_sso_token_id()

Get the SSO token id of the authenticated user.

Syntax

#include "am_auth.h"
AM_EXPORT const char *
am_auth_get_sso_token_id(am_auth_context_t auth_ctx);

Parameters

This function takes the following parameter:

Parameter	Description
uth_ctx	Handle of the auth context.

Returns

This function returns const char * with one of the following values:

Value	Description
Zero terminated string representing the organization	When user successfuly logs in.
NULL	If there was an error or the user has not successfully logged in

---

am_auth_get_sso_token_id()

Get the SSO token id of the authenticated user.

Syntax

#include "am_auth.h"
AM_EXPORT const char *
am_auth_get_sso_token_id(am_auth_context_t auth_ctx);

Parameters

This function takes the following parameter:

Parameter	Description
auth_ctx	Handle of the auth context.

Returns

This function returns const char * with one of the following values:

Value	Description
Zero terminated string representing the organization.	When user successfuly logs in.
NULL	If there was an error or the user has not successfully logged in.

---

am_auth_has_more_requirements()

Checks to see if there are requirements to be supplied to complete the login process.

Syntax

#include "am_auth.h"
AM_EXPORT boolean_t
am_auth_has_more_requirements(am_auth_context_t auth_ctx);

Parameters

This function takes the following parameter:

Parameter	Description
auth_ctx	Handle of the auth context.

Returns

This function returns boolean_t with one of the following values:

Value	Description
B_TRUE	If there are more requirements.
B_FALSE	If there are no more requirements.

Details

This call is invoked after invoking the login() call. If there are requirements to be supplied, then the caller can retrieve and submit the requirements in the form of callbacks.

---

am_auth_init()

Initializes the authentication modules.

Syntax

#include "am_auth.h"
AM_EXPORT am_status_t
am_auth_init(const am_properties_t auth_init_params);

Parameters

This function takes the following parameter:

Parameter	Description
auth_init_params	The property handle to the property file which contains the properties to initialize the authentication library.

Returns

This function returns am_status_t with one of the following values:

Value	Description
AM_SUCCESS	If the initialization of the library is successful.
AM_NO_MEMORY	If unable to allocate memory during initialization.
AM_INVALID_ARGUMENT	If auth_init_params is NULL.
Others	If the error was due to other causes. See am_types.h.

---

am_auth_login()

Starts the login process given the index type and its value.

Syntax

#include "am_auth.h"
AM_EXPORT am_status_t
am_auth_login(am_auth_context_t auth_ctx, am_auth_index_t auth_idx,
   const char *value);

Parameters

This function takes the following parameters:

Parameter	Description
auth_ctx	Handle of the auth context.
auth_idx	Index type to be used to initiate the login process.
value	Value corresponding to the index type.

Returns

This function returns am_status_t with one of the following values:

Value	Description
AM_SUCCESS	If the login process was successfully completed.
AM_INVALID_ARGUMENT	If the auth_ctx or value parameter is NULL.
AM_FEATURE_UNSUPPORTED	If the auth_idx parameter is invalid.

---

am_auth_logout()

Logs out the user.

Syntax

#include "am_auth.h"
AM_EXPORT am_status_t
am_auth_logout(am_auth_context_t auth_ctx);

Parameters

This function takes the following parameter:

Parameter	Description
auth_ctx	Handle of the auth context.

Returns

This function returns am_status_t with one of the following values:

Value	Description
AM_SUCCESS	If the logout process was successfully completed.
AM_INVALID_ARGUMENT	If the auth_ctx parameter is NULL.

---

am_auth_num_callbacks()

Gets the number of callbacks.

Syntax

#include "am_auth.h"
AM_EXPORT size_t
am_auth_num_callbacks(am_auth_context_t auth_ctx);

Parameters

This function takes the following parameters:

Parameter	Description
auth_ctx	Handle of the auth context.

Returns

This function returns size_t a value equal to the number of callbacks.

---

am_auth_submit_requirements()

Submits the responses populated in the callbacks to the server.

Syntax

#include "am_auth.h"
AM_EXPORT am_status_t
am_auth_submit_requirements(am_auth_context_t auth_ctx);

Parameters

This function takes the following parameter:

Parameter	Description
auth_ctx	Handle of the auth context.

Returns

This function returns am_status_t with one of the following values:

Value	Description
AM_SUCCESS	If the submitted requirements were processed successfully.
AM_AUTH_FAILURE	If the authentication process failed.
AM_INVALID_ARGUMENT	If the auth_ctx parameter is NULL.

Previous      Contents      Next

---

Copyright 2004 Sun Microsystems, Inc. All rights reserved.