Wiki source code of Configure Roles and Users

Last modified by Erik Bakker on 2024/02/12 14:27
Show last authors
1 {{container}}{{container layoutStyle="columns"}}(((
2 In this microlearning, we will focus on learning how you can configure roles and users for the API Gateway.
3 A crucial part of setting up your (API) Gateway with the help of RESTful services is defining which client has access to which operation.
4
5 Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
6
7 == 1. Prerequisites ==
8
9 * Basic knowledge of the eMagiz platform
10
11 == 2. Key concepts ==
12
13 This microlearning centers around configuring roles and users for the API Gateway solution of eMagiz.
14 * With roles, we mean: Any action that is available to be executed on an internal system that you want to make publicly available via the API Gateway
15 * With users, we mean: Any system or user that is granted access to such actions via the role
16 * With API Gateway, we mean: A collection of RESTful API operations that can be published to the outside world to give them access to applications that are linked to your business process
17
18 In eMagiz, you have a straightforward way to define "consuming" entities of an API Gateway and assign the correct roles and rights on the role and user level. This is done in a two-part process.
19 The first part is done in Capture and Design, and the second part is done in Deploy.
20
21 == 3. Configure roles and users ==
22
23 A crucial part of setting up your (API) Gateway with the help of RESTful services is defining which client has access to which operation.
24 In eMagiz, you have a straightforward way to define "consuming" entities of an API Gateway and assign the correct roles and rights on the role and user level. This is done in a two-part process.
25 The first part is done in Capture and Design, and the second part is done in Deploy.
26
27 Below we will discuss each of these parts in more detail.
28
29 === 3.1 Capture ===
30
31 In Capture, you can add a so-called 'consuming' system of an API Gateway.
32 To define a 'consuming' system, you need to draw a line from the system to eMagiz, indicating that an external system is 'consuming' the API Gateway.
33 The type of system you choose does not matter. Both single-tenant and multi-tenant systems can fulfill these purposes.
34
35 The choice between creating a standard or multi-tenant system is based on what you want to achieve in terms of giving access to roles and users.
36 By choosing the standard system, you make the implicit choice that one user (i.e., that system) has one specific role.
37 By choosing the multi-tenant system, you state that multiple users have the same role.
38
39 If you choose a multi-tenant system, make sure also to define the tenants before you continue.
40
41 If you already have a system that also wants to 'consume' an API Gateway, you don't have to create a new system but can draw a line from the existing system towards eMagiz.
42
43 A possible solution of two separate 'consuming' systems of the same resource can be represented as follows.
44
45 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-configure-roles-and-users--capture-filled-in-consuming-systems.png]]
46
47 === 3.2 Design ===
48
49 When you add a "consuming" system of type API Gateway in Capture, you have the ability in Design to assign rights to that "consuming" system on one or more operations.
50 This can be done by activating the checkbox in Design.
51
52 By activating the checkbox in Design, you're telling eMagiz that this particular system (and all underlying users) has the right to access the operation you have just selected.
53
54 In the example below, it means that the 'consuming' system (i.e., the role) Microlearning Read Write has access to the GET HTTP Methods operation
55 whereas the 'consuming' system (i.e., the role) Microlearning Write has no access to the GET HTTP Methods operation
56
57 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-configure-roles-and-users--design-handed-out-rights.png]]
58
59 === 3.3 Deploy ===
60
61 Changes made in Design are automatically updated in Deploy for the Test environment when you navigate to the User management tab, given that the operation is already available in a Release. This means that when you open the User management tab, you will see all users and roles in the correct configuration based on the checkboxes selected in Design.
62
63 To synchronize the Deploy phase of User Management with your configuration in Design for Acceptance and Production, you must first press the "Transfer from Design" on the role level and subsequently on the user level.
64
65 ==== 3.3.1 Test the API as portal user ====
66
67 Suppose you want to test the API operations yourself without breaking the barrier between tests executed by external parties and developers. In that case, you can create an API user based on your portal user. This can be done via the Import button in the User management tab.
68 This method ensures that you do not mix the authentication and authorization of your test with tests from an external system.
69
70 After you have pressed the import button, you can select which user you want to create a User. Here you can choose only those users that have access to this project.
71
72 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-configure-roles-and-users--deploy-import-portal-user.png]]
73
74 After you have created the user, you can assign roles. For example, to Assign a role, you select the freshly imported user and open the tab called Assign Roles.
75
76 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-configure-roles-and-users--deploy-tab-assigned-roles.png]]
77
78 Based on your needs, you can give the portal user all roles or assign a subset of the roles to the portal user.
79
80 After you have verified the settings and are satisfied with how the rights per role and user are configured, you can update
81 these settings per environment by pressing the Apply to environment button.
82 By pressing this button, you indicate that your design choices can be actualized in Deploy for that particular environment.
83
84 ==== 3.3.2 Apply to environment ====
85
86 After you have verified the settings and are satisfied with how the rights per role and user are configured, you can update these settings per environment by pressing the Apply to environment button. By pressing this button, you indicate that your design choices can be actualized in Deploy for that particular environment.
87
88 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-configure-roles-and-users--deploy-apply-to-environment.png]]
89
90 {{warning}}Note that before you can "Apply to environment" in Acceptance and Production you need to press the "Transfer from Design" button first.{{/warning}}
91
92 ==== 3.3.3 Actualize "User Management" ====
93
94 Read the pop-up you get after pressing this button carefully as it says what your next move is. This next move differs between the Legacy runtime and the 3rd runtime generation.
95
96 {{info}}In the legacy runtime, you need to restart the "all.entry" flow. After you have restarted the "all.entry" flow, you can test the settings via the Swagger UI, which you can access via the Runtime Dashboard -> View Swagger UI. More on that in the next microlearning.{{/info}}
97
98 {{info}}In the 3rd generation runtime, you need to create a new release and deploy this with the help of your deployment plan to an environment. After you have deployed the flow, you can test the settings via the Swagger UI, which you can access via the Runtime Dashboard -> View Swagger UI. More on that in the next microlearning.{{/info}}
99
100 ==== 3.3.4 Communicate Credentials ====
101
102 After you have pressed the Apply to environment button, you can retrieve the relevant authentication information per user by "editing" the user in user management and activating the checkbox "Show user credentials."
103
104 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-configure-roles-and-users--show-user-credentials.png]]
105
106 == 4. Key takeaways ==
107
108 * In eMagiz, you have a straightforward way to define "consuming" entities of an API Gateway and assign the correct roles and rights on the role and user level. This is done in a two-part process.
109 * The first part is done in Capture and Design. The second part is done in Deploy
110 * A 'consuming' system equals a role
111 * A 'consuming' tenant or system equals a user
112
113 == 5. Suggested Additional Readings ==
114
115 If you are interested in this topic and want more information, please read the help text provided by eMagiz.
116
117 )))((({{toc/}}))){{/container}}{{/container}}