Configure Roles and Users

{{container}}{{container layoutStyle="columns"}}(((

In this microlearning, we will focus on learning how you can configure roles and users for the API Gateway in eMagiz. We will walk through the essential steps to set up your API Gateway by defining which clients have access to which operations. This process involves setting roles and users to ensure proper access control.

3

4

If you have any questions along the way, feel free to reach out to us at [[academy@emagiz.com>>mailto:academy@emagiz.com]].

5

6

== 1. Prerequisites ==

7

8

* Basic knowledge of the eMagiz platform

9

10

== 2. Key concepts ==

11

12

This microlearning centers around configuring roles and users for the API Gateway solution of eMagiz.

13

* 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

14

* With users, we mean: Any system or user that is granted access to such actions via the role

15

* 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

16

17

== 3. Configure roles and users ==

18

19

A crucial part of setting up your API Gateway with the help of RESTful services is defining which client has access to which operation. 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. The first part is done in Capture and Design, which we have covered in the previous microlearnings. The second part is done in Deploy, which will be discussed in this microlearning.

20

21

Below we will discuss each of these parts in more detail.

=== 3.1 Capture ===

In Capture, you can add a so-called 'consuming' system of an API Gateway.

26

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.

27

The type of system you choose does not matter. Both single-tenant and multi-tenant systems can fulfill these purposes.

28

29

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.

30

By choosing the standard system, you make the implicit choice that one user (i.e., that system) has one specific role.

31

By choosing the multi-tenant system, you state that multiple users have the same role.

32

33

If you choose a multi-tenant system, make sure also to define the tenants before you continue.

34

35

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.

36

37

A possible solution of two separate 'consuming' systems of the same resource can be represented as follows.

38

39

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-configure-roles-and-users--capture-filled-in-consuming-systems.png]]

=== 3.2 Design ===

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.

44

This can be done by activating the checkbox in Design.

45

46

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.

47

48

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

49

whereas the 'consuming' system (i.e., the role) Microlearning Write has no access to the GET HTTP Methods operation

50

51

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-configure-roles-and-users--design-handed-out-rights.png]]

=== 3.3 Deploy ===

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.

56

57

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.

58

59

==== 3.3.1 Test the API as portal user ====

60

61

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.

62

This method ensures that you do not mix the authentication and authorization of your test with tests from an external system.

63

64

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.

65

66

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-configure-roles-and-users--deploy-import-portal-user.png]]

67

68

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.

69

70

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-configure-roles-and-users--deploy-tab-assigned-roles.png]]

71

72

Based on your needs, you can give the portal user all roles or assign a subset of the roles to the portal user.

73

74

After you have verified the settings and are satisfied with how the rights per role and user are configured, you can update

75

these settings per environment by pressing the Apply to environment button.

76

By pressing this button, you indicate that your design choices can be actualized in Deploy for that particular environment.

77

78

==== 3.3.2 Apply to environment ====

79

80

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.

81

82

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-configure-roles-and-users--deploy-apply-to-environment.png]]

83

84

{{warning}}Note that before you can "Apply to environment" in Acceptance and Production you need to press the "Transfer from Design" button first.{{/warning}}

85

86

==== 3.3.3 Actualize "User Management" ====

87

88

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.

89

90

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

91

92

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

93

94

==== 3.3.4 Communicate Credentials ====

95

96

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

97

98

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-configure-roles-and-users--show-user-credentials.png]]

99

100

== 4. Key takeaways ==

101

102

* 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.

103

* The first part is done in Capture and Design. The second part is done in Deploy

104

* A 'consuming' system equals a role

105

* A 'consuming' tenant or system equals a user

106

107

== 5. Suggested Additional Readings ==

108

109

If you are interested in this topic and want more information, please read the help text provided by eMagiz and the following link.

110

111

* [[Crash Course (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.WebHome||target="blank"]]

112

** [[Crash Course API Gateway (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.WebHome||target="blank"]]

113

*** [[Swagger UI (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-swagger-ui||target="blank"]]

114

* [[Intermediate Level (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.WebHome||target="blank"]]

115

** [[Solution Architecture (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Solution Architecture.WebHome||target="blank"]]

116

*** [[System vs Multi-tenant System (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Solution Architecture.intermediate-solution-architecture-system-vs-multi-tenant-system||target="blank"]]

117

* [[Advanced Level (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Advanced Level.WebHome||target="blank"]]

118

** [[Solution Architecture (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Advanced Level.Solution Architecture.WebHome||target="blank"]]

119

*** [[Key differences Design & Deploy Architecture (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Advanced Level.Solution Architecture.advanced-solution-architecture-diffs-design-deploy.WebHome||target="blank"]]

120

* [[Expert Level (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Expert Level.WebHome||target="blank"]]

121

** [[Securing Data Traffic (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Expert Level.Securing Data Traffic.WebHome||target="blank"]]

122

*** [[API Gateway Security - External IDP (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Expert Level.Securing Data Traffic.expert-securing-data-traffic-api-gw-security-external-idp||target="blank"]]

123

*** [[Data Exchange (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Expert Level.Securing Data Traffic.expert-securing-data-traffic-data-exchange||target="blank"]]

124

* [[Roles and Users (Search Results)>>url:https://docs.emagiz.com/bin/view/Main/Search?sort=score&sortOrder=desc&highlight=true&facet=true&r=1&f_space_facet=0%2FMain.&l_space_facet=10&f_type=DOCUMENT&f_locale=en&f_locale=&f_locale=en&text=%22Roles+and+Users%22||target="blank"]]

125

)))((({{toc/}}))){{/container}}{{/container}}

Wiki source code of Configure Roles and Users

Navigation