Last modified by Eva Torken on 2023/09/20 14:15
Show last authors
1 {{container}}{{container layoutStyle="columns"}}(((
2
3 In this microlearning, we will discuss how you can ensure that the correct credentials are sent to the external system. There are many forms of OAuth 2.0 authorization flows. The one that we see most for interchanging data between applications is the client credentials flow. In this microlearning, we will learn how you need to configure certain components within your flow to successfully send the relevant authentication information to the external system. In the following microlearning, we will look at a different OAuth 2.0 authorization flow, the authorization code flow.
4
5 Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
6
7 == 1. Prerequisites ==
8
9 * Intermediate knowledge of the eMagiz platform
10
11 == 2. Key concepts ==
12
13 This microlearning centers around authenticating ourselves with an external REST web service via the OAuth 2.0 Client Credentials flow.
14 With OAuth 2.0 flow, we mean: A specific flow that enables a third-party application to obtain limited access to an HTTP service
15 With REST, we mean: A web service that adheres to the RESTful principles
16
17 * The application (eMagiz) pushes data to an external REST web service (or API)
18 * To do so eMagiz needs to be authorized to read and/or write data
19 * OAuth 2.0 is an industry-standard that is widely implemented, especially in combination with API development
20
21 == 3. Authorization - OAuth 2.0 Client Credentials ==
22
23 There are many forms of OAuth 2.0 authorization flows. The one that we see most for interchanging data between applications is the client credentials flow. In this microlearning, we will learn how you need to configure certain components within your flow to successfully send the relevant authentication information to the external system. In the following microlearning, we will look at a different OAuth 2.0 authorization flow, the authorization code flow. Key parts to consider for this microlearning are:
24
25 * The application (eMagiz) pushes data to an external REST web service (or API)
26 * To do so eMagiz needs to be authorized to read and/or write data
27 * OAuth 2.0 is an industry-standard that is widely implemented, especially in combination with API development
28
29 Within eMagiz, you have a lot of components that help you build your flows. The same applies when you want to authorize yourselves with an external party with the help of OAuth 2.0. So let us discuss how we should make that happen.
30
31 === 3.1 REST Template ===
32
33 When you navigate to the Create phase you can open an exit flow and see whether you already have an HTTP outbound component within your exit flow. If not please add an HTTP outbound component (gateway or channel adapter) to the flow. In the previous microlearning, we focused on these components so we won't focus on these components in this microlearning.
34
35 To ensure that a certain authorization is added to this HTTP outbound component we need to add the support object called REST Template to the flow:
36
37 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-authorization-oauth-client-credentials--rest-template-search.png]]
38
39 After you have added the support object to the canvas and given it a name you can open it by double clicking on the component. eMagiz will show you the following pop-up:
40
41 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-authorization-oauth-client-credentials--rest-template-empty.png]]
42
43 As you can see here you can select various authentication schemes. In this microlearning, the focus is on OAuth 2.0 Client Credentials therefore we select the button called OAuth2 authorization. Selecting this option will open another pop-up. In this pop-up, we need to fill in the relevant information for the authentication scheme that we have selected.
44
45 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-authorization-oauth-client-credentials--pop-up-empty.png]]
46
47 In this case, we have to fill in several items. At first, we need to fill in a registration ID. This can be anything you want. The best practice is to name it after the runtime you are currently working on. The second configuration element is the Grant Type. Here you can select the various grant types that are available within the various OAuth 2.0 authorization flows. For this microlearning, we will select the Client Credentials option.
48
49 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-authorization-oauth-client-credentials--pop-up-first-config.png]]
50
51 The second part of your configuration has to do with the 'username' and 'password' you need to send to the OAuth 2.0 endpoint to retrieve a token you can use in subsequent calls. In OAuth 2.0 the 'username' and 'password' are called client id and client secret. As always in scenarios where an information element can change between environments, you should use a property reference and determine the correct value on a per-environment basis.
52
53 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-authorization-oauth-client-credentials--pop-up-second-config.png]]
54
55 The third part of your configuration has to do with the scope. When the external party has defined a scope (i.e. to what do you have access exactly) you should define that exact scope in this configuration. If the external party has not defined any scope you can fill it with a default static value. As always in scenarios where an information element can change between environments, you should use a property reference and determine the correct value on a per-environment basis.
56
57 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-authorization-oauth-client-credentials--pop-up-third-config.png]]
58
59 Our fourth part of the config on the basic tab identifies which endpoint will provide us with the token necessary to authenticate ourselves in subsequent calls to the actual endpoints. In most cases, these endpoint has the word token in it. As always in scenarios where an information element can change between environments, you should use a property reference and determine the correct value on a per-environment basis.
60
61 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-authorization-oauth-client-credentials--pop-up-fourth-config.png]]
62
63 Now that we have configured the basic tab we need to turn our attention to the advanced tab. Here we need to configure some additional elements. For token persistence, we choose the option In Memory as it is not necessary to store the data somewhere so it can be used again later in this OAuth 2.0 flow. Furthermore, we select the option Form as Authentication Method. This will ensure that the information is sent correctly to the endpoint.
64
65 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-authorization-oauth-client-credentials--pop-up-advanced-config.png]]
66
67 When you are satisfied you can press Save. This will lead you back to the original pop-up that now indicates the authentication scheme you have selected.
68
69 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-authorization-oauth-client-credentials--rest-template-filled-in.png]]
70
71 Once again you can press Save if you are satisfied with your configuration.
72
73 === 3.2 Link REST Template to HTTP Outbound Component ===
74
75 Now that we have successfully configured the REST Template the last thing we need to do is link the REST Template to the HTTP Outbound component in your flow. To do so open the HTTP Outbound component by double-clicking on the component. After you have opened the component you need to navigate to the advanced tab. On this tab, you can select a REST Template. Select the one we have just configured from the drop-down menu and press Save.
76
77 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-authorization-oauth-client-credentials--link-rest-template-to-http-outbound-component.png]]
78
79 Now you have successfully linked the REST Template to the HTTP Outbound Gateway. If you ever want to validate whether a support object is indeed linked to your component simply click on it once. That way eMagiz will show the selected component and all other components that are linked to it.
80
81 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-authorization-oauth-client-credentials--link-rest-template-to-http-outbound-component-visual.png]]
82
83 == 4. Key takeaways ==
84
85 * eMagiz pushes data to or retrieves data from the external party
86 * eMagiz offers two HTTP Outbound components to call a REST Webservice. Choose based on whether you want a response or not
87 * To do so eMagiz needs to be authorized to read and/or write data
88 * OAuth 2.0 is an industry-standard that is widely implemented, especially in combination with API development
89 * Don't forget to link the support object to the HTTP Outbound component
90
91 == 5. Suggested Additional Readings ==
92
93 If you are interested in this topic and want more information on it please read the help text provided by eMagiz.
94
95 )))((({{toc/}}))){{/container}}{{/container}}