Gin 框架:添加 HTTP 基本验证中间件

2021年11月22日 阅读数:4
这篇文章主要向大家介绍Gin 框架:添加 HTTP 基本验证中间件,主要内容包括基础应用、实用技巧、原理机制等方面,希望对大家有所帮助。

介绍

经过一个完整例子,在基于 Gin 框架的微服务中添加 HTTP 基本验证中间件。git

什么是 HTTP 基本验证中间件?github

验证中间件会对每个 API 请求进行拦截,并验证 Basic Auth 或者 X-API-Key 的验证。json

咱们将会使用 rk-boot 来启动 Gin 框架的微服务。api

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

安装

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

快速开始

1.建立 boot.yaml

boot.yaml 文件描述了 Gin 框架启动的原信息,rk-boot 经过读取 boot.yaml 来启动 Gin。app

为了验证,咱们启动了 commonService。commonService 里包含了一系列通用 API。 详情: CommonService框架

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

这一步,咱们启动 Basic Auth,用户名密码为 user:pass。ide

---
gin:
  - name: greeter                   # Required, name of gin entry
    port: 8080                      # Required, port of gin entry
    enabled: true                   # Required, enable gin 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"
)

// 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。

---
gin:
  - name: greeter                   # Required, name of gin entry
    port: 8080                      # Required, port of gin entry
    enabled: true                   # Required, enable gin 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 请求。

---
gin:
  - name: greeter                           # Required, name of gin entry
    port: 8080                              # Required, port of gin entry
    enabled: true                           # Required, enable gin 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/gin-gonic/gin"
	"github.com/rookie-ninja/rk-boot"
	"net/http"
)

// @title RK Swagger for Gin
// @version 1.0
// @description This is a greeter service with rk-boot.

// @securityDefinitions.basic BasicAuth

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

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

	// Register handler
	boot.GetGinEntry("greeter").Router.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 *gin.Context) {
	ctx.JSON(http.StatusOK, &GreeterResponse{
		Message: fmt.Sprintf("Hello %s!", ctx.Query("name")),
	})
}

// Response.
type GreeterResponse struct {
	Message string
}

用 swag 命令行从新生成 swagger config 文件并启动 main.go。