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.
Security in itself is a broad term.

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.
In other words, the available methods within eMagiz to verify this

In the microlearnings that will follow we will zoom in on configuring roles and users to
ensure that although a user can access the API Gateway they still cannot perform operations for which they are not authorized.

Should you have any questions, please contact academy@emagiz.com.

1. Prerequisites

• Basic knowledge of the eMagiz platform

2. Key concepts

This microlearning centers around securing the API Gateway in general.
With securing we mean: Configuring a method that will be used to validate that the clients are who they say they are
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

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.
Security in itself is a broad term.

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.
In other words, the available methods within eMagiz to verify this.

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.

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)

Choosing this option will lead you to the following screen. Here you can add a New security scheme or edit the existing one.
Take into account that you should select one security scheme that is in place for all your environments.

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.
This is the most low-level solution available in terms of authorization.
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.
If not the client will receive a 401 Unauthorized

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

This method is frequently used in a situation that demands less technical complexity and deals with less sensitive data.
An eMagiz best practice is to always combine this option with the use of a client certificate whenever possible.

3.2 OpenID Connect

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

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.

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.
To configure this option simply configure the security scheme as follows:

3.3 OAuth 2.0 Client Credentials

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.

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.

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.

3.4 OAuth 2.0 Authorization code

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.

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.

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.

4. Key takeaways

• Security in itself is a broad term.
• Focus of this microlearning was on the check if someone was allowed in
• eMagiz support three methods out of the box
• API Key
• OpenID Connect
• OAuth 2.0

5. Suggested Additional Readings

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