Learn about the security framework of IBM MobileFirst™ Platform Foundation (the
security framework), its building blocks, and the related authorization
flows for protecting your resources and securing your applications.
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
Following is an outline of the end-to-end flow for
authorizing client access to a protected resource. The flow consists
of two main stages:
- The client obtains an access token for the protected resources,
after passing the required security checks (as defined in the resource's
protecting scope). See Obtaining
an access token.
- The client uses the access token to access the protected resource.
Before granting the client access to the resource, the access token
is validated. See Accessing
a protected resource by using an access token.
- Obtaining an access token
- The client obtains an access token from the authorization server
by following these steps, as illustrated in Figure 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).
- 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.
- 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.
- 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.