Security - eMagiz

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

In this microlearning, we will explore the essential steps to securing your API Gateway. In today’s digital landscape, protecting your APIs is crucial to ensuring that only authorized users can access your services. We will begin by covering general security measures to verify client identities and introduce the built-in options eMagiz provides for safeguarding your API Gateway. In the following microlearning, we will delve deeper into configuring roles and user permissions to ensure robust protection for your API operations.

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 securing the API Gateway in general.

13

14

* With securing we mean: Configuring a method that will be used to validate that the clients are who they say they are

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

== 3. Security ==

While "security" is a broad term, this microlearning focuses specifically on the general security measures that ensure clients can prove their identity to the API Gateway, i.e., how clients should prove to the API Gateway that they are who they say they are. We will then explore the methods eMagiz provides to verify client authenticity.

20

21

When you want to set up your security in combination with the eMagiz API Gateway we offer three options out of the box:

* API Key

* OpenID Connect

* OAuth 2.0

All three methods can be supplemented with the requirement that a client needs to send along a client certificate when executing the call.

28

29

To choose the security measure for your API Gateway you can navigate to Design and open the context menu on API level (the API segment in the middle of the Design overview)

30

31

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-security-api-gateway--security-context-menu.png]]

32

33

Choosing this option will lead you to the following screen. Here you can add a New security scheme or edit the existing one.

34

Take into account that you should select one security scheme that is in place for all your environments.

35

36

Below we will talk about each of these three options.

=== 3.1 API Key ===

The simplest form of authentication is with the help of a so-called API Key.

41

This is the most low-level solution available in terms of authorization.

42

In this case, the client will send a specific key that they have received from us in a certain header and we will check if the value is correct.

43

If not the client will receive a 401 Unauthorized

44

45

Best practice is to name the header x-api-key. A example of how you can configure this is:

46

47

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-security-api-gateway--security-api-key.png]]

48

49

This method is frequently used in a situation that demands less technical complexity and deals with less sensitive data.

50

An eMagiz best practice is to always combine this option with the use of a client certificate whenever possible.

51

52

=== 3.2 OpenID Connect ===

53

54

Both OpenID Connect and OAuth 2.0 work with an authorization server. On this server it is specified if you have rights and if so to what exactly.

55

To authenticate themselves they first have to send a request to the authorization server. In all subsequent calls, they will have to use the information in the bearer to authenticate themselves.

56

57

As you can see this becomes a lot more complex to implement for an outside party. On the flip side, it is a lot better in terms of security.

58

59

When using the IDP provided within the platform you can leave the configuration as it is configured for you on default when you select this option for implementing your eMagiz API Gateway solution.

60

To configure this option simply configure the security scheme as follows:

61

62

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-security-api-gateway--security-open-id-connect.png]]

63

64

{{info}}Do note that the IPD provided by the platform is restricted in the following manner:

65

- It will only work for environments for which a cloud slot is known and active

66

- Before creating your first user(s), a manual action is needed at the side of eMagiz to link the IPD to your specific cloud slot(s). For more information on this please contact us at [[productmanagement@emagiz.com>>mailto:productmanagement@emagiz.com]]{{/info}}

67

68

=== 3.3 OAuth 2.0 Client Credentials===

69

70

As said OpenID Connect and OAuth 2.0 are very similar solutions. Only not all OAuth 2.0 providers accept OpenID connect. Another reason to not use the authorization server that eMagiz can provide you is the fact you already have your authorization server (i.e. Azure AD) in which you already manage this.

71

72

For cases that are covered by either of those reasons, we offer the OAuth 2.0 option. When using the IDP provided within the platform you can leave the configuration as it is configured for you on default when you select this option.

73

74

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-security-api-gateway--security-oauth.png]]

75

76

{{info}}Do note that the IPD provided by the platform is restricted in the following manner:

77

- It will only work for environments for which a cloud slot is known and active

78

- Before creating your first user(s), a manual action is needed at the side of eMagiz to link the IPD to your specific cloud slot(s). For more information on this please contact us at [[productmanagement@emagiz.com>>mailto:productmanagement@emagiz.com]]{{/info}}

79

80

When you opt to use your own Identity Provider to govern the authorization you need to specify the correct Issuer URL and Token URL. More on this and the additional consequences of making this choice will be explained in this [[microlearning>>doc:Main.eMagiz Academy.Microlearnings.Expert Level.Securing Data Traffic.expert-securing-data-traffic-api-gw-security-external-idp||target="blank"]].

81

82

=== 3.4 OAuth 2.0 Authorization code===

83

One can also choose to use the grant type Authorization code as part of OAuth 2.0 security as described in the previous paragraph. When chosing OAuth 2.0 as the security mechanism of choice for your API Gateway the default grant type is the 'Client Credentials' grant type. However, we have functionality that allows you to deviate from this standard on a system by system basis. You can change this selection by editing the system configuration in Design. Once the 'Authorization code' grant type has been selected as one can see below, the specific call-back URLs (comma separated list) need to provided to support the login process that comes with this grant type.

84

85

[[image:Main.Images.Microlearning.WebHome@crashcourse-apigw-authorization-code.png]]

86

87

Once this is done, the first time the requesting application will need the provided username and password to login to our IDP Server. This is usually an object inside the application requestor. This username and password will be generated by our IDP server. Once done the configuration will work like the grant type client credentials.

88

89

Note that to test this security configuration via the Swagger UI sections of eMagiz, the same two-step approach is needed to test and validate the operation to which the system has been granted access to.

90

91

== 4. Key takeaways ==

92

93

* Security encompasses various aspects, and in this session we focused on how to verify client identities to ensure authorized access.

94

* eMagiz offers three key methods for securing your API Gateway:

95

** API Key: A basic form of authentication using a unique key.

96

** OpenID Connect: A more advanced method leveraging an authorization server for authentication.

97

** OAuth 2.0: A flexible option that can be tailored to use different grant types, including Client Credentials and Authorization Code.

98

* In the next microlearning, we will cover how to configure roles and permissions to further control access to your API operations.

99

100

== 5. Suggested Additional Readings ==

101

102

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

103

104

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

105

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

106

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

107

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

108

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

109

*** [[Updating your API Gateway Operations (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.API Management.intermediate-api-management-updating-your-api-gateway-operations||target="blank"]]

110

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

111

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

112

*** [[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"]]

113

* [[API Gateway Security (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=%22API+Gateway+Security%22||target="blank"]]

114

115

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

Wiki source code of Security

Navigation