Skip to content

Commit 671269e

Browse files
DDH13DDH13
authored
Merge branch '1.1.0' into gprc-docs
2 parents 663d634 + d4cf696 commit 671269e

19 files changed

+254
-123
lines changed

‎en/docs/catalogs/crds/gql_routes_types.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -349,4 +349,6 @@
349349
<hr />
350350
<p><em>
351351
Generated with <code>gen-crd-api-reference-docs</code>.
352-
</em></p>
352+
</em></p>
353+
354+
{!catalogs/samples/gqlroute.md!}

‎en/docs/catalogs/samples/gqlroute.md

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# GQLRoute Sample
2+
3+
The following is a sample GQLRoute CR.
4+
5+
```
6+
apiVersion: dp.wso2.com/v1alpha2
7+
kind: GQLRoute
8+
metadata:
9+
name: graphql-api-route
10+
spec:
11+
hostnames:
12+
- graphql.backend.gw.wso2.com
13+
backendRefs:
14+
- group: dp.wso2.com
15+
kind: Backend
16+
name: gql-backend
17+
rules:
18+
- matches:
19+
- path: hero
20+
type: QUERY
21+
- path: droid
22+
type: QUERY
23+
- path: reviews
24+
type: QUERY
25+
- path: search
26+
type: QUERY
27+
- path: character
28+
type: QUERY
29+
- path: allHumans
30+
type: QUERY
31+
- path: allDroids
32+
type: QUERY
33+
- path: allCharacters
34+
type: QUERY
35+
- path: starship
36+
type: QUERY
37+
- path: createReview
38+
type: MUTATION
39+
- path: human
40+
type: QUERY
41+
parentRefs:
42+
- group: gateway.networking.k8s.io
43+
kind: Gateway
44+
name: wso2-apk-default
45+
namespace: apk
46+
sectionName: httpslistener
47+
```

‎en/docs/control-plane/apk-as-gateway-in-apim/apk-as-gateway-in-apim-qsg.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -128,11 +128,11 @@ Now you can verify the deployment by executing the following command. You will s
128128

129129
### Create Deploy and Publish the API
130130

131-
{!control-plane/api-management/control-plane-create-and-deploy-rest-apis.md!}
131+
{!control-plane/apk-as-gateway-in-apim/api-management/control-plane-create-and-deploy-rest-apis.md!}
132132

133133
### Create Application and Subscribe to the API
134134

135-
{!control-plane/api-management/control-plane-create-application-and-subscription.md!}
135+
{!control-plane/apk-as-gateway-in-apim/api-management/control-plane-create-application-and-subscription.md!}
136136

137137

138138
## Step 3 - Invoke the API

‎en/docs/create-api/create-and-attach-api-policies/api-policies-overview.md

+12-12
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@ API policies are a powerful tool in WSO2 APK for enforcing business logic and mo
66

77
There are a few levels where a Policy attachment can happen in APK resources.
88

9-
| **Level** | **Actor** | **Description** |
10-
|------------------------|----------------|------------------|
11-
| Gateway | System Admin | Any policy which is applicable to all the APIs deployed to gateway runtime should be attached to `Gateway` resource. |
12-
| API | API Owner | Attach a policy which is applicable to all the operations of that API. |
13-
| Operation | API Owner | Attach a policy to an operation of a API. |
9+
| **Level** | **Actor** | **Description** |
10+
| --------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
11+
| Gateway | System Admin | Any policy which is applicable to all the APIs deployed to gateway runtime should be attached to `Gateway` resource. |
12+
| API | API Owner | Attach a policy which is applicable to all the operations of that API. |
13+
| Operation | API Owner | Attach a policy to an operation of a API. |
1414

1515
Attaching a policy to a specific level is descibed under each policy.
1616

@@ -40,16 +40,16 @@ When you have multiple policies attached in different levels policies, you need
4040

4141
Keep in mind that you cannot attach an API policy at two separate levels simultaneously and that the approach for attaching policies varies depending on the interface that you are using (i.e., CLI or REST API interface) to create the APIs.
4242

43-
| **Create an API from:** | **Attach Policies** |
44-
|-------------------------|-----------------------------------------------------------------|
45-
| REST APIs | Attach a policy at API-level or Operation-level |
46-
| Custom Resources (CRs) | Attach a policy at Gateway-level, API-level or Operation-level |
43+
| **Create an API from:** | **Attach Policies** |
44+
| ----------------------- | -------------------------------------------------------------- |
45+
| REST APIs | Attach a policy at API-level or Operation-level |
46+
| Custom Resources (CRs) | Attach a policy at Gateway-level, API-level or Operation-level |
4747

4848
When you attach a policy at the API-level, it will be applied globally to all the operations that correspond to the API. However, when you attach a policy at an operation level, it will only be applicable locally to a specific operation.
4949

5050
## What's Next?
5151

52-
- [Learn to attach API Policies for Interceptor Services](../interceptors/interceptors-overview/)
53-
- [Learn to attach API Policies for Backend JWT Token Manipulation](../backend-jwt-token-manipulation/backend-jwt-token-manipulation-via-rest-api/)
54-
- [Learn to attach API Policies for CORS](../cors/enable-cors-via-rest-api/)
52+
- [Learn to attach API Policies for Interceptor Services](./interceptors/interceptors-overview.md)
53+
- [Learn to attach API Policies for Backend JWT Token Manipulation](./backend-jwt-token-manipulation/overview.md)
54+
- [Learn to attach API Policies for CORS](./cors/enable-cors-via-rest-api.md)
5555

‎en/docs/create-api/create-and-attach-api-policies/backend-jwt-token-manipulation/backend-jwt-token-manipulation-via-crs.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Attach Backend JWT Token manipulation Policy to APIs via CRs
1+
# Backend JWT Manipulation Policy via CRs
22

33
You need to create an `APIPolicy` with referencing to a `BackendJWT` resource under `override` or `default` sections in `APIPolicy.spec`. Then you need to create the `BackendJWT` custom resource with required properties. This policy can be used on both the `SYSTEM_API` and non system APIs separately. To find more information about backend JWT generation, please refer to the [Passing End User Attributes to the Backend](https://apim.docs.wso2.com/en/latest/deploy-and-publish/deploy-on-gateway/choreo-connect/passing-enduser-attributes-to-the-backend-via-choreo-connect/#enabling-the-default-backend-jwt-generator).
44

‎en/docs/create-api/create-and-attach-api-policies/backend-jwt-token-manipulation/backend-jwt-token-manipulation-via-rest-api.md

+108-68
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,113 @@
1-
# Attach Backend JWT Token manipulation Policy to APIs via REST API
1+
# Backend JWT Manipulation Policy via APK Conf
22

3-
There can be scenarios where a backend service needs to make different decisions or respond with different data, depending on the application end-user that consumes an API. This can be facilitated by APK by sending the attributes in a JWT via an HTTP header, to the backend service when the API call is being forwarded.
3+
### Before you begin
44

5-
To find more information about backend JWT generation, please refer to the [Passing End User Attributes to the Backend](https://apim.docs.wso2.com/en/latest/deploy-and-publish/deploy-on-gateway/choreo-connect/passing-enduser-attributes-to-the-backend-via-choreo-connect/#enabling-the-default-backend-jwt-generator).
5+
- [Create an API](../../../get-started/quick-start-guide.md)
66

7-
## Before you begin
7+
### Step 1 - Retrieve existing API configuration
88

9-
- [Create an API](../../../get-started/quick-start-guide.md)
9+
Here, you can use the apk-conf file which is created in [Create an API](../../../get-started/quick-start-guide.md) documentation and save this content into a file named `EmployeeService.apk-conf`.
10+
11+
### Step 2 - Add the API Policy for Backend JWT
12+
13+
A sample API Policy used for sending a JWT to the backend is given below.
14+
```
15+
apiPolicies:
16+
request:
17+
- policyName: "BackendJwt"
18+
parameters:
19+
encoding: Base64
20+
signingAlgorithm: SHA256withRSA
21+
header: X-JWT-Assertion
22+
tokenTTL: 3600
23+
customClaims:
24+
- claim: claim1
25+
value: value1
26+
- claim: claim2
27+
value: value2
28+
```
29+
30+
The configurations that you need when attaching API Policies for Backend JWT manipulation are available in [Backend JWT Configurations section.](#backend-jwt-api-policy-configuration)
31+
32+
The above policy will send the following claims to the backend under the header "X-JWT-Assertion".
33+
34+
```
35+
{
36+
claim1: value1
37+
claim2: value2
38+
}
39+
```
40+
41+
The sample APK configuration content after the modification is shown below.
42+
43+
```
44+
name: "test-backend-jwt"
45+
basePath: "/backend-jwt"
46+
version: "1.0"
47+
type: "REST"
48+
defaultVersion: false
49+
endpointConfigurations:
50+
production:
51+
endpoint: "https://httpbin.org/anything"
52+
operations:
53+
- target: "/test"
54+
verb: "GET"
55+
secured: true
56+
scopes: []
57+
apiPolicies:
58+
request:
59+
- policyName: "BackendJwt"
60+
parameters:
61+
encoding: Base64
62+
signingAlgorithm: SHA256withRSA
63+
header: X-JWT-Assertion
64+
tokenTTL: 3600
65+
customClaims:
66+
- claim: claim1
67+
value: value1
68+
- claim: claim2
69+
value: value2
70+
```
71+
### Step 3 - Deploy the API in APK
72+
73+
Refer to the [Deploy the API in APK](../../../get-started/quick-start-guide.md#deploy-the-api-in-apk) to deploy the API using APK configuration.
74+
75+
### Step 4 - Generate an Acess Token
76+
77+
Follow the [Generate Access Token](../../../develop-and-deploy-api/security/generate-access-token.md) documentation to generate an access token.
78+
79+
### Step 5 - Invoke the API
80+
81+
You can invoke the API using the following command.
82+
83+
```
84+
curl --location 'https://default.gw.wso2.com:9095/backend-jwt/1.0/test' \
85+
--header 'Host: default.gw.wso2.com' \
86+
--header 'Authorization: Bearer <accessToken>
87+
```
88+
89+
Since this guide uses the [httpbin service](https://httpbin.org/anything) which echoes the request and all of its headers, when you invoke the API, you will see a response similar to the following. The header "X-Jwt-Assertion" contains the JWT generated containing the claims.
90+
91+
```
92+
"headers": {
93+
"Accept": "*/*",
94+
"Accept-Encoding": "gzip, deflate, br",
95+
"Host": "httpbin.org",
96+
"X-Jwt-Assertion": "eyJraWQiOiI4.....9UcOovptvkajf6xUqUbIJfMQp9g"
97+
}
98+
```
99+
100+
### Backend JWT API Policy configuration
101+
102+
The configurable fields of the above API policy have been described below.
103+
104+
| Field | Description |
105+
| ---------------- | ----------------------------------------------------------------------------------------- |
106+
| encoding | The encoding mechanism used to encode the Backend JWT. |
107+
| signingAlgorithm | The signing algorithm used to sign the Backend JWT. |
108+
| header | The name of the HTTP header to which the Backend JWT is attached and sent to the backend. |
109+
| tokenTTL | The expiry time of the Backend JWT. |
110+
| customClaims | List of custom claims that needs to be added to the Backend JWT. |
111+
| claim | Name of the claim to send in the BackendJWT. |
112+
| value | Value of the claim to send in the BackendJWT. |
10113

11-
### Backend JWT configuration
12-
13-
<table>
14-
<tbody>
15-
<tr>
16-
<th colspan="2">Field</th>
17-
<th>Description</th>
18-
</tr>
19-
<tr>
20-
<td colspan="2" class="confluenceTd"><pre>encoding</pre></td>
21-
<td class="confluenceTd">The encoding mechanism used to encode the Backend JWT.</td>
22-
</tr>
23-
<tr>
24-
<td colspan="2" class="confluenceTd"><pre>signingAlgorithm</pre></td>
25-
<td class="confluenceTd">The signing algorithm used to sign the Backend JWT.</td>
26-
</tr>
27-
<tr>
28-
<td colspan="2" class="confluenceTd"><pre>header</pre></td>
29-
<td class="confluenceTd">The name of the HTTP header to which the Backend JWT is attached.</td>
30-
</tr>
31-
<tr>
32-
<td colspan="2" class="confluenceTd"><pre>tokenTTL</pre></td>
33-
<td class="confluenceTd">The expiry time of the Backend JWT.</td>
34-
</tr>
35-
<tr>
36-
<td colspan="2" class="confluenceTd"><pre>customClaims</pre></td>
37-
<td class="confluenceTd">List of custom claims that needs to be added to the Backend JWT.</td>
38-
</tr>
39-
</tbody>
40-
</table>
41-
42-
43-
Sample APK configuration content after the modification is shown below.
44-
45-
```
46-
name: "test-backend-jwt"
47-
basePath: "/backend_jwt"
48-
version: "1.0.0"
49-
type: "REST"
50-
defaultVersion: false
51-
endpointConfigurations:
52-
production:
53-
endpoint: "https://httpbin.org/anything"
54-
operations:
55-
- target: "/test"
56-
verb: "GET"
57-
secured: true
58-
scopes: []
59-
apiPolicies:
60-
request:
61-
- policyName: "BackendJwt"
62-
parameters:
63-
encoding: Base64
64-
signingAlgorithm: SHA256withRSA
65-
header: X-JWT-Assertion
66-
tokenTTL: 3600
67-
customClaims:
68-
- claim: claim1
69-
value: value1
70-
- claim: claim2
71-
value: value2
72-
73-
```

‎en/docs/create-api/create-and-attach-api-policies/backend-jwt-token-manipulation/overview.md

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Passing End User Attributes to the Backend
2+
3+
There can be scenarios where a backend service needs to make different decisions or respond with different data, depending on the application end-user that consumes an API. To achieve this, the backend service needs to have access to the respective end-user's data at the time an API call takes place.
4+
5+
This can be facilitated by the Gateway by sending the end user attributes that are defined in the respective user store, in a JWT via an HTTP header, to the backend service when the API call is being forwarded.
6+
7+
The backend JSON Web Token (JWT) contains the claims that are transferred between two parties, such as the end-user and the backend. A claim is an attribute of the user that is mapped to the underlying user store. A set of claims is referred to as a dialect.
8+
9+
If you enable backend JWT generation in the Gateway, each API request will carry a digitally signed JWT, which is in the following format to the backend service.
10+
11+
`{token header}.{claims list}.{signature}`
12+
13+
You can configure backend JWT in two ways.
14+
15+
1. [Using the APK Conf file](./backend-jwt-token-manipulation-via-rest-api.md).
16+
2. [Using CRs](./backend-jwt-token-manipulation-via-crs.md).

‎en/docs/create-api/create-and-attach-api-policies/interceptors/interceptors-overview.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ When you want the policy only to be defined in a single level, then defining the
8787

8888
Configuring an interceptor requires the following two steps.
8989

90-
1. [Implement an interceptor microservice adhering to the Interceptor OpenAPI Definition](https://apim.docs.wso2.com/en/latest/deploy-and-publish/deploy-on-gateway/choreo-connect/message-transformation/interceptor-microservice/interceptor-microservice/)
90+
1. [Implement an interceptor microservice adhering to the Interceptor OpenAPI Definition](https://apim.docs.wso2.com/en/4.2.0/deploy-and-publish/deploy-on-gateway/choreo-connect/message-transformation/interceptor-microservice/interceptor-microservice/)
9191

9292
2. For reference, a sample interceptor service for data conversion between application/json and application/xml data types with interceptor policy CRs can be found here: [request-response-mediation-interceptors](https://github.com/wso2/apk/tree/main/samples/request-response-mediation-interceptors)
9393

‎en/docs/create-api/manage-service-endpoint/manage-resiliency-circuit-breaker.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -93,8 +93,11 @@ operations:
9393
secured: true
9494
scopes: []
9595
```
96-
You can then deploy this API by following the steps in [Create an API](../../get-started/quick-start-guide.md) documentation.
96+
97+
You can then deploy this API by following the steps in the [Deploy the API in APK](../../get-started/quick-start-guide.md#deploy-the-api-in-apk) documentation.
98+
9799
## Via CRs
100+
98101
**Step 1 - Define the CRs**
99102

100103
Define the Backend resource for the API as below.

‎en/docs/create-api/manage-service-endpoint/manage-resiliency-retry-policy.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,9 @@ operations:
8383
secured: true
8484
scopes: []
8585
```
86-
You can then deploy this API by following the steps in [Create an API](../../get-started/quick-start-guide.md) documentation.
86+
87+
You can then deploy this API by following the steps in the [Deploy the API in APK](../../get-started/quick-start-guide.md#deploy-the-api-in-apk) documentation.
88+
8789
## Via CRs
8890

8991
**Step 1 - Define the CRs**

‎en/docs/create-api/manage-service-endpoint/manage-resiliency-timeout.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,8 @@ operations:
7474
scopes: []
7575
```
7676

77-
You can then deploy this API by following the steps in [Create an API](../../get-started/quick-start-guide.md) documentation.
77+
You can then deploy this API by following the steps in the [Deploy the API in APK](../../get-started/quick-start-guide.md#deploy-the-api-in-apk) documentation.
78+
7879
## Via CRs
7980

8081
**Step 1 - Define the CRs**

‎en/docs/create-api/manage-service-endpoint/manage-security-via-crs.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -184,7 +184,7 @@ Create an `HTTPRoute` resource referring to the above `Backend`.
184184

185185
Refer [Step 3](https://apk.docs.wso2.com/en/latest/get-started/quick-start-guide/#step-3-invoke-the-api) in QSG to see how to invoke the API.
186186

187-
In this try out we will use [httpbin service's](https://httpbin.org/) `/get` resource to test the backend security. It echoes back the request details including all the headers. Therefore if the backend security was correctly configured, you should see the ehader `"Authorization": "Basic YWRtaW4KOmFkbWluCg==",` in the received response.
187+
In this try out we will use [httpbin service's](https://httpbin.org/) `/get` resource to test the backend security. It echoes back the request details including all the headers. Therefore if the backend security was correctly configured, you should see the header `"Authorization": "Basic YWRtaW4KOmFkbWluCg==",` in the received response.
188188

189189
```
190190
{

0 commit comments

Comments
 (0)