OAuth-based security model

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

Protecting resources with OAuth-based security

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

{
    "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