Security - eMagiz

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

In this microlearning, we will focus on securing the API Gateway. To ensure that not everyone can access the operations that you have made available you need security.

3

Security in itself is a broad term.

4

5

The focal point of this microlearning is the general security measures that specify how clients should prove to the API Gateway that they are who they say they are.

6

In other words, the available methods within eMagiz to verify this

7

8

In the microlearnings that will follow we will zoom in on configuring roles and users to

9

ensure that although a user can access the API Gateway they still cannot perform operations for which they are not authorized.

10

11

Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].

12

13

== 1. Prerequisites ==

14

15

* Basic knowledge of the eMagiz platform

16

17

== 2. Key concepts ==

18

19

This microlearning centers around securing the API Gateway in general.

20

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

21

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

22

23

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.

== 3. Security ==

To ensure that not everyone can access the operations that you have made available you need security.

34

Security in itself is a broad term.

35

36

The focal point of this microlearning is the general security measures that specify how clients should prove to the API Gateway that they are who they say they are.

37

In other words, the available methods within eMagiz to verify this.

38

39

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.

46

47

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)

48

49

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

50

51

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

52

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

53

54

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.

59

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

60

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.

61

If not the client will receive a 401 Unauthorized

62

63

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

64

65

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

66

67

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

68

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

69

70

=== 3.2 OpenID Connect ===

71

72

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.

73

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.

74

75

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.

76

77

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.

78

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

79

80

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

81

82

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

83

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

84

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

85

86

=== 3.3 OAuth 2.0 Client Credentials===

87

88

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.

89

90

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.

91

92

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

93

94

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

95

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

96

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

97

98

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

99

100

=== 3.4 OAuth 2.0 Authorization code===

101

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.

102

103

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

104

105

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.

106

107

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.

108

109

== 4. Key takeaways ==

110

111

* Security in itself is a broad term.

112

* Focus of this microlearning was on the check if someone was allowed in

113

* eMagiz support three methods out of the box

114

* API Key