社区首页 >专栏 >Echo 框架：添加 HTTP 基本验证中间件

Echo 框架：添加 HTTP 基本验证中间件

原创

尹东勋

修改于 2021-12-12 16:30:49

1.1K0

文章被收录于专栏：开源 & 技术分享开源 & 技术分享

介绍

通过一个完整例子，在基于 Echo 框架的微服务中添加 HTTP 基本验证中间件。

什么是 HTTP 基本验证中间件？
验证中间件会对每一个 API 请求进行拦截，并验证 Basic Auth 或者 X-API-Key 的验证。

我们将会使用 rk-boot 来启动 Echo 框架的微服务。

请访问如下地址获取完整教程：https://rkdocs.netlify.app/cn

安装

go get github.com/rookie-ninja/rk-boot
go get github.com/rookie-ninja/rk-echo

快速开始

1.创建 boot.yaml

boot.yaml 文件描述了 Echo 框架启动的原信息，rk-boot 通过读取 boot.yaml 来启动 Echo。

为了验证，我们启动了 commonService。commonService 里包含了一系列通用 API。

详情: CommonService

同时启动了 sw 来提供 Swagger UI。

这一步，我们启动 Basic Auth，用户名密码为 user:pass。

---
echo:
  - name: greeter                   # Required, name of echo entry
    port: 8080                      # Required, port of echo entry
    enabled: true                   # Required, enable echo entry
    commonService:
      enabled: true                 # Optional, enable common service
    sw:
      enabled: true                 # Optional, enabled Swagger UI
    interceptors:
      auth:
        enabled: true               # Optional, enable auth middleware
        basic: ["user:pass"]        # Optional, basic auth credentials

2.创建 main.go

CommonService 的 Swagger Config 文件里默认添加了关于 Basic Auth & API Key 的选项。

如果想要在自己的 API 中添加 Swagger 验证选项，请参考 swag security 官网，我们会在其他的例子中介绍。

package main

import (
	"context"
	"github.com/rookie-ninja/rk-boot"
	_ "github.com/rookie-ninja/rk-echo/boot"
)

// Application entrance.
func main() {
	// Create a new boot instance.
	boot := rkboot.NewBoot()

	// Bootstrap
	boot.Bootstrap(context.Background())

	// Wait for shutdown sig
	boot.WaitForShutdownSig(context.Background())
}

3.文件夹结构

$ tree
.
├── boot.yaml
├── go.mod
├── go.sum
└── main.go

0 directories, 4 files

4.启动 main.go

$ go run main.go

5.验证

在不提供 Basic Auth 的情况下，我们得到了 401 错误码。

$ curl -X GET localhost:8080/rk/v1/healthy
# This is RK style error code if unauthorized
{
    "error":{
        "code":401,
        "status":"Unauthorized",
        "message":"Missing authorization, provide one of bellow auth header:[Basic Auth]",
        "details":[]
    }
}

用 Swagger UI 试一下。访问 http://localhost:8080/sw，直接发送请求，我们依然会得到 401 错误。

提供 Basic Auth，出于安全考虑，Request Header 里的 Auth 需要用 Base64 进行编码。我们对 user:pass 字符串进行了 Base64 编码。

$ curl localhost:8080/rk/v1/healthy -H "Authorization: Basic dXNlcjpwYXNz"
{
    "healthy":true
}

在 Swagger UI 中，点击【锁】按钮，添加 Basic Auth。

使用 X-API-Key 授权模式

1.修改 boot.yaml

这一步，我们启动 X-API-Key，key 的值为 token。

---
echo:
  - name: greeter                   # Required, name of echo entry
    port: 8080                      # Required, port of echo entry
    enabled: true                   # Required, enable echo entry
    commonService:
      enabled: true                 # Optional, enable common service
    sw:
      enabled: true                 # Optional, enabled Swagger UI
    interceptors:
      auth:
        enabled: true               # Optional, enable auth middleware
        apiKey: [ "token" ]         # Optional, enable X-API-Key auth

2.启动 main.go

$ go run main.go

3.验证

同样的情况，在不提供 X-API-Key 的情况下，我们得到了 401 错误码。

$ curl  -X GET localhost:8080/rk/v1/healthy
# This is RK style error code if unauthorized
{
    "error":{
        "code":401,
        "status":"Unauthorized",
        "message":"Missing authorization, provide one of bellow auth header:[X-API-Key]",
        "details":[]
    }
}

$ curl localhost:8080/rk/v1/healthy -H "X-API-Key: token"
{
    "healthy":true
}

忽略请求路径

我们可以添加一系列 API 请求路径，让中间件忽略验证这些 API 请求。

---
echo:
  - name: greeter                           # Required, name of echo entry
    port: 8080                              # Required, port of echo entry
    enabled: true                           # Required, enable echo entry
    commonService:
      enabled: true                         # Optional, enable common service
    sw:
      enabled: true                         # Optional, enabled Swagger UI
    interceptors:
      auth:
        enabled: true                       # Optional, enable auth middleware
        basic: ["user:pass"]                # Optional, basic auth credentials
        ignorePrefix: ["/rk/v1/healthy"]    # Optional, ignoring path with prefix

添加 Swag Security Annotation

这次我们看一下如何在 swag 里添加安全相关的 annotation。

在 main() 函数添加如下 annotation，定义 security。

// @securityDefinitions.basic BasicAuth
// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name X-API-Key

在 Handler 函数添加如下 annotation。

// @Security ApiKeyAuth
// @Security BasicAuth

例子如下：

// Copyright (c) 2021 rookie-ninja
//
// Use of this source code is governed by an Apache-style
// license that can be found in the LICENSE file.
package main

import (
	"context"
	"fmt"
	"github.com/labstack/echo/v4"
	"github.com/rookie-ninja/rk-boot"
	"github.com/rookie-ninja/rk-echo/boot"
	"net/http"
)

// @title RK Swagger for Echo
// @version 1.0
// @description This is a greeter service with rk-boot.
// @securityDefinitions.basic BasicAuth

// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name X-API-Key
func main() {
	// Create a new boot instance.
	boot := rkboot.NewBoot()

	// Register handler
	boot.GetEntry("greeter").(*rkecho.EchoEntry).Echo.GET("/v1/greeter", Greeter)

	// Bootstrap
	boot.Bootstrap(context.Background())

	// Wait for shutdown sig
	boot.WaitForShutdownSig(context.Background())
}

// @Summary Greeter service
// @Id 1
// @version 1.0
// @produce application/json
// @Param name query string true "Input name"
// @Security ApiKeyAuth
// @Security BasicAuth
// @Success 200 {object} GreeterResponse
// @Router /v1/greeter [get]
func Greeter(ctx echo.Context) error {
	return ctx.JSON(http.StatusOK, &GreeterResponse{
		Message: fmt.Sprintf("Hello %s!", ctx.QueryParam("name")),
	})
}

// Response.
type GreeterResponse struct {
	Message string
}