For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.

Mapping scope elements

Map custom scope elements to security checks to define application-specific security logic.

An OAuth scope is composed of zero or more scope elements, and each scope element is mapped to zero or more security checks (see OAuth scopes and security checks). We can define custom scope elements for our application, which map to any of the predefined or custom security checks that are available for the application.

The application scope mapping provides multiple advantages.

• Access the same resource from multiple applications, and customize the authorization logic of each application by using different maps for the same scope elements of the protecting resource scope.
• Reuse the same mandatory scope for multiple applications, and customize the authorization logic of each application by using different maps of the contained scope elements. See Configure a mandatory application scope.
• Dynamically change the application's authorization logic by changing the scope-element maps. For example, we can define an empty scope element, and remap it to a new security check when the check becomes available.

Procedure

Map scope elements to security checks by using one of the following alternative methods:

• Using IBM MobileFirst™ Platform Operations Console (the console)
  1. Select your application version from the Applications section of the console's navigation sidebar, and then select the application Security tab.
  2. In the Scope-Elements Mapping section, select Add to Scope.
  3. In the Add New Scope-Element Mapping dialog window, provide a name for the new element, select zero or more security checks to which to map the element, and then select Add. A scope-mapping table that reflects your configuration is displayed in the Scope-Elements Mapping section of the Security tab.
     Repeat this step as needed to map more scope elements.

  We can delete or edit a defined scope element by selecting the relevant action icon for this element in the application's scope-mapping table.

• Editing the application-descriptor file
  1. Create a local copy of the application-descriptor JSON file. See Application configuration.
  2. Edit your local copy to define a scopeElementMapping object. In this object, define data pairs that are each composed of the name of your selected scope element, and a string of zero or more space-separated security checks to which the element maps. Replace ScopeElement<n> and SecurityCheck<n> with the names of the relevant scope element and security check:

     "scopeElementMapping": {
         "ScopeElement1": "[SecurityCheck1 SecurityCheck2 ...]",
         ["ScopeElement2": "[SecurityCheck1 SecurityCheck2 ...]"
         ...]
     }

     For example, the following code maps two scope elements:

     1. The UserAuth scope element is mapped to a custom UserAuthentication security check
     2. The SSOUserValidation scope element is mapped to the predefined LtpaBasedSSO security check, and to a custom CredentialsValidation security check.

     "scopeElementMapping": {
         "UserAuth": "UserAuthentication",
         "SSOUserValidation": "LtpaBasedSSO CredentialsValidation"
     }

  3. Deploy your copy of the application-descriptor JSON file to MobileFirst Server. See Application configuration.

  We can edit this definition at any time, as needed. To remove all scope-element mapping for our application, create a new copy of the application-descriptor file, delete the scopeElementMapping object, and redeploy the descriptor file to the server.

Results

After you successfully map one or more scope elements, we can see your defined scope elements in the Scope-Elements Mapping table on the application Security console page. In addition, we can see the scope-mapping property definition in the application descriptor: in the console, go to the application Configuration Files tab. In the Application-Descriptor JSON File section, we can see a copy of the application-descriptor JSON file. Search for the scopeElementMapping property definition in this file. This definition object contains one or more name/value data pairs of the following format:

"ScopeElement": "[SecurityCheck1 SecurityCheck2 ...]"

For example, the following code maps two scope elements:

1. The UserAuth scope element is mapped to a custom UserAuthentication security check
2. The SSOUserValidation scope element is mapped to the predefined LtpaBasedSSO security check, and to a custom CredentialsValidation security check.

"scopeElementMapping": {
    "UserAuth": "UserAuthentication",
    "SSOUserValidation": "LtpaBasedSSO CredentialsValidation"
}

Parent topic: OAuth resource protection