Skip to content

Commit 6991903

Browse files
scott45scott45
authored
Merge pull request #144 from tazama-lf/dev
feat: Release V2.1.0
2 parents bec4c3a + fc912e8 commit 6991903

File tree

113 files changed

+2238
-655
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

113 files changed

+2238
-655
lines changed

‎Guides/demo-ui-guide.md

+416
Large diffs are not rendered by default.

‎Guides/drawio-guide.md

+3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
<!-- SPDX-License-Identifier: Apache-2.0 -->
22

3+
## Guide for including diagrams in markdown files <!-- omit in toc -->
4+
5+
36
- [Introduction](#introduction)
47
- [Tazama Template](#tazama-template)
58
- [Create and Update diagrams in draw.io](#create-and-update-diagrams-in-drawio)

‎Guides/full-service-full-stack-docker-tazama.md

+44-326
Large diffs are not rendered by default.

‎Guides/keycloak-operator.md

+313
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,313 @@
1+
### KeyCloak Operator Guide for Tazama
2+
3+
Official documentation found [here](https://www.keycloak.org/docs/23.0.6/server_admin/index.html)
4+
#### Logging into Admin Console
5+
6+
An admin account would have been created with KeyCloak deployment and management console is reached at the following endpoint:
7+
`{keycloak_url}/admin/master/console`
8+
9+
#### Creating a Realm
10+
First we need to create a Realm for Tazama to house our management of users and credentials. Realm creation is available at the KeyCloak web admin panel. Note a default master realm will exist but we will want a realm for our custom entity.
11+
12+
<details open>
13+
<summary>
14+
Navigate Realm
15+
</summary>
16+
17+
![1-create-realm-nav](../images/keycloak/1-create-realm-nav.png)
18+
19+
</details>
20+
21+
<details open>
22+
<summary>
23+
Create Realm
24+
</summary>
25+
26+
![2-create-realm](../images/keycloak/2-create-realm.png)
27+
</details>
28+
29+
---
30+
31+
#### Creating a Client
32+
We want to create a client to be able to authenticate and authorize using KeyCloak. In our scenario we are using the `auth lib` in Tazama. So we want to create a client for this purpose.
33+
To create a client first ensure we are on the right realm on the dropdown top left then navigate to the create client button under Clients.
34+
35+
<details open>
36+
<summary>
37+
Navigate Client
38+
</summary>
39+
40+
![3-create-client-nav](../images/keycloak/3-create-client-nav.png)
41+
42+
Then you can create the client
43+
</details>
44+
45+
<details open>
46+
<summary>
47+
Create Client
48+
</summary>
49+
50+
![4-create-client](../images/keycloak/4-create-client.png)
51+
52+
And enable authentication and authorization
53+
</details>
54+
55+
56+
<details open>
57+
<summary>
58+
Client Capabilities
59+
</summary>
60+
61+
![5-create-client-capability](../images/keycloak/5-create-client-capability.png)
62+
63+
Now that you have created a client just need to navigate to the client-secret as these details are needed by the auth-lib to function.
64+
</details>
65+
66+
<details open>
67+
<summary>
68+
Client Id and Secret
69+
</summary>
70+
71+
![6-client-id-and-secret](../images/keycloak/6-client-id-and-secret.png)
72+
73+
We have now created the following variables for auth-lib.
74+
75+
| Variable | Value |
76+
|-----------|---------------------|
77+
| **client_id** | auth-lib-client |
78+
| **client_secret** | sqqabDGAxJD8z01FhqOqPxJrYYmC1ViH |
79+
80+
</details>
81+
82+
---
83+
84+
#### Creating roles
85+
Roles are permissions to define varying scope of access for users (also clients) in a KeyCloak realm. Roles can either be created on the realm level or in the individual client level. For this use case we will only be using realm roles.
86+
To create a realm role navigate to Realm roles and click on Create role button.
87+
88+
<details open>
89+
<summary>
90+
Navigate Realm
91+
</summary>
92+
93+
![7-realm-role-nav](../images/keycloak/7-realm-role-nav.png)
94+
95+
Here we can create many roles for different permissions we will use in `auth lib`
96+
Let's create a role for `POST_V1_EVALUATE_ISO20022_PAIN_001_001_11`
97+
</details>
98+
99+
<details open>
100+
<summary>
101+
Create Realm Role
102+
</summary>
103+
104+
![8-realm-role-create](../images/keycloak/8-realm-role-create.png)
105+
106+
We can repeat this process for `POST_V1_EVALUATE_ISO20022_PAIN_013_001_09`, `POST_V1_EVALUATE_ISO20022_PACS_008_001_10` and `POST_V1_EVALUATE_ISO20022_PACS_002_001_12`
107+
</details>
108+
109+
110+
---
111+
112+
#### Creating groups
113+
Now that we have a roles defined we can create a group with roles assigned to them. To create a group navigate to Groups and click on create group button.
114+
115+
<details open>
116+
<summary>
117+
Navigate Group
118+
</summary>
119+
120+
![9-groups-nav](../images/keycloak/9-groups-nav.png)
121+
122+
Let's create a group called tazama-tms to assign the role(s) we previously created to the tazama-tms group.
123+
</details>
124+
125+
<details open>
126+
<summary>
127+
Create Group
128+
</summary>
129+
130+
![10-groups-create](../images/keycloak/10-groups-create.png)
131+
132+
Then click on the group and navigate to Role mappings to assign the role(s)
133+
134+
</details>
135+
136+
<details open>
137+
<summary>
138+
Navigate Group Role Mappings
139+
</summary>
140+
141+
![11-groups-role-mappings](../images/keycloak/11-groups-role-mappings.png)
142+
</details>
143+
144+
<details open>
145+
<summary>
146+
Assign Group Role Mappings
147+
</summary>
148+
149+
![12-groups-role-mappings-assign](../images/keycloak/12-groups-role-mappings-assign.png)
150+
151+
We now have a tazama-tms group but no users. Let's create some users next.
152+
</details>
153+
154+
---
155+
156+
#### Creating users
157+
Users are individuals that will authenticate through KeyCloak to obtain permissions to use Tazama.
158+
To create a user in KeyCloak navigate to the Users section and click on add user button.
159+
160+
<details open>
161+
<summary>
162+
Navigate Users
163+
</summary>
164+
165+
![13-users-nav](../images/keycloak/13-users-nav.png)
166+
167+
Then let's fill in the user details and additionally let the user join the tazama-tms group.
168+
</details>
169+
170+
<details open>
171+
<summary>
172+
Create User and Join Group
173+
</summary>
174+
175+
![14-users-create-and-group-join](../images/keycloak/14-users-create-and-group-join.png)
176+
177+
While the user is created a password was not yet set. So let's create a password for the newly created user under Credentials
178+
</details>
179+
180+
<details open>
181+
<summary>
182+
Set User Password
183+
</summary>
184+
185+
![15-users-set-password](../images/keycloak/15-users-set-password.png)
186+
---
187+
![16-users-set-password-extra](../images/keycloak/16-users-set-password-extra.png)
188+
189+
Congratulations. You now have a user with the appropriate roles to interact with Tazama TMS.
190+
191+
If you do not want the user to interact to the UI components of KeyCloak this would be the end.
192+
</details>
193+
194+
<details>
195+
<summary>
196+
<strong>Additionally</strong>
197+
</summary>
198+
If the user is expected to change their password the temporary password option should stay toggled at password creation or on the client page you can set required actions to `update password` and `verify email`.
199+
This will require the user to login to the KeyCloak account portal. The link is found by the Clients sidebar for the account entries home URL.
200+
<details>
201+
<summary>
202+
Account Portal
203+
</summary>
204+
205+
![17-account-portal](../images/keycloak/17-account-portal.png)
206+
207+
</details>
208+
</details>
209+
210+
---
211+
212+
#### Deleting users
213+
Deleting users are simple.
214+
We navigate to the Users section
215+
216+
<details open>
217+
<summary>
218+
Navigate Users
219+
</summary>
220+
221+
![18-users-del-nav](../images/keycloak/18-users-del-nav.png)
222+
223+
We check the user(s) we want to delete and press the delete user button.
224+
</details>
225+
226+
<details open>
227+
<summary>
228+
Deleting a User
229+
</summary>
230+
231+
![19-users-deletion](../images/keycloak/19-users-deletion.png)
232+
233+
The user is deleted.
234+
</details>
235+
236+
---
237+
238+
#### Local Deployment
239+
<details>
240+
<summary>
241+
<strong>Docker Compose</strong>
242+
</summary>
243+
<details open>
244+
<summary>
245+
docker-compose.yaml
246+
</summary>
247+
248+
```yaml
249+
services:
250+
postgres:
251+
image: postgres:16.2
252+
volumes:
253+
- postgres_data:/var/lib/postgresql/data
254+
environment:
255+
POSTGRES_DB: ${POSTGRES_DB}
256+
POSTGRES_USER: ${POSTGRES_USER}
257+
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
258+
networks:
259+
- kc_net
260+
261+
keycloak:
262+
image: quay.io/keycloak/keycloak:23.0.6
263+
command: start
264+
environment:
265+
KC_HOSTNAME: localhost # local use only
266+
KC_HOSTNAME_STRICT_BACKCHANNEL: false # local use only
267+
KC_HTTP_ENABLED: true # local use only
268+
KC_HOSTNAME_STRICT_HTTPS: false # local use only
269+
KC_HOSTNAME_PORT: 8080
270+
KC_HEALTH_ENABLED: true
271+
KEYCLOAK_ADMIN: ${KEYCLOAK_ADMIN}
272+
KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}
273+
KC_DB: postgres
274+
KC_DB_URL: jdbc:postgresql://postgres/${POSTGRES_DB}
275+
KC_DB_USERNAME: ${POSTGRES_USER}
276+
KC_DB_PASSWORD: ${POSTGRES_PASSWORD}
277+
ports:
278+
- 8080:8080
279+
restart: always
280+
depends_on:
281+
- postgres
282+
networks:
283+
- kc_net
284+
285+
volumes:
286+
postgres_data:
287+
driver: local
288+
289+
networks:
290+
kc_net:
291+
driver: bridge
292+
```
293+
</details>
294+
<details open>
295+
<summary>
296+
.env
297+
</summary>
298+
299+
```yaml
300+
POSTGRES_DB=keycloak_db
301+
POSTGRES_USER=keycloak_db_user
302+
POSTGRES_PASSWORD=keycloak_db_user_password
303+
KEYCLOAK_ADMIN=admin
304+
KEYCLOAK_ADMIN_PASSWORD=admin
305+
```
306+
</details>
307+
</details>
308+
309+
310+
311+
312+
313+

‎Knowledge-Articles/Entity-Resolution/Entity-Resolution-Explained.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ The table below lists the data fields available in the Mojaloop messages that co
115115
| geoCode.latitude | The Latitude of the service initiating Party. | Y | Y | | |
116116
| geoCode.longitude | The Longitude of the service initiating Party. | Y | Y | | |
117117

118-
Ref: [ISO20022 and Tazama | Mojaloop to ISO 20022 mapping](https://github.com/frmscoe/docs/blob/dev/Knowledge-Articles/iso20022-and-tazama.md#mojaloop-to-iso-20022-mapping)
118+
Ref: [ISO20022 and Tazama | Mojaloop to ISO 20022 mapping](https://github.com/tazama-lf/docs/blob/dev/Knowledge-Articles/iso20022-and-tazama.md#mojaloop-to-iso-20022-mapping)
119119

120120
Ref: [https://docs.mojaloop.io/api-snippets/?urls.primaryName=v1.1](https://docs.mojaloop.io/api-snippets/?urls.primaryName=v1.1)
121121

‎LICENSE

+1-12
Original file line numberDiff line numberDiff line change
@@ -175,18 +175,7 @@
175175

176176
END OF TERMS AND CONDITIONS
177177

178-
APPENDIX: How to apply the Apache License to your work.
179-
180-
To apply the Apache License to your work, attach the following
181-
boilerplate notice, with the fields enclosed by brackets "[]"
182-
replaced with your own identifying information. (Don't include
183-
the brackets!) The text should be enclosed in the appropriate
184-
comment syntax for the file format. We also recommend that a
185-
file or class name and description of purpose be included on the
186-
same "printed page" as the copyright notice for easier
187-
identification within third-party archives.
188-
189-
Copyright [yyyy] [name of copyright owner]
178+
Copyright [2024] [Tazama]
190179

191180
Licensed under the Apache License, Version 2.0 (the "License");
192181
you may not use this file except in compliance with the License.

‎Product/complete-example-of-a-network-map.md

+7-3
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@
1313
"txTp": "pacs.002.001.12",
1414
"typologies": [
1515
{
16-
"id": "typology_processor@1.0.0",
17-
"cfg": "1.0.0",
16+
"id": "typology-processor@1.0.0",
17+
"cfg": "001@1.0.0",
1818
"rules": [
1919
{
2020
"id": "[email protected]",
@@ -23,6 +23,10 @@
2323
{
2424
"id": "[email protected]",
2525
"cfg": "1.0.0"
26+
},
27+
{
28+
"id": "[email protected]",
29+
"cfg": "none"
2630
}
2731
]
2832
}
@@ -32,4 +36,4 @@
3236
}
3337
```
3438

35-
This network map executes two rule processors (006 and 078) when a pacs.002 transaction is received and summarizes the rule results into typology 001.
39+
This network map executes two rule processors (006 and 078) when a pacs.002 transaction is received and summarizes the rule results into typology 001. The event flow rule processor (EFRuP) is also configured in this typology.

0 commit comments

Comments
 (0)