Sharing Applications Between Multiple Groups

WSO2 API Manager provides the facility for users to share their applications and subscriptions with a specific logical group/groups such as an organization. As a result of application sharing, users can view and modify applications and subscriptions belonging to other users in the same group or a different group.

This is available only as a WUM update and is effective from 23rd December 2017 (2017-12-23). For more information on updating WSO2 API Manager, see Updating WSO2 Products.

Enabling the group sharing feature

Shutdown the server if its running. Execute the following query in your API Manager database. Database vendor specific create statements for the AM_APPLICATION_GROUP_MAPPING table can be found in the <APIM_HOME>/dbscripts/apimgt folder, after you receive the WUM update.

CREATE TABLE AM_APPLICATION_GROUP_MAPPING (
    APPLICATION_ID INTEGER NOT NULL,
    GROUP_ID VARCHAR(512) NOT NULL,
    TENANT VARCHAR(255),
    PRIMARY KEY (APPLICATION_ID,GROUP_ID,TENANT),
    FOREIGN KEY (APPLICATION_ID) REFERENCES AM_APPLICATION(APPLICATION_ID) ON DELETE CASCADE ON UPDATE CASCADE
);

If you are already using the existing group sharing feature you need to add the grouped mapping to the AM_APPLICATION_GROUP_MAPPING table. Previously, groupings were saved with the tenant domain in the AM_APPLICATION table in column GROUP_ID.
e.g., carbon.super/wso2.com
The group IDs will be stored in the AM_APPLICATION_GROUP_MAPPING table as follows
```
+----------------+----------+--------------+
| APPLICATION_ID | GROUP_ID | TENANT       |
+----------------+----------+--------------+
|              1 | wso2.com | carbon.super |
+----------------+----------+--------------+
```
Use a mysql query to insert the records into the newly created AM_APPLICATION_GROUP_MAPPING table. A sample is given below.
```
INSERT INTO AM_APPLICATION_GROUP_MAPPING ( `APPLICATION_ID`,`GROUP_ID`,`TENANT`)
(SELECT APPLICATION_ID,SUBSTRING_INDEX(GROUP_ID,'/',-1) AS GROUP_ID, SUBSTRING_INDEX(GROUP_ID,'/',1) AS TENANT  FROM AM_APPLICATION)
```
Note that the above query is supported for mysql. you can use a similar query which supports your database. As an alternative, you can log in to the store and share the applications with the preferred groups.

After completing database changes, open the <API-M_HOME>/repository/conf/api-manager.xml file. Under the APIStore configurations section, enable EnableMultipleGroupId and uncomment the GroupIDExtractor class.

Sample Configuration

<APIStore>
<EnableMultipleGroupId>true</EnableMultipleGroupId>              
<GroupingExtractor>
org.wso2.carbon.apimgt.impl.DefaultGroupIDExtractorImpl
</GroupingExtractor>
<CompareCaseInsensitively>true</CompareCaseInsensitively>
        <DisplayURL>false</DisplayURL>
        <URL>https://localhost:${mgt.transport.https.port}/store</URL>
...              
</APIStore>

Restart the server after doing the changes.

Using the group sharing feature

Group IDs are extracted using a GroupingExtractor class which is an implementation of NewPostLoginExecutor interface. The default implementation is done through the DefaultGroupIDExtractorImpl class. The organization claim is extracted using the group ID. If a particular user is in more than one organization, provide the organizations as a string separated by commas.

The steps below show how to use the group sharing feature

Start WSO2 API Manager and click Sign-up.
Sign up to the API store as two different users(e.g., usera, userb) belonging to the the same organizations. Click Show Additional Details to set the organization.
Sign in as usera and add application App_A.
Enter the Group ID as org1 and press enter. Click Add. App_A will be shared with all the users in org1 group.
Sign out of the API Store. Sign in as userb.
Go to the Applications tab. You will see App_A which was added by usera.

Note that the name of the application creator is appended to the application name to differentiate the applications.
Subscribe to the default API using App_A.
Log in to the API Store as usera. The subscriptions for App_A by userb will be displayed.

Extending the group ID extractor

The default implementation picks the organization claim as the group ID. The organization names are returned in a string array. To use a different claim or a different type of group ID , should create your own group ID extractor class by extending NewPostLoginExecutor interface and overriding the method below.

String[] getGroupingIdentifierList(String response);

This particular method will be called when a user is logging into the store and it will return all the groupIds for the logged in user. After logging in users will be able to see the applications created by themselves, and the applications shared with groupIds returned by getGroupingIdentifierList Method

Defining a custom user claim as the group extractor claim

You need to get the latest product updates for your product to use this feature in the current version of WSO2 API-M. This feature is available as a product update in WSO2 API-M 2.1.0 from June 12, 2018 onwards.

Note that you can deploy updates in a production environment only if you have a valid subscription with WSO2. Read more about WSO2 Updates.

You can use this WUM update to configure the user claim of your choice from a configuration file rather than use the hard-coded organization claim URI. Thereby, this allows you to have the flexibility of using your own custom claim.

To define a custom user claim URI as the default group extractor claim URI, add the following configuration under the <APIStore> tag in the <APIM_HOME>/repository/conf/api-manager.xml file.

Format

<DefaultGroupExtractorClaimUri>[custom-claim]</DefaultGroupExtractorClaimUri>

Example

<DefaultGroupExtractorClaimUri>http://wso2.org/claims/role</DefaultGroupExtractorClaimUri>