Learn about the MobileFirst security-check
contract, which is defined by the SecurityCheck and SecurityCheckConfiguration interfaces.
Overview
Every security check must implement
the
com.ibm.mfp.server.security.external.SecurityCheck interface
(
the security-check interface). This interface constitutes
the basic contract between the security check and the
MobileFirst security
framework. Custom security checks are implemented as a Java™ security-check class within a
MobileFirst adapter
(see
Security-checks implementation).
The security-check implementation must fulfill the following requirements:
- Functions - the security check must provide the client-authorization
and introspection functions. See Security-check functions.
- State management - the security check must manage its state, including
creation, disposal, and current-state management. See Security-check state management.
- Configuration - the security check must create a security-check
configuration object, which defines the supported security-check configuration
properties, and validates the types and values of customizations of
the basic configuration. See Security-check configuration.
For a complete reference of the security-check
interface, see SecurityCheck. In addition, review the
implementation and documentation of the provided abstract security-check
base classes. These classes implement some of the requirements of
the security-check contract, such as state management, and demonstrates
how to implement other custom functions. See
The security-check base and sample classes.
Security-check functions
A
security check provides two main functions to the security framework:
- Authorization
- The framework uses the SecurityCheck.authorize method
to authorize client requests. When the client requests access to a
specific OAuth scope, the framework maps the scope elements into security
checks (see OAuth scopes and security checks). For each security
check in the scope, the framework calls the authorize method
to request authorization for a scope that contains the scope elements
that mapped to this security check. This scope is provided in the
method's scope parameter. The security check
adds its response to the AuthorizationResponse object that is passed
to it within the response parameter. The response
contains the name of the security check and the response type, which
can be success, failure, or a challenge (see AuthorizationResponse.ResponseType). When
the response contains a challenge object or custom success or failure
data, the framework passes the data to the client's security-check
challenge handler within a JSON object. For success, the response
also contains the scope for which the authorization was requested
(as set in the scope parameter), and the expiration
time for the granted authorization. To grant the client access to
the requested scope, the authorize method of each
of the scope's security checks must return success, and all expiration
times must be later than the current time.
- Introspection
- The framework uses the SecurityCheck.introspect method
to retrieve introspection data for a resource server. This method
is called for each security check that is contained in the scope for
which introspection was requested. As with the authorize method,
the introspect method receives a scope parameter
that contains the scope elements that mapped to this security check.
Before returning the introspection data, the method verifies that
the current state of the security check still supports the authorization
that was previously granted for this scope. If the authorization is
still valid, the introspect method adds its response
to the IntrospectionResponse object that is passed
to it within the response parameter. The response
contains the name of the security check, the scope for which the authorization
was requested (as set in the scope parameter),
the expiration time for the granted authorization, and the requested
custom introspection data. If authorization can no longer be granted
(for example, if the expiration time for a previous successful state
elapses), the method returns without adding a response.
Note: - The security framework collects the processing results from the
security checks, and passes relevant data to the client. The framework
processing is entirely ignorant of the states of the security checks.
- Calls to the authorize or introspect methods
can result in a change in the current state of the security check,
even if the expiration time of the current state did not elapse.
Security-check state
management
Security checks are stateful, meaning that the
security check is responsible for tracking and retaining its interaction
state. On each authorization or introspection request, the security
framework retrieves the states of relevant security checks from external
storage (usually, distributed cache). At the end of request processing,
the framework stores the security-check states back in external storage.
The
security check contract requires that a security check
- Implement the java.io.Externalizable interface.
The security check uses this interface to manage the serialization
and deserialization of its state.
- Define an expiration time and an inactivity timeout for its current
state. The state of the security check represents a stage in the authorization
process, and cannot be indefinite. The specific periods for the state's
validity and maximum inactivity time are set in the security-check
implementation, according to the implemented logic. The security check
informs the framework of its selected expiration time and inactivity
timeout via the implementation of the getExpiresAt and getInactivityTimeoutSec methods
of the SecurityCheck interface.
Security-check configuration
A
security check can expose configuration properties, whose values can
be customized both at the adapter and at the application level. The
security-check definition of a specific class determines which of
the supported configuration properties of this class to expose, and
can customize the default values set in the class definition. See Defining security checks. The property values can be further customized,
dynamically, both for the adapter that defines the security checks,
and for each application that uses the check. See Security-checks configuration. A security-check class exposes its supported
properties by implementing a createConfiguration method,
which creates an instance of a security-check configuration class
that implements the com.ibm.mfp.server.security.external.SecurityCheckConfiguration interface
(the security-check configuration interface). This interface
complements the SecurityCheck interface, and is
also part of the security-check contract. The security check can create
a configuration object that does not expose any properties, but the createConfiguration method
must return a valid configuration object and cannot return null. For a complete reference of the security-check configuration
interface, see SecurityCheckConfiguration. In addition, review
the implementation and documentation of the provided abstract security-check
base class and the sample configuration-class implementations. See The security-check base and sample classes.
The security framework calls the security-check's
createConfiguration method
during deployment, which occurs for any adapter or application configuration
change. The method's
properties parameter contains
the properties that are defined in the adapter's security-check definition,
and their current customized values (or the default value if there
was no customization). The implementation of the security-check configuration
should validate the values of the received properties, and provide
methods for returning the validation results. The security-check configuration
must implement
getErrors,
getWarnings,
and
getInfo methods. The abstract security-check
configuration base class,
SecurityCheckConfigurationBase also defines
and implements custom
getStringProperty,
getIntProperty,
and
addMessage methods. See the code documentation
of this class for details.
Note: The names and values of the configuration
properties in the security-check definition and in any adapter or
application customization, must match the supported properties and
allowed values, as defined in the configuration class.