Author: Chidambaram, Arundev (arunc@softwareag.com)
Supported Versions: 10.5 and above
Overview of the tutorial
This tutorial introduces the concept of Teams and how to make use of it effectively in API Gateway . In this tutorial we will go through the following topics in detail.
- Managing a Team
- Adding groups to the Team
- Creating API and assigning a Team
- Changing the Team
- Changing the Team with Approval flow
- Privilege for the asset owners
- Conflicting teams between API and Applications
- Global Team assignments
- Effect of Teams on OAuth / OpenID Scopes
- Effect of Teams on Promotion / Search
Why?
The Team support feature allows you to group the users who work in a project, or users with similar roles, as a team. Using this feature, you can assign assets for each team and specify the access level of team members based on the team members' project requirements.
This feature is helpful for organizations that have multiple teams, who work on different projects. Users can access only the assets that are assigned to them. For example, consider an organization with different teams such as Development, Configuration Management, Product Analytics, and Quality Assurance. Each of these teams needs access to different assets at different levels. That is, developers would require APIs to develop applications and they require the necessary privileges to manage APIs and applications. Similarly, analysts would want the necessary privileges to view performance dashboards of assets. In such scenarios, you can group users based on their roles as a team and assign them the necessary privileges based on their responsibility.
Prerequisite steps
Team work support is available in API Gateway version 10.5 or above. Enable team work feature by following the below steps.
Step 1
Login to API Gateway as Administrator user
Step 2
Go to Administration->Extended settings and set enableTeamWork property to true,
The changes will be reflected in the next login so logout and login again in API Gateway.
Details
Prior to the 10.5 version, users were given the necessary privileges using Access Profiles. Starting version 10.5, you can limit the access of your asset to the required team members and assign access privileges using the Team support feature. A team can be defined as a group of users with a set of defined responsibilities. You can create teams from the User Management section of API Gateway by including the required user groups and assigning them the required functional privilege. You can also assign a Team administrator for each team, who can add or modify team members.
Users with the Manage user administration privilege can create teams. When creating a team, you can assign:
Team administrator
You can assign a user or a user group as team administrator. Team administrators can add or remove users from a team. When you assign a user group as team administrator, all users of the groups can modify team members. When team administrators, who do not have the Manage user administration functional privilege log on to API Gateway, they can view only the teams assigned to them in the Teams tab of the Administration page.
Functional privileges for the team members
The functional privileges assigned to a team determines the accessibility of assets to the respective team members. For example, if you assign all privileges under the APIs, Policies, and Applications section, then the team members can manage APIs and applications assigned to their teams and perform operations related to policies.
Team members
You can assign user groups to the team. Team members can access the assets assigned to their teams and perform operations on the assets based on their functional privileges. After you have created teams, you can assign assets to teams in one of the following ways:
Assign team during asset creation
When you create an asset, API Gateway provides an option to select the teams for the asset. You can select more than one team for an asset. You can modify the teams assigned by following the Change ownership process explained in later part of this article.
Using Global Team Assignment rule
This is a preferred method to assign teams when you already have assets to which you want to assign teams to. You can create global assignment rules that are applied to assets and assign teams to them. You can specify one or more conditions in a rule.When an asset satisfies the conditions specified in a rule, the asset is assigned to the teams specified in the rule. When you create and activate a rule, the rule is applied to the existing assets and teams are assigned accordingly
The team, Default, is available in API Gateway when the feature is enabled and all API Gateway users are added to this team by default. Assets, which are not assigned to any team, are assigned to the Default team. Hence, all API Gateway users can view the assets that are part of the Default team. However, users can perform actions on the assets based on the functional privileges assigned to them.
To illustrate all the use-cases we are going to create users, groups and assign them to teams based on the table below.
Groups
|
SecurityAPIDevGroup
|
|---|
| Allice |
| Bob |
| John |
|
SecurityAPITestGroup
|
|---|
| William |
|
TravelAPIDevGroup
|
|---|
| Peter |
| John |
| Robert |
|
AnalyticsGroup
|
|---|
| Frank |
| Edward |
Teams
|
SecurityAPITeam |
Groups | Team Administrator | Functional Privilege |
|---|---|---|---|
| SecurityAPIDevGroup | Allice |
|
|
TravelAPIDevTeam |
Groups | Team Administrator | Functional Privilege |
|---|---|---|---|
| TravelAPIDevGroup | Peter |
|
|
AnalyticsTeam |
Groups | Team Administrator | Functional Privilege |
|---|---|---|---|
| AnalyticsGroup | Frank |
No functional privilege selected. |
Use-case 1: Managing a Team
First use-case is a demo of how to create teams and assign a team administrator to the team.
Roles of actors in this Use-case
| Administrator (User with Manage user administration functional privilege) |
|
|
Team Administrator (Assumption that user doesn't have Manage user administration functional privilege) |
|
Step 1
Login to API Gateway with a user who has Manage user administration functional privilege.
Step 2
Create the users mentioned in the table with their login password as password.
Step 3
Create and assign users to the groups as mentioned in the table.
Step 4
Create team SecurityAPITeam and assign Allice as team administrator.
- Navigate to User management → Teams and click on Add team button.
- In the Basic Information section fill in the team name and assign Allice as team administrator
- In the Functional privileges section check and Activate / Deactivate APIs functional privilege.
- In the Groups section search for SecurityAPIDevGroup which was created earlier in Step 3 and select.
Similarly follow the steps and create teams for TravelAPIDevTeam and AnalyticsTeam with the respective functional privileges mentioned in the table.
Step 5
Save the changes.
Use-case 2: Adding groups to the Team
In this Use-case , we are going to login as a team administrator and assign a group to an existing team. Right now the groups present in SecurityAPITeam is SecurityAPIDevGroup , We are going to add SecurityAPITestGroup to SecurityAPITeam.
Step 1
Login API Gateway as Allice
Step 2
Navigate to User management → Teams
Since Allice is team administrator and doesn't have Manage user administration functional privilege only teams tabs will be visible.
In the teams tab Allice can view the teams which has Allice as team administrator.
Step 3
Navigate to User management → Teams->SecurityAPITeam→Functional privileges. Since Allice is team administrator and doesn't have Manage user administration functional privilege, she can view the functional privileges assigned to the team and cant add/update or delete any functional privileges.
Step 4
Navigate to User management → Teams→SecurityAPITeam→Groups. In the Groups section search for SecurityAPITestGroup which was created earlier and select.
Step 5
Save the changes.
Use-case 3: Creating API and assigning a Team
In this Use-case we are going to login as Allice, create an API and assign SecurityAPITeam
Step 1
Login API Gateway as Allice
Step 2
Go to Create API Screen. There will be Team drop-down which will list down the teams the logged in user belongs. Allice is part of SecurityAPITeam and Default. Now select SecurityAPITeam in the Team drop down , give api1_sec_team as name to the API and click Create button.
Step 3
Now the API api1_sec_team will be visible only to members of SecurityAPITeam. To verify we will now login as Bob and see whether we are able to view api1_sec_team API.
Step 4
Verify api1_sec_team API is not visible to users of other teams. To verify that we will now login as William and see whether we are able to view api1_sec_team API.
Use-case 4: Changing the Team
Changing team can be done by users who have Change ownership/teams functional privilege. The recommended approach is to create a team and have just Change ownership/teams functional privilege and add users who needs this privilege.
Groups
|
ManagersGroup
|
|---|
| John |
Teams
|
Managers |
Groups | Team Administrator | Functional Privilege |
|---|---|---|---|
| ManagersGroup | John |
|
In this Use-case we are going to add TravelAPIDevTeam team to API api1_sec_team.
Step 1
Follow Use-case 3: Creating API and assigning a team by logging in as Peter, create an API api2_travel_team and assign TravelAPIDevTeam team to the API.
Step 2
Login API Gateway as Allice. Navigate to api1_sec_team API. As you can see there is no option for Allice to change team as Allice is not part of Managers team.
Step 3
Login API Gateway as John. Navigate to api1_sec_team API. You can see an edit icon near Team.
Step 4
Click on the Edit icon. Navigate to api1_sec_team API. John is a member of SecurityAPITeam and TravelAPIDevTeam teams, so both the teams will appear in the drop-down and now select TravelAPIDevTeam team from the drop-down.
Now api1_sec_team API is part of SecurityAPITeam and TravelAPIDevTeam teams.
Step 5
To verify this we now login as Peter who is a member of TravelAPIDevTeam team and check whether api1_sec_team API is visible.
Peter will be able to see 2 APIs api1_sec_team and api2_travel_team
Use-case 5: Changing the Team with Approval flow
An approval flow can be enabled if a user changes teams. Until the request is approved the asset's team will not be changed. In this case John who is a part of Managers group will be adding SecurityAPITeam to api2_travel_team API. An approval request for changing team will generated. This approval for change team will be approved by members of Approvers team selected in the Approval Configuration. Once approved the SecurityAPITeam will be added to api2_travel_team.
Step 1
Login API Gateway as Administrator and navigate Approval Configuration → Change Owner/Teams and click on Enable. In the approvers drop down , select Administrators . This implies members part of Administrators team will be able to approve the change team request.
Step 2
Login API Gateway as John. Navigate to api2_travel_team API. You can see an edit icon near Team. Click on the edit icon. John is a member of SecurityAPITeam and TravelAPIDevTeam teams, so both the teams will appear in the drop-down and now select SecurityAPITeam team from the drop-down.
You can navigate to My pending Requests and see the change team request for the API
Step 3
Login API Gateway as Administrator, navigate to My Pending Requests and click approve the change team request.
Step 4
Login API Gateway as Allice. In the API page you will able to see api1_sec_team and api2_travel_team both the APIs.
Use-case 6: Privilege for the asset owners
The owner of the assets will be able to access the assets even if the owner is not part of the team the asset belongs. In this usecase we are going to create an API by logging as Robert who is a part of TravelAPIDevTeam. Then we will change the team of the API to SecurityAPITeam. Robert will be still able to access the API as he is the owner however Peter who is a part of TravelAPIDevTeam will not be able to access the API.
Step 1
Login API Gateway as Robert, create an API api3_travel_team and assign team to TravelAPIDevTeam.
Step 2
Login API Gateway as John.Navigate to api3_travel_team API. Remove the team TravelAPIDevTeam and add SecurityAPITeam.
Step 3
Login API Gateway as Peter. API api3_travel_team will not be visible.
Step 4
Login API Gateway as Robert. API api3_travel_team will visible as he is the owner of the API.
Use-case 7: Conflicting teams between API and Applications
Users will be able to just view applications name descriptions if the application is associated to an API and team of the application is different as of the logged in user.
Step 1
Login to API Gateway as Allice. Create an application app1_security_team by associating SecurityAPITeam team and register app1_security_team application to api1_sec_team API. Allice will be able to view the API and application as the both the API and application are part of SecurityAPITeam.
Step 2
Login to API Gateway as John. Create an application app2_travel_team by associating TravelAPIDevTeam team . Since John is a part of SecurityAPITeam and TravelAPIDevTeam, He will be able to view app2_travel_team application and api1_sec_team API . Register app2_travel_team application to api1_sec_team API
Step 3
Login to API Gateway as Allice. Navigate to api1_sec_team APIs application section.
Allice will be able to see the app2_travel_team even though the application belonging to a different team. But Allice will not be able to disassociate the application from the API. In the Find applications search Allice will be able to search applications that are part of Allice's team.
Use-case 8: Global Team assignments
There is an AnalyticsTeam team ,whose responsibility to view the analytics data of all the APIs present in API Gateway . The members of the AnalyticsTeam should not have any functional privilege other than viewing the data. To achieve this we can make use of global team assignments , for which we can create a rule and assign AnalyticsTeam team to all the APIs. Team assignment rules are used to assign teams to existing assets and the ones being created. Users with Manage user administration functional privilege will be able to manage global team assignments.
Step 1
Login to API Gateway as Administrator. Navigate to User Management → Global team assignments and click Add global team assignment
Step 2
Fill in the name and description for the rule.
Step 3
Click on the filters section. Select all the asset types and don't add any filters.
Step 4
Click on the Team assignments section. Search and add AnalyticsTeam
Step 5
Enable the created team assignment rule
Now all the assets in API Gateway will be part of AnalyticsTeam
Step 6
Login as Frank who is a part of AnalyticsTeam and navigate to APIs , Applications page. You will be able to see all the APIs and applications so far created in API Gateway .
Step 7
Navigate to Analytics in the profile menu and analytics for all the assets in API Gateway can be viewed.
Use-case 9: Effect of Teams on OAuth / OpenID Scopes
Users having Manage scope mapping will be able to search all the APIs in API Gateway irrespective of the team the user belongs. To demonstrate this use-case create an user Rob and the corresponding groups and teams OauthScopeMappingTeam.
Groups
|
OauthScopeMappingGroup
|
|---|
| Rob |
Teams
|
OauthScopeMappingTeam |
Groups | Team Administrator | Functional Privilege |
|---|---|---|---|
| OauthScopeMappingGroup | Rob |
Manage scope mapping |
The user Rob is belonging to OauthScopeMappingTeam team.
Step 1
In this step we are going to create a dummy scope in the authorization server to demonstrate the Use-case.
Login to API Gateway as Administrator. Navigate to Administration → Security → JWT/OAuth/OpenID and create a scope read by clicking on the authorization server alias local.
Step 2
Login to API Gateway as Rob. Navigate to OAuth/OpenID scopes from the menu.
Step 3
Click on Map scope button and authorization scope read which we created in Step 1
Step 4
Click on API scopes section. The user Rob who is not part of SecurityAPITeam or TravelAPIDevTeam will be able to view the APIs belonging to the team. This is the privilege enjoyed by the user who has Manage scopes functional privilege.
Use-case 10: Effect of Teams on Promotion / Search
Teams are a hard dependency on the assets in API Gateway . So when we export or promote assets Teams will also be exported or promoted. There are team filters in the Promotions and Global search page where users can search the assets based on the teams. To demonstrate this Use-case we will login as John who is part of SecurityAPITeam, TravelAPIDevTeam and Managers. Team filters will have these teams in Promotions, APIs and Global search screen.
Step 1
Login to API Gateway as John. Navigate to APIs screen.
Step 2
Navigate to global search screen.
Step 3
Navigate to Promotion Management → Promotions screen
Downloadable artifacts
- APIs.zip
- Applications.zip
- users.zip
- groups.zip
- teams.zip
- Analytics_team_rule.zip
- EmployeeManagementSwagger.json
Analytics_team_rule.zip (1.47 KB)
APIs.zip (22.2 KB)
Applications.zip (14.9 KB)
EmployeeManagementSwagger.json (10 KB)
groups.zip (4.46 KB)
teams.zip (4.18 KB)
users.zip (7.37 KB)