# Configure Basic Authentication Basic authentication is a common method for securing web services. It uses the standard HTTP `Authorization` header with a `Basic` scheme, followed by a base64-encoded string of `username:password`. API7 Gateway provides the [`basic-auth`](https://docs.api7.ai/hub/basic-auth.md) plugin to handle this authentication flow and validate credentials against its consumer credential database. Use this guide for the standard setup workflow. For the full plugin field reference and advanced behaviors, see [`basic-auth`](https://docs.api7.ai/hub/basic-auth.md). ## Prerequisites[​](#prerequisites "Direct link to Prerequisites") * An API7 Enterprise instance is running. * A Gateway Group is created and a Gateway instance is running. * A [token from the Dashboard](https://docs.api7.ai/api7-gateway/reference/obtain-dashboard-token.md). ## Configure Basic Authentication[​](#configure-basic-authentication "Direct link to Configure Basic Authentication") Setting up basic authentication involves three steps: 1. Create a service with a valid upstream. 2. Create a route that enables `basic-auth`. 3. Create a consumer and attach a basic auth credential. ### Step 1: Create a Service with an Upstream[​](#step-1-create-a-service-with-an-upstream "Direct link to Step 1: Create a Service with an Upstream") * Admin API * ADC ``` curl -k "https://localhost:7443/apisix/admin/services/basic-auth-httpbin-service?gateway_group_id={gateway_group_id}" -X PUT \ -H "X-API-KEY: ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "name": "basic-auth-httpbin-service", "upstream": { "type": "roundrobin", "scheme": "http", "nodes": [ { "host": "httpbin.org", "port": 80, "weight": 100 } ] } }' ``` adc.yaml ``` services: - name: basic-auth-httpbin-service upstream: name: default scheme: http nodes: - host: httpbin.org port: 80 weight: 100 routes: - name: basic-auth-route uris: - /anything/basic-auth methods: - GET plugins: basic-auth: hide_credentials: true labels: docs-example: basic-auth-httpbin-service consumers: - username: basic-auth-consumer credentials: - name: basic-auth-consumer-cred type: basic-auth config: username: alice password: secret-password labels: docs-example: basic-auth-httpbin-service ``` Preview the changes owned by this example and confirm that the diff contains no unintended updates or deletions: ``` adc diff -f adc.yaml \ --include-resource-type service \ --include-resource-type consumer \ --label-selector docs-example=basic-auth-httpbin-service ``` Synchronize the reviewed configuration: ``` adc sync -f adc.yaml \ --include-resource-type service \ --include-resource-type consumer \ --label-selector docs-example=basic-auth-httpbin-service ``` ### Step 2: Create a Route and Enable `basic-auth`[​](#step-2-create-a-route-and-enable-basic-auth "Direct link to step-2-create-a-route-and-enable-basic-auth") * Admin API * ADC ``` curl -k "https://localhost:7443/apisix/admin/routes/basic-auth-route?gateway_group_id={gateway_group_id}" -X PUT \ -H "X-API-KEY: ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "name": "basic-auth-route", "paths": ["/anything/basic-auth"], "methods": ["GET"], "service_id": "basic-auth-httpbin-service", "plugins": { "basic-auth": { "hide_credentials": true } } }' ``` The route is already included in the previous `adc.yaml` example. ### Step 3: Create a Consumer and Credential[​](#step-3-create-a-consumer-and-credential "Direct link to Step 3: Create a Consumer and Credential") * Admin API * ADC ``` # 1. Create the consumer curl -k "https://localhost:7443/apisix/admin/consumers/basic-auth-consumer?gateway_group_id={gateway_group_id}" -X PUT \ -H "X-API-KEY: ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "username": "basic-auth-consumer" }' # 2. Create the basic-auth credential curl -k "https://localhost:7443/apisix/admin/consumers/basic-auth-consumer/credentials/basic-auth-consumer-cred?gateway_group_id={gateway_group_id}" -X PUT \ -H "X-API-KEY: ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "name": "basic-auth-consumer-cred", "plugins": { "basic-auth": { "username": "alice", "password": "secret-password" } } }' ``` The consumer and credential are already included in the previous `adc.yaml` example. ## Validate the Configuration[​](#validate-the-configuration "Direct link to Validate the Configuration") Send a request without the `Authorization` header. The gateway should reject it with `401 Unauthorized`: ``` curl -i "http://127.0.0.1:9080/anything/basic-auth" ``` Then send the request with the correct credentials: ``` curl -i "http://127.0.0.1:9080/anything/basic-auth" \ -u alice:secret-password ``` You should receive `200 OK`, and the upstream response should include headers similar to the following: ``` { "headers": { "X-Consumer-Username": "basic-auth-consumer", "X-Credential-Identifier": "basic-auth-consumer-cred" } } ``` If the authenticated request still returns `401`, or the route returns `404`, immediately after you apply the configuration, wait a few seconds for the latest configuration to reach the gateway and retry. ## Next Steps[​](#next-steps "Direct link to Next Steps") * [Configure Key Authentication](https://docs.api7.ai/api7-gateway/how-to-guides/api-security/key-auth.md) - secure your APIs using unique API keys. * [Configure JWT Authentication](https://docs.api7.ai/api7-gateway/how-to-guides/api-security/jwt-auth.md) - use JSON Web Tokens for stateless authentication. * [Learn about Consumers and Credentials](https://docs.api7.ai/api7-gateway/key-concepts/consumers-and-credentials.md) - understand how API7 Gateway manages API identities.