Overview of the MobileFirst security framework

The security framework is based on the OAuth 2.0 protocol, as defined in the OAuth Specification. According to this protocol, a resource can be protected by a scope that defines the required permissions for accessing the resource. To access a protected resource, the client must provide a matching access token, which encapsulates the scope of the authorization that is granted to the client.

The OAuth protocol separates the roles of the authorization server and the resource server on which the resource is hosted. The authorization server manages the client authorization and token generation. The resource server uses the authorization server to validate the access token that is provided by the client, and ensure that it matches the protecting scope of the requested resource.

The security framework is built around an authorization server that implements the OAuth protocol, and exposes the OAuth endpoints with which the client interacts to obtain access tokens. The framework provides the building blocks for implementing a custom authorization logic on top of the authorization server and the underlying OAuth protocol. By default, MobileFirst Server functions also as the authorization server. However, you can configure an IBM® WebSphere® DataPower® appliance to act as the authorization server and interact with MobileFirst Server.

OAuth scopes, security checks, and challenge handlers

In the OAuth model, a resource is protected by a scope, which is string of zero or more space-separated scope elements. Each scope element represents a logical authorization permission. The MobileFirst security framework maps scope elements into security checks, which implement the actual authorization logic.

A security check is a server-side entity that implements the security logic for protecting server-side application resources. A simple example of a security check is a user-login security check that receives the credentials of a user, and verifies the credentials against a user registry. Another example is the predefined MobileFirst application-authenticity security check, which validates the authenticity of the mobile application and thus protects against unlawful attempts to access the application's resources. Server-side developers can write security checks that implement their required authorization logic. The framework also contains predefined security checks, for example for validating the authenticity of a mobile application.

A security check typically issues security challenges that require the client to respond in a specific way to pass the check. This handshake occurs as part of the OAuth access-token-acquisition flow. The client uses challenge handlers to handle challenges from security checks. A challenge handler is a client-side entity that implements the client-side security logic and the related user interaction.

For each security check that issues a challenge, a matching client challenge handler must be registered in the application code. The MobileFirst client API includes preregistered challenge handlers for the predefined security checks. To support a custom security check, the client-side developer must implement and register a challenge handler for that security check in the application code.

Application developers protect access to their resources by defining the required scope for each protected resource, and implementing the related security checks and challenge handlers. The server-side security framework and the client-side API handle the OAuth message exchange and the interaction with the authorization server transparently, allowing developers to focus only on the authorization logic.

End-to-end authorization flow

Obtaining an access token

The client obtains an access token from the authorization server by following these steps, as illustrated in Figure 1:

1. Registration - the client registers itself with MobileFirst Server. As part of the registration, the client provides a public key that will be used for authenticating its identity (see Step 4). This phase occurs once in the lifetime of a mobile application instance. If the application-authenticity security check is enabled for a mobile client application, the authenticity of the application is validated during its registration (see Application-authenticity security check).
2. Access-token request - the client requests an access token with a certain scope. The requested scope should map to the same security checks as the scope of the protected resource that the client wants to access, and can optionally also map to additional security checks.
   If the client does not have prior knowledge about the scope of the protected resource, it can first request an access token with an empty scope, and try to access the resource with the obtained token. The client will receive a response with a 403 (Forbidden) error and the required scope of the requested resource.
3. Authorization - MobileFirst Server runs the security checks to which the scope of the client's request is mapped. The authorization server either grants or rejects the client's request based on the results of these checks. If a mandatory application scope is defined, the security checks of this scope are run in addition to the checks of the requested scope.
4. Token generation - after successful authorization, the client is redirected to the authorization server's token endpoint, where it is authenticated by using the public key that was provided as part of the client's registration (see Step 1). Upon successful authentication, the authorization server issues the client a digitally signed access token that encapsulates the client's ID, the requested scope, and the token's expiration time.

Figure 1. Obtaining an access token

Note: The "MobileFirst Server" box in Figure 1 embodies both the functions that are provided specifically by MobileFirst Server, and the functions that are provided by the authorization server. The authorization server can be either MobileFirst Server (default) or WebSphere DataPower.

Accessing a protected resource by using an access token

After obtaining an access token, the client attaches the obtained token to subsequent requests to access protected resources. The resource server uses the authorization server's introspection endpoint to validate the token. The validation includes using the token's digital signature to verify the client's identity, verifying that the scope matches the authorized requested scope, and ensuring that the token has not expired. When the token is validated, the client is granted access to the resource. The protected resource can be hosted on an instance of MobileFirst Server (see Figure 2) or on an external server (see Figure 3).

Figure 2. Protecting a resource on MobileFirst Server

Figure 3. Protecting a resource on an external server

Note: The "MobileFirst Server" box in Figure 2 and Figure 3 embodies both the functions that are provided specifically by MobileFirst Server, and the functions that are provided by the authorization server. The authorization server can be either MobileFirst Server (default) or WebSphere DataPower.

Related information