diff --git a/.gitignore b/.gitignore index 6c1eba55..a84ae031 100644 --- a/.gitignore +++ b/.gitignore @@ -15,7 +15,6 @@ *.war *.nar *.ear -*.zip *.tar.gz *.rar diff --git a/en/docs/assets/files/develop-api-proxy/policy/authenticator-mtls.zip b/en/docs/assets/files/develop-api-proxy/policy/authenticator-mtls.zip new file mode 100644 index 00000000..3905011d Binary files /dev/null and b/en/docs/assets/files/develop-api-proxy/policy/authenticator-mtls.zip differ diff --git a/en/docs/assets/img/develop-api-proxy/policy/mtls-auth-policy.png b/en/docs/assets/img/develop-api-proxy/policy/mtls-auth-policy.png new file mode 100644 index 00000000..fa0cb61c Binary files /dev/null and b/en/docs/assets/img/develop-api-proxy/policy/mtls-auth-policy.png differ diff --git a/en/docs/assets/img/monitoring-and-insights/logs/audit-logs.png b/en/docs/assets/img/monitoring-and-insights/logs/audit-logs.png new file mode 100644 index 00000000..867c5de0 Binary files /dev/null and b/en/docs/assets/img/monitoring-and-insights/logs/audit-logs.png differ diff --git a/en/docs/assets/img/monitoring-and-insights/logs/create-role-to-view-audit-logs.png b/en/docs/assets/img/monitoring-and-insights/logs/create-role-to-view-audit-logs.png new file mode 100644 index 00000000..c275784e Binary files /dev/null and b/en/docs/assets/img/monitoring-and-insights/logs/create-role-to-view-audit-logs.png differ diff --git a/en/docs/assets/img/monitoring-and-insights/logs/log-management-permission.png b/en/docs/assets/img/monitoring-and-insights/logs/log-management-permission.png new file mode 100644 index 00000000..f03fbf39 Binary files /dev/null and b/en/docs/assets/img/monitoring-and-insights/logs/log-management-permission.png differ diff --git a/en/docs/assets/img/monitoring-and-insights/logs/runtime-logs.png b/en/docs/assets/img/monitoring-and-insights/logs/runtime-logs.png new file mode 100644 index 00000000..2b9686b6 Binary files /dev/null and b/en/docs/assets/img/monitoring-and-insights/logs/runtime-logs.png differ diff --git a/en/docs/assets/img/monitoring-and-insights/logs/search-regex.png b/en/docs/assets/img/monitoring-and-insights/logs/search-regex.png new file mode 100644 index 00000000..c23f685c Binary files /dev/null and b/en/docs/assets/img/monitoring-and-insights/logs/search-regex.png differ diff --git a/en/docs/develop-api-proxy/policy/policies.md b/en/docs/develop-api-proxy/policy/policies.md index b1a452f3..9e7a31e5 100644 --- a/en/docs/develop-api-proxy/policy/policies.md +++ b/en/docs/develop-api-proxy/policy/policies.md @@ -27,6 +27,7 @@ Bijira supports a set of inbuilt mediation policies that can handle common API t - **Rewrite Resource Path**: Modifies the resource path of an HTTP request by replacing the original path with a new relative path. You can apply this policy multiple times, but only the last instance will take effect. The new path must be static, but you can use placeholders to configure different values for different environments. For example, `${myResourcePath}`. - **Log Message**: Logs the payload and headers of a request or response. Attaching this policy multiple times results in duplicate log entries. By default, headers and payloads are not logged. To log them, you can enable `Log Headers` and `Log Payload` parameters. To exclude specific headers when logging, you can use the `Excluded Headers` parameter, which takes a comma-separated list of header names. An error will occur if payload logging is enabled but the payload cannot be read. - **Permissions (Scopes)**: Defines fine-grained access control by assigning permissions (scopes) to API resources. Each resource can have one or more scopes, and only users or applications with the required scope in their access token can invoke the resource. +- **MTLS Authenticator**: Secures the communication between the client application and the gateway through mutual TLS (mTLS). This policy enforces that both the client and the gateway authenticate each other using certificates, ensuring encrypted and authenticated connections. It validates client certificates against configured certificate authorities. Follow the steps mentioned in [Secure Client-Gateway Communication with mTLS](../policy/secure-client-gateway-communication-with-mtls.md) to configure the MTLS Authenticator policy. These inbuilt mediation policies provide flexibility to manage API requests and responses, allowing for custom transformations and logic without requiring custom code. diff --git a/en/docs/develop-api-proxy/policy/secure-client-gateway-communication-with-mtls.md b/en/docs/develop-api-proxy/policy/secure-client-gateway-communication-with-mtls.md new file mode 100644 index 00000000..2bdb241e --- /dev/null +++ b/en/docs/develop-api-proxy/policy/secure-client-gateway-communication-with-mtls.md @@ -0,0 +1,92 @@ +# Secure Client-Gateway Communication with Mutual TLS + +Mutual TLS (mTLS) adds client-side certificate authentication to ensure only trusted clients can call an API. In WSO2 Bijira, you enable mTLS at the API proxy level by configuring the MTLS Authenticator mediation policy to validate client certificates or an intermediate CA chain during the TLS handshake. + +This guide walks through the end-to-end steps to configure mTLS for an API proxy. + +## Prerequisites + +1. Set up [ Ballerina 2201.5.5](https://ballerina.io/downloads/swan-lake-release-notes/swan-lake-2201.5.5). +2. Open the `~/.ballerina/settings.toml` file and ensure you have configured an access token to Ballerina Central. If you have not configured an access token, follow the steps given below to configure one. + 1. Generate a token via [https://central.ballerina.io/dashboard?tab=token](https://central.ballerina.io/dashboard?tab=token). + 2. Download the generated `Settings.toml` file and copy it to your local `~/.ballerina` directory. + +Alternatively, you can set the access token via the `BALLERINA_CENTRAL_ACCESS_TOKEN` environment variable. + +``` bash +export BALLERINA_CENTRAL_ACCESS_TOKEN= +``` + +## Configure mTLS Policy + +1. Mutual SSL will be configured through a mediation. Please click to download the [mediation app](../../assets/files/develop-api-proxy/policy/authenticator-mtls.zip). +2. Open the `Ballerina.toml` file in your preferred text editor and modify the `org` parameter to match your current Bijira organization. +3. Build the mediation app and publish it to the Ballerina central using the following commands. + + !!!note + If setting up in dev environment use `export BALLERINA_DEV_CENTRAL=true` before following commands. + + ```bash + bal pack + bal push + ``` + +## Generate a Self-signed Certificate + +1. If you don't have a CA-signed certificate, use the following command to generate a self-signed certificate. + + ```bash + openssl req -x509 -newkey rsa:2048 -keyout mykey.pem -out mycert.pem -days 365 -nodes + ``` + +2. Open the certificate via the preferred text editor and get the content in PEM format. Convert the content in to URL encoding and copy the content to the clipboard for future use. + +## Apply mTLS to API Proxy + +1. Sign in to the [Bijira Console](https://console.bijira.dev/). +2. In the Proxy Listing pane, click on the API proxy for which you want to enable MTLS. For instructions on how to create an API proxy component, see [Create an API Proxy](../../create-api-proxy/my-apis/http/import-api-contract.md). +3. Go to Develop, Policy page and click "Resource level policies". + + !!! note + If you don't need OAuth2 to be enabled, remove the "OAuth2" mediation policy. + +4. Under the policies, select "MTLS Authenticator". +5. Paste the URL-encoded certificate content you copied to the clipboard at the step 2 of [Generate a Self-signed Certificate](#generate-a-self-signed-certificate) section above and save. + + !!! note + If you need to support multiple client certificates, you can use an intermediate CA certificate and add here. Once that is done, all certificates signed by the intermediate certificate will be allowed to access the resource. + + ![MTLS authenticator policy](../../assets/img/develop-api-proxy/policy/mtls-auth-policy.png) + +6. Deploy the API to development and then to the production environment. + +## Invoke the API Proxy + +!!! note + If you haven’t removed OAuth2 policy, you will have to subscribe to the API and get access token. + +You can use curl for this. Get the URL for the API from the dev portal and invoke API. + +```bash +curl --request GET \ + --url \ + --header 'Accept: application/json' \ + --cert //mycert.pem \ + --key //mykey.pem +``` + +For a failed scenario, you will get the following error. + +```json +{ + "error_message":"Invalid Credentials", + "code":"900901", + "error_description":"Make sure you have provided the correct security credentials." +} +``` + +## Configure a Custom Domain + +To configure a custom domain for an API Proxy, follow the steps mentioned in [Configure a Custom Domain for Your Organization](../../../administer/settings/configure-a-custom-domain-for-your-organization/). + +Once the above step is completed, contact the Bijira team via [bijira-help@wso2.com](mailto:bijira-help@wso2.com) to enable mTLS for the given custom domain. \ No newline at end of file diff --git a/en/docs/monitoring-and-insights/logs/audit-logs.md b/en/docs/monitoring-and-insights/logs/audit-logs.md new file mode 100644 index 00000000..81ca84d0 --- /dev/null +++ b/en/docs/monitoring-and-insights/logs/audit-logs.md @@ -0,0 +1,78 @@ +# Audit logs + +Audit logs, also called audit trails, enhance security, ensure compliance, provide operational insights, and help manage risks. + +In Bijira, an audit log records organization-level user-specific operations performed via the Bijira Console. It also captures the timestamp and the outcome of the action. + +As of now, Bijira captures the following user-specific operations as audit logs: + +- Project creation, update, and deletion. +- API Proxy creation, update, and deletion. +- API Proxy promotion initiation. +- API Proxy version creation. + + + + + +- Organization user management. +- On-premises key management. +- Project-level configuration management. + +In Bijira, organization administrators are allowed to view audit logs by default. If other members need to access organization-specific audit logs, the administrator can create a role with the relevant permission and assign it to members. For step-by-step instructions on how to create and assign a role with relevant permission, see [Manage audit log access](#manage-audit-log-access). + +To view audit logs, follow these steps: + +1. Sign in to [Bijira](https://console.bijira.dev/). +2. In the Bijira Console, go to the top navigation menu and click **Organization**. + + !!! tip + As of now, you can only view organization-level audit logs. + +3. In the left navigation menu, click **Admin** and then click **Audit Logs**. This displays audit logs for the past 30 days by default. + + To view audit logs based on a specific time range and other requirements, you can apply the necessary filter criteria. + + ![Audit logs](../../assets/img/monitoring-and-insights/logs/audit-logs.png) + +## Audit log retention + +Bijira retains audit logs for one year and archives them for an additional year. Therefore, the total retention period for audit logs is two years. + +## Manage audit log access + +Follow the steps given below to create a role with audit log access permission and assign it to organization members who need access to audit logs: + +!!! info "Note" + You must be the organization administrator to perform this action. + +### Step 1: Create a role with audit log access permission + +1. In the Bijira Console, go to the top navigation menu and click **Organization**. +2. In the left navigation menu, click **Admin** and then click **Settings**. +3. On the **Access Control** tab, click **Roles** and then click **+ Create Role**. +4. Enter a name and description for the role. + + ![Create role](../../assets/img/monitoring-and-insights/logs/create-role-to-view-audit-logs.png){: style="width:700px"} + +5. Click **Next**. +6. In the **Create Role** dialog, select **LOG-MANAGEMENT** under **Permissions**. + + ![Select log management permission](../../assets/img/monitoring-and-insights/logs/log-management-permission.png){: style="width:700px"} + +7. Click **Create**. + + +### Step 2: Assign the created role to an organization member + +1. On the **Access Control** tab, click **Groups**. This lists the groups of the organization with their respective details. +2. Select the group that you want to assign the role to and click Edit button. +3. Click the **Roles** tab, and then click **+ Add Roles** to add a new role to the group. Then add the role you created in [Step 1](#step-1-create-a-role-with-audit-log-access-permission) and click **Add**. + + !!! tip + If you want to invite one or more members and assign them the audit log viewer role, follow the steps given below: + + 1. Click **+ Invite Member** and then click to expand the **Roles** list. + 2. Select the role you created in [Step 1](#step-1-create-a-role-with-audit-log-access-permission). + 3. In the **Emails** field, enter the email addresses of members you want to invite and grant permission to access audit logs. + 4. Click **Invite**. This sends an invitation email to each email address so that the members can accept and obtain access to view audit logs. diff --git a/en/docs/monitoring-and-insights/logs/overview.md b/en/docs/monitoring-and-insights/logs/overview.md new file mode 100644 index 00000000..e534044f --- /dev/null +++ b/en/docs/monitoring-and-insights/logs/overview.md @@ -0,0 +1,13 @@ +# Logs + +The unified log view in Bijira allows you to view runtime and audit logs to gain API Proxy and user insights while ensuring data privacy. Bijira provides real-time insights through live logs and allows you to view historical logs for insights into the past. + +You also have the flexibility to define a required time range to view relevant log entries, where an intuitive scrolling capability facilitates easy viewing of appropriate logs within the selected time frame. The log view also provides advanced filtering capabilities that allow you to efficiently navigate through appropriate logs to expedite troubleshooting in distributed environments. + +!!! info "Note" + All personally identifiable information (PII) gets resolved at the frontend service level, with only relevant UUIDs stored in logs. + +Below are the types of logs you can access. + +- **[Runtime logs](../runtime-logs)**: These logs capture the real-time execution details of your API proxies, helping you monitor performance and identify issues as they occur. +- **[Audit logs](../audit-logs)**: These logs provide a record of user actions and system changes, ensuring accountability and traceability for compliance and security purposes. diff --git a/en/docs/monitoring-and-insights/logs/runtime-logs.md b/en/docs/monitoring-and-insights/logs/runtime-logs.md new file mode 100644 index 00000000..bbab6b45 --- /dev/null +++ b/en/docs/monitoring-and-insights/logs/runtime-logs.md @@ -0,0 +1,83 @@ +# Runtime logs + +Bijira runtime logs provide insights into both project and API Proxy-level logs, covering application and gateway logs. These logs streamline the debugging process by centralizing diverse log sources. + +In Bijira, any organization member can view runtime logs via the runtime logs page. Bijira allows you to apply filters based on parameters such as log level (error, warn, info, debug), log type (application, gateway, system), and environment (development, staging, production) to simplify the debugging process. + +To access runtime logs, follow the steps below: + +1. Sign in to [Bijira](https://console.bijira.dev/). +2. In the left navigation menu, click **Observability** and then click **Logs**. This displays runtime logs for the past 30 days by default. + + To view logs based on a specific time range and other requirements, you can apply the necessary filter criteria. + + ![Runtime logs](../../assets/img/monitoring-and-insights/logs/runtime-logs.png) + +## Searching through runtime logs + +The runtime logs interface provides powerful search capabilities to help you quickly locate specific log entries. + +### Text search +Type any text into the search box to locate log entries that contain the exact phrase. Searches are case-sensitive and will match partial strings within the log messages of Application, Gateway, and System logs. + +### Advanced search with regex +Use Lucene-compatible regex patterns to perform advanced search queries. Refer to the [OpenSearch regex syntax](https://docs.opensearch.org/latest/query-dsl/regex-syntax/#standard-regex-operators) for more details. + +Pattern examples: + + - `error.*timeout` : Find logs containing the phrase "error" followed by "timeout" + - `.*(GET|POST).*&.*500.*` : Find logs of GET or POST request methods with HTTP 500 status code + - `\"userId\":\"12345\"` : Find logs containing the userId "12345" + +![Search and filter interface](../../assets/img/monitoring-and-insights/logs/search-regex.png) + +## Understand runtime logs + +When you view API Proxy-level logs on the **Logs** page, you will see application/mediation, gateway and system logs. + +### Application logs + +Each application log entry displays the following details: + + - `timestamp`: The time when the request is received by the component. + - `level`: Indicates the severity of the log message. Possible values are **Debug**, **Info**, **Warn**, and **Error**. + - `componentVersion`: The version of the invoked component. + - `componentVersionId`: The identifier of the invoked component’s version. + - `envName`: The environment of the inbound request. For example, Development, Production, etc. + +### Gateway logs + +Each gateway log entry displays the following details: + + - `timestamp`: The time when the request is received by the gateway component. + - `logLine`: Contains the following details about the request, including inbound and outbound information from the gateway perspective. + - `Method`: The HTTP method of the request. + - `RequestPath`: The path of the inbound request. + - `ServicePath`: The path of the outbound request. + - `UserAgent`: The user-agent header of the request. + - `CorrelationID`: The request identifier of the inbound request. This is useful to track a request. + - `ServiceHost`: The host IP of the backend. + - `Duration`: The time taken for the gateway to serve the request.   + - `gatewayCode`: Indicates the state of the request from the gateway perspective. Possible values are as follows: + - `BACKEND_RESPONSE`: Indicates successful processing of the request by the gateway with a response to the client from the backend application. + - `CORS_RESPONSE`: Denotes a CORS (Cross Origin Resource Sharing) request. + - `AUTH_FAILURE`: Indicates a request failure at the gateway due to authentication or authorization issues, such as an invalid token. + - `NO_HEALTHY_BACKEND`: Indicates a request failure at the gateway due to a non-existent backend. + - `RATE_LIMITED`: Indicates a request failure at the gateway due to surpassing the rate limit enforced within the component. + - `RESOURCE_NOT_FOUND`: Indicates a request failure at the gateway due to the absence of a matching API resource for the inbound request. This can be caused by a mismatch in the HTTP method, path, or host. + - `BACKEND_TIMEOUT`: Indicates a request timeout when calling the backend application from the gateway. + - `GATEWAY_ERROR`: Indicates a request failure due to an erroneous behavior in the gateway. + - `statusCode`: The HTTP status code returned to the client. + - `componentVersion`: The version of the invoked component. + - `envName`: The environment of the inbound request. For example, Development, Production, etc. + +### System logs + +Each system log entry displays the following details: + + - `timestamp`: The time of the system event. + - `componentVersion`: The version of the component. + - `componentVersionId`: The identifier of the component version. + - `reason`: The system event reason. + - `logEntry`: System event details. + - `kind`: The kind of the k8s object related to the event. diff --git a/en/mkdocs.yml b/en/mkdocs.yml index 6fe8cf6b..ce631db8 100644 --- a/en/mkdocs.yml +++ b/en/mkdocs.yml @@ -138,6 +138,7 @@ nav: - Overview: develop-api-proxy/policy/overview.md - Policies: develop-api-proxy/policy/policies.md - Attach and Manage Policies: develop-api-proxy/policy/attach-and-manage-policies.md + - Secure Client-Gateway Communication with Mutual TLS: develop-api-proxy/policy/secure-client-gateway-communication-with-mtls.md # - Apply Advanced Settings on Mediation Policies: develop-api-proxy/policy/apply-advanced-settings-on-mediation-policies.md - Documents: develop-api-proxy/documents.md - Lifecycle: develop-api-proxy/lifecycle-management.md @@ -156,6 +157,10 @@ nav: - API Governance Overview: governance/overview.md - Govern API Proxy: governance/govern-api-proxy.md - Monitor and Insights: + - Logs: + - Overview: monitoring-and-insights/logs/overview.md + - Runtime Logs: monitoring-and-insights/logs/runtime-logs.md + - Audit Logs: monitoring-and-insights/logs/audit-logs.md - Integrate Bijira with Moesif: monitoring-and-insights/integrate-bijira-with-moesif.md - Administer: - Create API Subscription Plans: administer/settings/create-api-subscription-plans.md