Skip to content

Commit 0ca77ad

Browse files
ldclakmalldclakmal
committed
Update markdown files
1 parent cb85f18 commit 0ca77ad

File tree

5 files changed

+104
-24
lines changed

5 files changed

+104
-24
lines changed

‎README.md‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -18,17 +18,22 @@ The examples, use-cases, demos, resources related to microservices security patt
1818
[![stars](https://img.shields.io/github/stars/ldclakmal/ballerina-security?style=social)](https://github.com/ldclakmal/ballerina-security)
1919
[![followers](https://img.shields.io/github/followers/ldclakmal?style=social)](https://github.com/ldclakmal)
2020

21-
### Examples
21+
### Project Structure
2222

23-
- [HTTP client and service examples secured with different auth mechanisms](https://github.com/ldclakmal/ballerina-security/tree/master/examples/http)
24-
- [gRPC client and service examples secured with JWT auth mechanism](https://github.com/ldclakmal/ballerina-security/tree/master/examples/grpc)
25-
- [WebSocket client and service examples secured with JWT auth mechanism](https://github.com/ldclakmal/ballerina-security/tree/master/examples/websocket)
26-
- [WebSub hub, publisher and subscriber examples secured with JWT auth mechanism](https://github.com/ldclakmal/ballerina-security/tree/master/examples/websub)
23+
#### [Test Suite](./test-suite)
2724

28-
### Scenarios
25+
This section demonstrates an automated Ballerina security test-suite which contains authentication and authorization related integration scenarios and Ballerina by examples (BBEs). These tests run on demand with the provided Ballerina version in GitHub secrets. Refer to the [workflow](https://github.com/ldclakmal/ballerina-security/actions).
2926

30-
- [Simple inventory management system](https://ldclakmal.me/ballerina-security/scenarios/scenario-1/)
31-
- [Advanced inventory management system](https://ldclakmal.me/ballerina-security/scenarios/scenario-2/)
27+
[![BBE](https://github.com/ldclakmal/ballerina-security/actions/workflows/bbe.yml/badge.svg)](https://github.com/ldclakmal/ballerina-security/actions/workflows/bbe.yml)
28+
[![Integration](https://github.com/ldclakmal/ballerina-security/actions/workflows/integration.yml/badge.svg)](https://github.com/ldclakmal/ballerina-security/actions/workflows/integration.yml)
29+
30+
#### [Examples](./examples)
31+
32+
This section demonstrates the examples with authentication and authorization for different transport protocols supported by Ballerina. The client and servers are secured with different auth protocols.
33+
34+
#### [Scenarios](./scenarios)
35+
36+
This section demonstrates the real-world scenarios which has authentication and authorization requirements and how that can be supported with Ballerina.
3237

3338
### Guides & Documentations
3439

‎examples/README.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
# Ballerina Security Examples
22

3-
This directory contains the example scenarios written by [Ballerina](https://ballerina.io) programming language for different protocols supported.
3+
This section demonstrates the examples with authentication and authorization for different transport protocols supported by Ballerina. The client and servers are secured with different auth protocols.
44

5-
1. [HTTP](./http)
6-
2. [gRPC](./grpc)
7-
3. [WebSocket](./websocket)
8-
4. [WebSub](./websub)
9-
5. [NATS](./nats)
5+
1. [HTTP](https://github.com/ldclakmal/ballerina-security/tree/master/examples/http)
6+
2. [gRPC](https://github.com/ldclakmal/ballerina-security/tree/master/examples/grpc)
7+
3. [WebSocket](https://github.com/ldclakmal/ballerina-security/tree/master/examples/websocket)
8+
4. [WebSub](https://github.com/ldclakmal/ballerina-security/tree/master/examples/websub)
9+
5. [NATS](https://github.com/ldclakmal/ballerina-security/tree/master/examples/nats)

‎scenarios/README.md‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,21 @@
11
# Ballerina Security Scenarios
22

3-
This directory contains the real-world scenarios written by [Ballerina](https://ballerina.io) programming language.
3+
This section demonstrates the real-world scenarios which has authentication and authorization requirements and how that can be supported with Ballerina.
44

5-
### [Scenario 1](./scenario-1)
5+
### [Ballerina Secure Token Service (STS)](./sts)
6+
7+
Ballerina STS which supports OAuth2 token issuing and validation.
8+
9+
Refer to the [README](./sts/README.md) for more information.
10+
11+
### [Simple inventory management system](./scenario-1)
612

713
Simple inventory management system, with 2 secured microservices, and a secured API gateway, which connects to an LDAP user store and trusts OAuth2 authorization server.
814

9-
User `Jane`, the admin, connects to `Admin Microservice` through the REST API of API gateway using HTTPS for management purposes. User `Alice`, a customer, connects to `Inventory Microservice` through the REST API of API gateway using HTTPS for purchasing items. All the APIs are authenticated with different types of authentication mechanisms such as basic auth, JWT auth, OAuth2 etc. and secured with TLS as well. Refer to the [diagram](./scenario-1/scenario-1.png) and [README](./scenario-1/README.md) for more information.
15+
Refer to the [diagram](./scenario-1/scenario-1.png) and [README](./scenario-1/README.md) for more information.
1016

11-
### [Scenario 2](./scenario-2)
17+
### [Advanced inventory management system](./scenario-2)
1218

1319
Advanced inventory management system, with 4 secured microservices, and a secured API gateway, which connects to an LDAP user store and trusts OAuth2 authorization server.
1420

15-
User `Jane`, the admin, connects to `Admin Microservice` through the REST API of API gateway using HTTPS for management purposes. User `Alice`, a customer, connects to `Inventory Microservice` through the REST API of API gateway using HTTPS for purchasing items. User `Bob`, another customer, connects to `Inventory Microservice` through the GraphQL API of API gateway using HTTPS for searching items. `Electronic` and `Fashions` microservices are connected to `Inventory Microservice` and can be accessed via gRPC APIs. All the HTTP, GraphQL, gRPC APIs are authenticated with different types of authentication mechanisms such as basic auth, JWT auth, OAuth2 etc. and secured with TLS as well. Refer to the [diagram](./scenario-2/scenario-2.png) and [README](./scenario-2/README.md) for more information.
21+
Refer to the [diagram](./scenario-2/scenario-2.png) and [README](./scenario-2/README.md) for more information.

‎scenarios/sts/README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Ballerina STS
2+
3+
Ballerina Secure Token Service (STS) which supports OAuth2 token issuing and validation. This is published into Docker Hub as well.
4+
5+
![Docker Pulls](https://img.shields.io/docker/pulls/ldclakmal/ballerina-sts)
6+
7+
### How to run
8+
9+
In order to run this in local machine, we need to have [Ballerina Swan Lake Alpha 5](https://ballerina.io/downloads/) installed.
10+
11+
- Run as a container: `$ docker run -p 9090:9090 ldclakmal/ballerina-sts`
12+
- Run using source code: `$ bal run ballerina-sts.bal`
13+
14+
### How to test
15+
16+
- Get an access-token with a scope:
17+
18+
```shell
19+
curl -kv -u FlfJYKBD2c925h4lkycqNZlC2l4a:PJz0UhTJMrHOo68QQNpvnqAY_3Aa -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -d "grant_type=client_credentials&scope=view-order" https://localhost:9090/oauth2/token
20+
```
21+
22+
- Refresh an access-token with a scope:
23+
24+
```shell
25+
curl -kv -u 3VTwFk7u1i366wzmvpJ_LZlfAV4a:TNOH0ZklJm8sqS9U3IMMAZVth78a -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -d "grant_type=refresh_token&refresh_token=<ACCESS_TOKEN>&scope=view-order" https://localhost:9090/oauth2/token
26+
```
27+
28+
- Validate an access-token:
29+
30+
```shell
31+
curl -kv -u admin:admin -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=<ACCESS_TOKEN>' https://localhost:9090/oauth2/introspect
32+
```

‎test-suite/README.md‎

Lines changed: 42 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,45 @@
33

44
# Ballerina Security Test Suite
55

6-
This is an automated Ballerina security test suite which contains authentication and authorization related scenarios. These tests run on demand with the provided Ballerina version.
6+
This section demonstrates an automated Ballerina security test-suite which contains authentication and authorization related integration scenarios and Ballerina by examples (BBEs). These tests run on demand with the provided Ballerina version in GitHub secrets. Refer to the [workflow](https://github.com/ldclakmal/ballerina-security/actions).
7+
8+
### Directory Structure
9+
10+
```shell
11+
test-suite
12+
|
13+
|__ packages
14+
| |__ bbe
15+
| | |__ access-control
16+
| | | |__ basic-auth-file-store
17+
| | | |__ basic-auth-ldap-store
18+
| | | |__ jwt-auth
19+
| | | |__ oauth2-bearer-token
20+
| | | |__ oauth2-client-credentials-grant
21+
| | | |__ oauth2-password-grant
22+
| | | |__ oauth2-refresh-token-grant
23+
| | |
24+
| | |__ security
25+
| | | |__ crypto
26+
| | | |__ url
27+
| | | |__ jwt
28+
| |
29+
| |__ integration
30+
| | |__ basic-auth-file-store
31+
| | |__ basic-auth-ldap-store
32+
| | |__ jwt-auth
33+
| | |__ oauth2
34+
| |
35+
| |__ resources
36+
|
37+
|__ scripts
38+
|__ bbe
39+
| |__ access-control
40+
| |__ security
41+
|
42+
|__ integration
43+
|__ resources
44+
```
745

846
### Secured services
947

@@ -14,7 +52,7 @@ This is an automated Ballerina security test suite which contains authentication
1452

1553
##### Steps:
1654
1. User configurations are defined in `Config.toml`
17-
2. Ballerina service is secured with Basic Auth with file user store.
55+
2. Ballerina service is secured with Basic Auth with file user store. Inbound tokens are validated with the user store configured in `Config.toml`.
1856
3. CURL client send requests to Ballerina service.
1957

2058
#### 2. Basic Auth - LDAP user store
@@ -25,7 +63,7 @@ This is an automated Ballerina security test suite which contains authentication
2563

2664
##### Steps:
2765
1. User configurations are provided to OpenLDAP server with `.ldif`
28-
2. Ballerina service is secured with Basic Auth with LDAP user store. Inbound tokens are validated with the OpenLDAP server.
66+
2. Ballerina service is secured with Basic Auth with LDAP user store. Inbound tokens are validated with the user store defined in OpenLDAP server.
2967
3. CURL client send requests to Ballerina service.
3068

3169
#### 3. JWT Auth
@@ -37,8 +75,7 @@ This is an automated Ballerina security test suite which contains authentication
3775

3876
##### Steps:
3977
1. Service providers are defined in WSO2 IS STS.
40-
2. Ballerina service is secured with JWT Auth. Inbound tokens are validated by Ballerina with the use of configurations
41-
provided by WSO2 IS STS.
78+
2. Ballerina service is secured with JWT Auth. Inbound tokens are validated by Ballerina with the use of configurations provided by WSO2 IS STS.
4279
3. CURL client send request to WSO2 IS STS and get the JWT.
4380
4. CURL client send requests to Ballerina service with the received JWT.
4481

0 commit comments

Comments
 (0)