Copilot commented on code in PR #2109:
URL: https://github.com/apache/apisix-website/pull/2109#discussion_r3869182535
##########
blog/en/blog/2021/08/25/Using-the-Apache-APISIX-OpenID-Connect-Plugin-for-Centralized-Authentication.md:
##########
@@ -12,255 +12,173 @@ authors:
image_url: "https://avatars.githubusercontent.com/u/36651058?v=4";
keywords:
- API Gateway
- - APISIX
- Apache APISIX
- - Okta
- - Authorization
-description: Simplify API authentication by using the APISIX openid-connect
plugin to centralize identity verification at the gateway level.
+ - OpenID Connect
+ - OIDC Authentication
+ - Centralized Authentication
+description: "Learn how the APISIX openid-connect plugin validates tokens or
runs the OIDC authorization code flow before proxying requests upstream."
tags: [Authentication, Plugins, Ecosystem]
image: https://static.apiseven.com/2022/blog/0818/plugins/openid%20connect.png
---
-> Compared with the traditional authentication mode, the centralized
authentication mode has the following advantages: first, it simplifies the
application development process, reduces the development application workload
and maintenance costs, and avoids repeated development of authentication code
for each application; second, it improves business security, and the
centralized authentication mode can intercept unauthenticated requests at the
gateway level in time to protect back-end applications.
+The Apache APISIX `openid-connect` plugin can integrate gateway routes with an
OpenID Connect identity provider. It can validate bearer tokens for API clients
or run the authorization code flow for browser-based applications. This
centralizes supported authentication checks at the gateway while leaving
resource-level authorization in the application that owns the data.
<!--truncate-->
-## What is Apache APISIX
+## OpenID Connect in an API Gateway
-[Apache APISIX](https://apisix.apache.org/) is a dynamic, real-time,
high-performance API gateway that provides rich traffic management features
such as load balancing, dynamic upstream, canary release, service meltdown,
authentication, observability, and more. Apache APISIX's OpenID Connect plug-in
supports OpenID, which allows users to replace authentication from traditional
authentication mode to centralized authentication mode.
+[OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/) is
an identity layer built on OAuth 2.0. An identity provider publishes metadata,
authorization and token endpoints, and signing keys. A relying party validates
the resulting tokens and their claims.
-## What is authentication
+When APISIX protects a route, it acts as an OIDC relying party or
token-validating resource-server component, depending on the configured mode:
-Authentication refers to the verification of a user's identity through certain
means. The application identifies the user through authentication and obtains
detailed user metadata from the Identity Provider based on the user identity
ID, and uses it to determine whether the user has access to the specified
resources. Authentication modes are divided into two categories: **Traditional
Authentication Mode** and **Centralized Authentication Mode**.
+- **Authorization code flow:** a browser without an authenticated session is
redirected to the identity provider. APISIX processes the callback, establishes
a session, and then proxies the request.
+- **Bearer-only mode:** an API client sends an access token. APISIX validates
the token and rejects missing or invalid credentials instead of redirecting the
client.
-### Traditional authentication mode
+These modes serve different clients. Redirecting a machine client to a login
page is usually incorrect; accepting bearer tokens without the intended issuer,
audience, scope, and signature checks is unsafe.
-In traditional authentication mode, each application service needs to support
authentication separately, such as accessing the login interface when the user
is not logged in, and the interface returns a 301 jump page. The application
needs to develop the logic for maintaining the Session and the authentication
interaction with the identity provider. The flow of the traditional
authentication model is shown in the figure below: first, the user initiates a
request, then the gateway receives the request and forwards it to the
corresponding application service, and finally the application service
interfaces with the identity provider to complete the authentication.
+## What Centralized Authentication Does—and Does Not—Do
-
+Applying authentication at the gateway can:
-### Centralized authentication mode
+- give multiple routes a consistent integration with the same identity
provider;
+- reject unauthenticated traffic before it reaches an upstream service;
+- reduce repeated OIDC protocol handling in individual edge-facing
applications;
+- attach validated token information to a trusted upstream request when
configured.
-Unlike the traditional authentication model, the centralized authentication
model takes user authentication out of the application service. Take Apache
APISIX as an example, the centralized authentication process is shown in the
following diagram: first, the user initiates a request, and then the front
gateway is responsible for the user authentication process, interfacing with
the identity provider and sending the identity provider an authorization)
request to the identity provider. The identity provider returns user info.
After the gateway identifies the user, it forwards the user identity
information to the back-end application in the form of a request header.
+It does not automatically implement all authorization. A valid identity may
still be unable to read a specific account, change another user's resource, or
perform an administrative action. Services should enforce domain- and
resource-level permissions using trusted identity context.
-
+The upstream must also be unable to receive spoofed identity headers directly
from an untrusted client. Restrict upstream network access and configure the
trusted proxy boundary so that only APISIX sets or forwards the identity
headers the application consumes.
-Compared with the traditional authentication mode, the centralized
authentication mode has the following advantages.
+## Prerequisites
-1. simplify the application development process, reduce the development of
application workload and maintenance costs, to avoid the repeated development
of each application authentication code.
-2. improve business security, centralized authentication mode at the gateway
level to intercept unauthenticated requests in time to protect the back-end
applications.
+Before configuring the plugin:
-## What is OpenID
+1. Create an OIDC client at the identity provider.
+2. Record the issuer's discovery URL, normally ending in
`/.well-known/openid-configuration`.
+3. Register the exact redirect URI used by APISIX for an authorization code
flow.
+4. Decide which scopes and claims the API requires.
+5. Store the client secret and session secret in protected configuration; do
not commit production values to source control.
+6. Ensure APISIX can reach the discovery, authorization, token,
user-information, and key endpoints required by the selected flow.
-OpenID is a centralized authentication model, which is a decentralized
identity system. The benefit of using OpenID is that users only need to
register and log in with one OpenID identity provider's website and use one
account password information to access different applications. okta is a common
OpenID identity provider and the Apache APISIX OpenID Connect plugin supports
OpenID so users can use the plugin to to replace the traditional authentication
model with a centralized authentication model.
+Use HTTPS for the identity provider and public application route. The plugin's
TLS verification should remain enabled; the current default for `ssl_verify` is
`true`.
-### OpenID Authentication Process
+## Configure Authorization Code Flow
-The OpenID authentication process has the following 7 steps, as shown in the
figure below. 1.
-
-1. APISIX initiates an authentication request to Identity Provider. 2.
-2. The user logs in and authenticates on the Identity Provider. 3.
-3. The Identity Provider returns to APISIX with the Authorization Code. 4.
-4. APISIX requests the Identity Provider with the Code extracted from the
request parameters. 5.
-5. The Identity Provider sends an answer message to APISIX containing the ID
Token and Access Token. 6.
-6. APISIX sends the Access Token to the Identity Provider's User Endpoint to
obtain the user's identity.
-7. After authentication, the User Endpoint sends the User info to APISIX to
complete the authentication.
-
-
-
-## How to configure Okta authentication using the OpenID Connect plugin for
Apache APISIX
-
-Configuring Okta authentication using the Apache APISIX OpenID Connect plug-in
is a simple three-step process that allows you to switch from traditional to
centralized authentication mode. The following section describes the steps to
configure Okta authentication using the OpenID Connect plug-in for Apache
APISIX.
-
-### Prerequisites
-
-An Okta account already exists.
-
-### Step 1: Configure Okta
-
-1. Login to your Okta account and create an Okta application, select the OIDC
login mode and the Web Application application type.
- 
- 
2.
-2. Set the login and logout jump URLs.
-The "Sign-in redirect URIs" are the links that are allowed to be redirected
after successful login, and the "Sign-out redirect URIs" are the links that are
redirected after logging out. In this example, we set both the sign-in redirect
and sign-out redirect URLs to `http://127.0.0.1:9080/`.
- 
-3. Click "Save" to save the changes after finishing the settings.
- 
-Visit the General page of the application to get the following configuration,
which is required to configure Apache APISIX OpenID Connect.
-
-- Client ID: OAuth client ID, which is the ID of the application,
corresponding to `client_id` and `{YOUR_CLIENT_ID}` below.
-- Client secret: OAuth client secret, i.e. application key, corresponds to
`client_secret` and `{YOUR_CLIENT_SECRET}` below.
-- Okta domain: The domain name used by the application, corresponds to
`{YOUR_ISSUER}` in discovery below.
-
-
-
-### Installing Apache APISIX
-
-You can install Apache APISIX in a variety of ways such as through source
packages, Docker, Helm Chart, etc.
-
-#### Installing dependencies
-
-The Apache APISIX runtime environment requires dependencies on NGINX and etcd,
so before installing Apache APISIX, please install the corresponding
dependencies according to the operating system you are using. We have provided
steps for installing dependencies on CentOS7, Fedora 31 & 32, Ubuntu 16.04 &
18.04, Debian 9 & 10 and MacOS, please refer to [Installing
dependencies](https://apisix.apache.org/zh/docs/apisix/install) for details.
-dependencies/).
-
-When installing Apache APISIX via Docker or Helm Chart, the required NGINX and
etcd are already included, please refer to the respective documentation.
-
-#### Installation via RPM package (CentOS 7)
-
-This installation method is available for CentOS 7 operating system, please
run the following command to install Apache APISIX.
+The following Admin API request illustrates the relevant fields. Replace the
example identifiers and upstream with values from your environment.
```shell
-sudo yum install -y
https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
+curl "http://127.0.0.1:9180/apisix/admin/routes/oidc-browser"; \
+ -X PUT \
+ -H "X-API-KEY: $admin_key" \
+ -d '
+{
+ "uri": "/app/*",
+ "plugins": {
+ "openid-connect": {
+ "client_id": "<oidc-client-id>",
+ "client_secret": "<oidc-client-secret>",
+ "discovery": "https://id.example.com/.well-known/openid-configuration";,
Review Comment:
This wildcard route omits `redirect_uri`, so APISIX derives the callback
from each original request URI (for example, `/app/foo/.apisix/redirect`). That
cannot be covered by the single exact callback registration required above for
all `/app/*` pages. Configure one fixed callback subpath on the route and
register that exact external URL with the identity provider.
##########
blog/en/blog/2023/10/07/apisix-gitops-adc.md:
##########
@@ -13,312 +13,210 @@ keywords:
- Open Source
- API Gateway
- Apache APISIX
-description: APISIX strengthens its integration with modern development and
operational workflows by introducing the declarative configuration tool, ADC.
+ - GitOps
+ - ADC
+ - Declarative Configuration
+description: "Use ADC lint, diff, sync, dump, and OpenAPI conversion commands
in a reviewed GitOps workflow for Apache APISIX configuration."
tags: [Community]
image: https://static.apiseven.com/2022/10/19/634f6677742a1.png
---
-APISIX strengthens its integration with modern development and operational
workflows by introducing the declarative configuration tool, ADC.
+ADC is a command-line tool for managing API gateway configuration
declaratively. With Apache APISIX, teams can keep intended routes, services,
upstreams, and other supported resources in version control, review changes,
compare them with a target gateway, and synchronize an approved file.
+
<!--truncate-->
-With the widespread adoption of cloud-native and microservices, the API
gateway has emerged as a critical component for connecting and managing various
microservices. However, as the number of services continues to grow and changes
occur more frequently, the traditional imperative configuration has become
increasingly challenging to manage and maintain. GitOps, on the other hand, is
an operational model that leverages version control systems and automated
workflows. By supporting declarative configurations, GitOps provides a more
efficient, reliable, and traceable mode of operation.
+ADC helps automate a workflow, but installing a CLI does not make the workflow
GitOps by itself. A production design still needs review, protected
credentials, environment promotion, drift policy, verification, and rollback
procedures.
-To enhance developing efficiency and operational reliability, APISIX has
introduced a new tool that supports GitOps in a declarative manner. By
embracing the declarative nature of GitOps, APISIX strengthens its integration
with modern development and operational workflows. This integration enables
smoother collaboration between developers and operations teams, promoting
efficient and reliable management of the APISIX platform.
+## What Declarative Gateway Configuration Changes
-## Why Does APISIX Support GitOps Declarative Configuration
+An imperative workflow sends a sequence of create, update, and delete
requests. The history may show what commands ran, but it can be difficult to
see the intended final state.
-Although APISIX offers a stand-alone mode that allows configuration through
YAML files, it lacks seamless integration with related ecosystems such as CI/CD
tools like Jenkins and ArgoCD. While the APISIX Ingress Controller project
makes significant strides in this area, APISIX itself does not provide a
comprehensive set of declarative tools to support GitOps when used in
non-Kubernetes environments such as bare metal or virtual machines.
+A declarative workflow stores the desired state in a file and asks a tool to
compare or reconcile that state with a target system. This can improve:
-In traditional API gateway management, configurations and policies are
typically manipulated using imperative methods, requiring manual modifications
through command-line tools or management interfaces. This approach poses
several challenges:
+- **reviewability:** a pull request shows the intended configuration change;
+- **repeatability:** the same approved input can be evaluated in another
environment;
+- **traceability:** commits connect a configuration version to its reviewer
and deployment;
+- **drift detection:** a diff can reveal changes made outside the controlled
workflow;
+- **recovery:** an earlier reviewed configuration is available as a rollback
candidate.
-- **Cumbersome Configuration Management**: Manual modifications of
configurations are prone to errors, especially when dealing with large-scale
gateways.
+These properties depend on repository controls and deployment discipline. A
declarative file can still contain an unsafe route, and synchronizing an old
file can remove a valid production change.
-- **Poor Traceability**: Tracking the change history and version control of
configurations becomes difficult.
+## What ADC Provides
-- **Lack of Consistency**: Configuration discrepancies among multiple
environments result in inconsistencies between development, testing, and
production environments.
+The current ADC command set includes workflows for:
-The APISIX development team recognized several benefits of supporting GitOps
in a declarative manner to effectively address these challenges:
+- `adc lint` — check a declarative file before deployment;
+- `adc diff` — compare a local file with the configured gateway;
+- `adc sync` — synchronize the local desired state;
+- `adc dump` — export supported configuration from the gateway;
+- `adc convert openapi` — convert an OpenAPI document to declarative gateway
configuration;
+- `adc ping` — verify that ADC can connect to the configured server.
-1. **Improved Developer Efficiency**: By using GitOps with a declarative
configuration approach, developers can directly manage API gateway
configurations by modifying and committing configuration files in the code
repository. This method aligns with the development workflow that developers
are familiar with, reducing the learning curve and tool-switching costs, and
thus enhancing developer productivity.
+Use `adc --help` and the [official ADC
repository](https://github.com/api7/adc) for the exact flags supported by the
installed release. Pin and test a tool version in automation rather than
silently changing behavior when a new release becomes available.
Review Comment:
The workflow omits a critical compatibility warning: ADC v0.30 marks its
APISIX backend experimental and tests only through APISIX 3.17, while APISIX
3.18 is now the latest release. A 3.18 user could follow this
production-oriented guide and run a destructive reconciliation against an
untested backend. Link the backend compatibility/limitations page and require a
tested APISIX/ADC pairing before `sync`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
