OAuth-based security model
Topics that describe OAuth-based security features in IBM MobileFirst™ Platform Foundation.
Overview
The OAuth 2.0 protocol is based on acquiring an access token, which encapsulates the authorization that is granted to the client. In that context, the IBM MobileFirst Platform Server serves as an authorization server and is able to generate such tokens. The client can then use these tokens to access resources on a resource server, which can be either the MobileFirst Server itself, or an external server. The resource servers perform validation on the token to make sure that the client can be granted access to the requested resource. This separation between resource server and authorization server in the new OAuth-based model allows you to enforce IBM MobileFirst Platform Foundation security on resources that are running outside the MobileFirst Server.
To support compatibility with earlier versions, the classic (pre-V7.0) security model is still in use in the flows that are based on the existing APIs (for example, invokeProcedure in Java™). The new client APIs trigger flows that conform to the OAuth-based security model. V7.0 provides seamless integration between the two security models. The platform allows you to mix classic and new APIs in the same application, while keeping a consistent security context on the server side.
End-to-end authorization flow
- Acquiring a token (see Figure
1): In this phase, the client obtains a token from the authorization
server, following these steps:
- Registration: This phase occurs once in the lifetime of a mobile app that is installed on a device. In this phase, the client registers itself with the MobileFirst Server. When application authenticity has been configured, it is activated during registration.
- Authorization: In this phase, the client has to undergo specific security checks, according to the scope of the authorization request. These checks are implemented using the building blocks of the classic security model: authentication realms are used on the server side, and challenge handlers are used on the client side. All the security checks supported by IBM MobileFirst Platform Foundation can be used in this phase (built-in realms such as remoteDisable and others, custom realms, and adapter-based authentication).
- Token generation: After successful authorization, the client is redirected to the token endpoint, where it is authenticated using the PKI trust that was established during the registration phase. The endpoint then generates two sets of tokens and sends them back to the client: an access token, which encapsulates all the security checks that the client has passed in the authorization phase and an ID token, which contains information regarding the user and device identity of the client.
Figure 1. Obtain token flow - Using a token to access protected resources: Protected resources
can run on the MobileFirst Server (see Figure 2) or on external servers
(see Figure 3). Resources
on external servers can be protected by using the validation modules
that are provided with IBM MobileFirst Platform Foundation:
the Node.js validation module for
protecting Node.js resources and the Trust association interceptor
(TAI) for protecting Java resources,
or by developing your own custom filter as shown in the Token validation
endpoint example. These modules validate the access token and
ID token in incoming requests, making sure that only authorized clients
are served. To consume such protected resources, the client has to
first acquire the token from the MobileFirst Server,
and then add the tokens as an authorization header to outgoing requests.
The new client APIs enable the client to access protected resources while transparently handling the handshake with the authorization server.
Figure 2. Protecting a resource on the MobileFirst ServerFigure 3. Protecting a resource on an external server
Protecting resources with OAuth-based security
- Integrity: Digital signature for both ID token and access token is verified.
- Token expiration: Both tokens are tested for expiration. An expired token will fail the validation.
- Scope: Required scope for the resource is verified. The token has to contain the scope tokens (realm names) that are defined in the scope, and these scope tokens have to be valid (meaning, not expired).
- Mandatory scope: In addition to the scope defined by the resource, the access token must contain the valid scope that is required by the application. This scope contains the realms, which are defined in the security test that is protecting the application.
- Protecting internal resources - RESTful adapters
- IBM MobileFirst Platform Foundation V7.0 enables you to enforce security on resources that are running on the MobileFirst Server, that is, Java and JavaScript RESTful adapters. For more information, see Security configuration of a JAX-RS resource.
- Protecting external resources
- With IBM MobileFirst Platform Foundation V7.0,
you can enforce MobileFirst security
on resources running outside the MobileFirst Server.
To this end, you can use the built-in Node.js and Java validation modules, or implement your own
custom validation module in the technology of your choice, using the
online validation endpoint:
- Node filter
- The passport-mfp-token-validation module provides a passport validation strategy for protecting apps on a Node.js server. For more information, see Protecting resources on Node.js servers.
- TAI filter
- You can use the IBM MobileFirst Platform Foundation OAuth trust association interceptor (TAI) to protect application resources on WebSphere Application Server or WebSphere Application Server Liberty. For more information, see Protecting resources on WebSphere Application Server or WebSphere Application Server Liberty.
- Custom filter
- The token validation endpoint on the MobileFirst Server validates tokens that are issued by the authorization server. For more information, see Protecting resources with the token validation endpoint.
Specifying the user identity realm in OAuth-based flows
Although user authorization may include authorization with several realms, only one of these realms is defined as the user identity realm, and that realm determines the user identity. In an OAuth-based flow, the user identity realm is set according to the userIdentityRealms definition in the The application descriptor. Note that in the classic (pre-V7.0) flows, the user identity realm is selected according to the definition in the security test. See customSecurityTest. In OAuth-based flows, information about the user identity, which is set by the userIdentityRealms attribute, is part of the data contained in the ID token.
Combining classic and OAuth-based security models
MobileFirst Server V7.0 provides a smooth integration between the classic and OAuth-based security models.
Essentially, both flows share the same security context on the server side, and so any security state of a specific realm (such as expiration, or login status) is consistently shared between the flows. This allows you, the developer, to mix classic and OAuth-based security APIs, while providing a unified experience for the end user.
Consider, for example, a client application that calls an adapter procedure protected by some realm myCustomRealm and then retrieves a token for a scope that includes the same realm. In this case, the user will have to pass the myCustomRealm security check only on the first call, and will get the relevant token on the second call, without having to re-authenticate.
Some issues need to be considered when using both models in the same flow, or on the same resource:
- Device SSO:
The configuration of the Device SSO feature is based on the device and user identity realms that are defined in the security test, which is protecting the resource. However, OAuth resources are not protected by security tests and do not have a single defined user realm per resource, so the standard MobileFirst device SSO behavior does not apply to them. For more information, see Device single sign-on (SSO).
. - The login/logout API:
The WLClient login/logout API enables a user to log in to and log out of a specific realm, by updating the server side security state. However, in the new OAuth-based security model, security credentials are also kept in the access token on the client side. The result is that using this API will cause an inconsistent state, for example, in which the client is logged out of a realm on the server side but still holds a valid token for that realm on the client side. To solve this inconsistency, it is recommended to re-obtain the access token, by using the obtainAuthorizationHeaderForScope method, after successful login or logout.
For example, consider a client that passed the security checks for Realm1 and Realm2, and later calls logout(Realm2). In this case, the access token on the client would still contain the security credentials for both Realm1 and Realm2, and the client could use this token to access protected resources. To refresh the token, that is, to obtain a token for Realm1 only, the client calls obtainAuthorizationHeaderForScope without the logged out realm Realm2.
iOS example:[[WLClient sharedInstance]logout:@"MyRealm" withDelegate:self]; -(void)onSuccess:(WLResponse *)response{ // re-obtain the token [[WLAuthorizationManager sharedInstance]obtainAuthorizationHeaderForScope:nil completionHandler:^(WLResponse *response, NSError *error) { // successful logout logic }]; }
Test token endpoint
The test token endpoint enables you to get a valid token via a REST call, without having to set up a mobile client. For more information, see The test token endpoint.
Public key endpoint
/authorization/v1/publickey
The
endpoint returns the public key information using the JWK standard
format. The following is an example of a result returned by this endpoint: {
"e": "AQAB",
"n": "AM0Dd7xAdv6H-ygL7r8qCLdE-3I2kk45zgZtDd_qs8fvnYfdiqTSV4_2t6OGG8CV5Ce41PMpIwmL410X9IZnvhxoYiFcMSaOeIqoe-rJA0uZuw2rHhXZ3WVCeKezRVcCOYsQN-mQK0mfz5_3o-ev0UYwXkSOwBBl1EhqIwVDwOieg2JMGl0EXsPZfkNZI-HU4oMii-TrNLzRWkMmLvm09hL5zosUNA15veCKph2WpmSm2S61nDhH7gLEoymDnTEjPY5Aoh2inI-36RGYVMUUbO46CrNUYuIobOiXlLzBIhuICpfVdxT_x7stKX5C9BfMTB4GkOHP5cUv7Nz1dDhIPu8",
"kty": "RSA"
}
Preview mode
The new OAuth-based flows are also available in preview mode. However, in this mode, the registration phase is protected by an anti-cross site request forgery realm, wl_antiXSRFRealm, and not application authenticity.
Exposed endpoints
You can enable white- and blacklists to the endpoints of the MobileFirst Server. For a list of endpoints for use with the OAuth-based security model, see Endpoints of the MobileFirst Server production server.
Security client APIs
- There is an API for consuming protected resources, which transparently
supports the interaction with the MobileFirst Server (obtaining
the token requested by the resource).
- In Objective-C: WLResourceRequest
- In Java: WLResourceRequest
- In JavaScript: WLResourceRequest
- In C# for Windows 8 Universal and Windows Phone 8 Universal: WLResourceRequest
- In addition, APIs are provided to create a custom client implementation that is able to interact with the validation modules and MobileFirst Server. The following examples are provided: