Programming Security for Web Services

Web Services Interfaces

To develop Web Services clients, you use the Web Services SSM application programming interfaces (APIs).

These interfaces are described in the following sections:

Registry Service Interface

To map security service type and SSM configuration and SOAP endpoints, each Web Services SSM process has its own separate Registry Service. The address of the Registry Service should be known to the web services client from its configuration. This service maps the SSM Configuration ID and the service type to the Web Services SSM and SOAP endpoints for the security services. The Configuration ID is defined in the default.properties file for the SSM instance. The Registry Service makes it possible to distinguish between the supported service types (auditing, authentication, authorization, credential mapping, and role mapping). Registry Service operations on a particular machine are limited to the local machine (see Figure 5-1). The Web Services client learns about the Registry Service from its configuration file.

The following topics provide or more information on the Registry Service.

How the Registry Service Works

The Registry Service works as follows (Figure 5-2):

Registry Service Methods

The Registry Service supports two methods: locateService() and doesServiceExist(). Both methods accept the requested service type of the Web Server SSM or Web Services SSM that provides the service. The supported service types are: ALES_AUDIT, ALES_AUTHENTICATION, ALES_AUTHORIZATION, ALES_CREDENTIAL, and ALES_ROLE. The type for all service types is string.

For the locateService() method, the Registry Service returns the fully qualified URL for the endpoint of the requested service. For the doesServiceExist() method, the service returns a Boolean value (true or false) that indicates whether the service exists and can be requested.

Methods Common to All Web Services Interfaces

The following methods are supported by all Web Services interfaces, except for the Registry Service interface.

Authentication Service Interface

The Authentication Service provides security functions to an application so as to establish, verify, and transfer a person or process identity. Thus, the Authentication Service provides two main security functions: authentication and identity assertion.

The Authentication Service accepts user credentials and/or identity assertion tokens and verifies that they match the user identity stored in the existing user profile. The following types of identity assertion tokens are supported:

The Extensible Markup Language (XML) structures used by the Authentication Service for transmitting identity assertion tokens and other credential types are defined the WSDL interface.

To ensure secure handling of credentials, all credentials presented to the Web Services SSM must satisfy the following requirements:

The Web Services SSM only accepts clear-text passwords. However, the credentials presented are always be protected by SSL, either one-way or two-way. The Web Services SSM returns credentials to clients over SSL as well.

The SOAP authentication interface enables the Web Services SSM to return challenges to clients if they fail to provides the information necessary to complete the authentication process. In such cases, the client can respond with the requested information. In order to avoid expensive round trips, however, the web services client should pass in all available credentials information with the initial SOAP request.

The following topics provide more information on the Authentication Service interface:

Authentication Process

The authentication process is as follows (see Figure 5-3):

Authentication Service Methods

To support authentication functions the authentication provides the following methods:

authenticate() Method

This method accepts any credential type supported by the authentication provider or a response to an earlier authentication challenge, and, optionally, the type of requested identity assertion that represents the identity and application context of the authenticated user. In response, it returns either the requested identity assertion token and status information or an authentication challenge.

Table 5-1 describes the authenticate() method parameters.

assertIdentity() Method

This method accepts any supported identity assertion type or a response to an earlier authentication challenge, and, optionally, the type of requested identity assertion that represents the identity and application context of the authenticated user. In response, it returns either the requested identity assertion token and status information or an authentication challenge.

Table 5-2 describes the assertIdentity() method parameters.

isAssertionTokenSupported() Method

This method accepts an identity assertion credential type that represents the authenticated user’s identity. It returns a Boolean value (true or false) to indicate whether this token type is supported by this instance of the Web Services SSM.

Table 5-3 describes the isAssertionTokenSupported() method parameters.

validateIdentity() Method

This method is DEPRECATED.

This method accepts any supported identity assertion type that represents the identity of the authenticated user. It returns a structure with a Boolean value (true or false) that indicates whether the token is valid.

Table 5-4 describes the validateIdentity() method parameter.

Authorization Service Interface

The Authorization Service is a service that allows an application to determine if a specific identity is permitted to access a specific resource. This decision may then be enforced in the application directly at the policy enforcement point.

The Authorization Service is primarily based on a single method: isAccessAllowed(). This method accepts a supported type of user credential or an identity token, a runtime resource, and a runtime action. Optionally, this method can accept the type of the requested identity assertion token that represents the identity of the authenticated user, the application context, and direction parameters. The isAccessAllowed() method requires that a valid, authenticated identity or a null identity token (representing an anonymous identity) be present when requesting an access decision. The following topics provide more information on the Authorization Service.

Authorization Process

The authorization process is as follows (see Figure 5-4):

Authorization Service Methods

The Authorization Service supports the following methods:

isAccessAllowed()

This method accepts a supported type of an identity assertion token and runtime resource and action structures. Optionally, it can accept the requested identity assertion credential type, application context, and authorization direction parameters. In response, this method returns the authorization decision and authorization data, or, if required by the authorization provider, additional context requests.

Table 5-5 describes the isAccessAllowed() method parameters.

isAuthenticationRequired() Method

The Authorization Service interface also supports the isAuthenticationRequired() method. This method accepts a runtime resource and a runtime action. It returns a Boolean value (true or false) that indicates whether authentication is require to access this resource. The web services client uses this method to test whether privileges are required to access a particular resource.

Table 5-6 describes the isAuthenticationRequired() method parameters.

Auditing Service Interface

The Auditing Service logs events based on activity related to enterprise security. The Web Services SSM runtime uses the Auditing Service to log appropriate data when events occur. The Auditing Service is based on an event model. When something of note occurs, an auditing event is automatically logged. A user or a application that wants notification when a particular event occurs can derive a new class from the AuditRecord class.

The following topics provide more information on the Auditing Service.

Auditing Process

The auditing process is as follows (see Fig):

Auditing Service Method

The Auditing Service passes the audit event to the Web Services SSM runtime. Based on its configuration, the SSM runtime routes the event to the proper auditing providers so that it can be recorded.

The Auditing Service supports a single method, recordEvent(). This method accepts an audit record, and, optionally, an identity assertion token, representing the auditing user, and an application context.

Table 5-7 describes the recordEvent() method parameters.

Role Mapping Service Interface

The Role Mapping Service allows an application to extract role information about specific identities and resources within the context of the application. These roles can then be used for customizing an interface or for other purposes.

The Role Mapping Service evaluates an interaction of an identity with a resource within an application context and returns a list of role names associated with the configuration of that identity. These roles can change with every resource or be static for the identity across all resources. The roles assigned to an identity are determined by the security policy.

The Web Services SSM is capable of retrieving the roles that a user may have for the given resource and action combination. The user identity is passed as an identity assertion token, instead of a Java object. To obtain roles, authenticated users must be authorized to obtain their roles for the given resource/action combination.

The Role Mapping Service requires that the application pass in a valid identity, a valid resource, and a valid action. The application context is optional and may be set to null if no context is passed in.

The following topics provide more information on the Role Mapping Service.

Role Mapping Process

The role mapping process is as follows (see Figure 5-4):

Role Mapping Service Method

The Role Mapping Service interface supports one method, getRoles(). This method gets the roles for an authenticated user identity in reference to a RuntimeResource, RuntimeAction, and an optional Context.

The getRoles() method accepts a supported type of an identity token, and, optionally, runtime resource and action structures, and an application context. It returns either a list of user roles associated for the identity and a time-to-live parameter for user roles.

Table 5-8 describes the getRoles() method parameters.

Credential Mapping Service Interface

The Credential Mapping Service allows an client application to fetch credentials of certain types that are associated with a specific identity for a specific resource. These credentials can then be used on behalf of that identity to execute some privileged function, such as logging into a database or sending e-mail.

The following topics provide more information on the Credential Mapping Service.

Credential Mapping Process

The credential mapping process is as follows (see Figure 5-6):

Credential Mapping Method

The Credential Mapping Service supports one method: getCredentials(). This method accepts a supported type of an identity assertion token and a list of requested credential types. Optionally, this method can accept an identity assertion token that represents the identity of a different user and a runtime resource structure, which includes the requested resource and action and the application context. In response, the getCredentials() method returns either a list of requested user credentials, identity assertion tokens, and a list of any missing credential types.

Authenticated users are always authorized to obtain their own credentials for the given resource/action combination. However, authenticated user cannot requests credentials on behalf of another user.

Credential mapping process involves issuing new types of credentials to the specified combination of user, resource, and action. The user identity is passed as an identity assertion token, instead of a Java object.

Table 5-9 describes the getCredentials() method parameters.