pavitt/mock-oauth2-server

mock-oauth2-server

镜像概述和主要用途

mock-oauth2-server 是一个可脚本化/可定制的Web服务器，用于测试使用OAuth2/OpenID Connect的HTTP客户端，或依赖运行中的OAuth2服务器的应用（例如需要来自已知发行者的签名JWT的API）。该服务器还提供令牌验证所需的端点（JWKS端点）和身份提供者元数据发现端点（提供服务器元数据的"well-known"端点）。

该服务器使用Kotlin编写，基于OkHttp MockWebServer作为底层服务器库，可在Java和Kotlin的单元/集成测试中使用，或作为独立服务器在任何语言环境中运行（例如通过docker-compose）。

注意：尽管服务器旨在符合支持的OAuth2/OpenID Connect规范，但仅应用于测试场景，不得用于生产环境。

动机

开发此工具的目的是提供一种设置，使应用开发者在运行测试时无需禁用应用中的安全功能！如果您在OAuth2和令牌等方面遇到问题并考虑在测试时禁用"安全"功能，请提交issue或PR，帮助开发者和安全需求和谐共存。

核心功能和特性

• 多发行者/多租户支持：服务器可代表任意数量的不同身份提供者/令牌发行者（具有不同的令牌发行者名称），无需任何额外设置！
• 支持的OAuth2/OpenID Connect授权流程：
  • OpenID Connect授权码流程
  • OAuth2客户端凭证授权
  • OAuth2 JWT承载授权（委托流程）
  • OAuth2令牌交换授权
  • OAuth2刷新令牌授权
• 发行的JWT令牌可验证：通过OpenID Connect发现/OAuth2授权服务器元数据的标准机制
• 单元/集成测试支持：
  • 为每个测试启动和停止服务器
  • 无需令牌定制时的合理默认值和最小设置
  • 需要定制令牌声明时可预排队预期令牌
  • 预排队预期响应
  • 验证对服务器的预期请求
  • 通过暴露底层OkHttp MockWebServer实现定制
• 独立运行支持：可在IDE中作为应用启动、在应用内运行或作为Docker镜像运行（提供镜像）
• OAuth2客户端调试器：支持触发OIDC授权码流程并在调试器应用中接收回调，查看服务器的令牌响应（用于独立运行模式）

安装

Gradle Kotlin DSL

最新版本 ![Maven Central]([***]

kotlin
testImplementation("no.nav.security:mock-oauth2-server:$mockOAuth2ServerVersion")

Maven

最新版本 ![Maven Central]([***]

xml
<dependency>
  <groupId>no.nav.security</groupId>
  <artifactId>mock-oauth2-server</artifactId>
  <version>${mock-oauth2-server.version}</version>
  <scope>test</scope>
</dependency>

Docker

最新版本

⚠️ 从0.3.3版本开始，Docker镜像发布到GitHub Container Registry，可***从 ghcr.io/navikt/mock-oauth2-server:<version> 拉取。请相应更新镜像拉取命令。

bash
docker pull ghcr.io/navikt/mock-oauth2-server:$MOCK_OAUTH2_SERVER_VERSION

使用方法

Well-Known配置

mock-oauth2-server会根据请求URL提供不同的配置，具体来说，请求URL中的第一个路径（或上下文根）元素将指定issuerId。

请求 http://localhost:8080/default/.well-known/openid-configuration 将生成issuerId为default的配置：

json
{
   "issuer":"http://localhost:8080/default",
   "authorization_endpoint":"http://localhost:8080/default/authorize",
   "token_endpoint":"http://localhost:8080/default/token",
   "jwks_uri":"http://localhost:8080/default/jwks",
   "response_types_supported":[
      "query",
      "fragment",
      "form_post"
   ],
   "subject_types_supported":[
      "public"
   ],
   "id_token_signing_alg_values_supported":[
      "RS256"
   ]
}

JWT中的实际发行者值为 iss: "http://localhost:8080/default"。

要使用另一个发行者（id为anotherissuer），只需请求 http://localhost:8080/anotherissuer/.well-known/openid-configuration，配置将相应更改。

单元测试

测试设置

• 在随机端口启动服务器
• 获取服务器元数据/配置的URL
• 设置应用使用OAuth2服务器元数据并执行测试
• 关闭服务器

kotlin
val server = MockOAuth2Server()
server.start()
// 可自定义 - 如有多个发行者，应唯一标识
val issuerId = "default"
// 授权服务器元数据的发现URL
val wellKnownUrl = server.wellKnownUrl(issuerId).toString()
// ......
// 使用wellKnownUrl的元数据设置应用并执行测试
// ......
server.shutdown()

测试需要用户登录的OpenID Connect授权码流程应用

• 按上述方式设置测试
• 让测试HTTP客户端跟随重定向
• 回调（redirect_uri）端点应按要求接收回调请求，并能够从令牌端点获取令牌。

如需特定用户登录，可使用OAuth2TokenCallback接口提供自定义实现或在DefaultOAuth2TokenCallback中设置值：

kotlin
@Test
fun loginWithIdTokenForSubjectFoo() {
    server.enqueueCallback(
        DefaultOAuth2TokenCallback(
            issuerId = issuerId,
            subject = "foo"
        )
    )
  // 调用应用并断言用户foo已登录
}

如需在生成的id_token中包含特定声明（如acr或自定义声明），也可使用OAuth2TokenCallback：

kotlin
@Test
fun loginWithIdTokenForAcrClaimEqualsLevel4() {
    server.enqueueCallback(
        DefaultOAuth2TokenCallback(
            issuerId = issuerId,
            claims = mapOf("acr" to "Level4")
        )
    )
  // 调用应用并断言id_token中存在acr=Level4
}

测试需要access_token的API（例如签名JWT）

kotlin
val token: SignedJWT = oAuth2Server.issueToken(issuerId, "someclientid", DefaultOAuth2TokenCallback())
// 使用HTTP客户端调用API并附加序列化令牌
val request = // ....
request.addHeader("Authorization", "Bearer ${token.serialize()}")

更多示例

可在src/test目录的examples中查看Kotlin示例。

API

服务器URLs

可通过调用 fun *Url(issuerId: String): HttpUrl 函数/方法从服务器获取包含正确端口和issuerId等信息的URL：

kotlin
val server = MockOAuth2Server()
server.start()
val wellKnownUrl = server.wellKnownUrl("yourissuer")
// 生成URL：http://localhost:<随机端口>/yourissuer/.well-known/openid-configuration

独立服务器

独立服务器默认使用端口8080，可通过调用StandaloneMockOAuth2Server.kt（Kotlin）或StandaloneMockOAuth2ServerKt（Java）中的main()方法启动。

在Windows上，建议在Docker中运行服务器并指定主机为localhost，例如：docker run -p 8080:8080 -h localhost $IMAGE_NAME

配置

独立服务器支持通过环境变量进行以下配置：

JSON_CONFIG

JSON_CONFIG允许使用JSON配置OAuth2Config类的内容。

示例：

json
{
    "interactiveLogin": true,
    "httpServer": "NettyWrapper",
    "tokenCallbacks": [
        {
            "issuerId": "issuer1",
            "tokenExpiry": 120,
            "requestMappings": [
                {
                    "requestParam": "scope",
                    "match": "scope1",
                    "claims": {
                        "sub": "subByScope",
                        "aud": [
                            "audByScope"
                        ]
                    }
                }
            ]
        },
        {
            "issuerId": "issuer2",
            "requestMappings": [
                {
                    "requestParam": "someparam",
                    "match": "somevalue",
                    "claims": {
                        "sub": "subBySomeParam",
                        "aud": [
                            "audBySomeParam"
                        ]
                    }
                }
            ]
        }
    ]
}

从上述JSON示例中：

向http://localhost:8080/issuer1/token发送带有参数scope等于scope1的令牌请求将匹配第一个tokencallback：

json
{
    "issuerId": "issuer1",
    "tokenExpiry": 120,
    "requestMappings": [
        {
            "requestParam": "scope",
            "match": "scope1",
            "claims": {
                "sub": "subByScope",
                "aud": [
                    "audByScope"
                ]
            }
        }
    ]
}

并返回包含以下声明的令牌响应：

json
{
  "sub": "subByScope",
  "aud": "audByScope",
  "nbf": 1616416942,
  "iss": "http://localhost:54905/issuer1",
  "exp": 1616417062,
  "iat": 1616416942,
  "jti": "28697333-6f25-4b1f-b2c2-409ce010933a"
}

Docker

构建到本地Docker守护进程：

gradle
./gradlew jibDockerBuild

运行容器：

bash
docker run -p 8080:8080 $IMAGE_NAME

Docker-Compose

为使容器间网络和浏览器交互顺畅，必须在hosts文件中添加主机条目127.0.0.1 host.docker.internal，并在docker-compose.yaml文件的mock-oauth2-server服务中设置hostname：

yaml
version: '3.7'
services:
  your_app:
    build: .
    ports:
      - 8080:8080
  mock-oauth2-server:
    image: ghcr.io/navikt/mock-oauth2-server:$MOCK_OAUTH2_SERVER_VERSION
    ports:
      - 8080:8080
    hostname: host.docker.internal

调试器

调试器是一个实现authorization_code流程的OAuth2客户端，带有调试UI（例如请求参数）。在浏览器中访问http://localhost:8080/default/debugger即可使用。

联系

该项目目前由组织https://github.com/navikt%E7%BB%B4%E6%8A%A4%E3%80%82

如需要提出问题或疑问，请在此创建issue并添加适当标签。

对于https://github.com/navikt%E7%BB%84%E7%BB%87%E5%86%85%E7%9A%84%E8%81%94%E7%B3%BB%E8%AF%B7%E6%B1%82%EF%BC%8C%E5%8F%AF%E4%BD%BF%E7%94%A8Slack%E9%A2%91%E9%81%93#pig_sikkerhet%E3%80%82

如需直接联系个人，请查看贡献者列表。

贡献

开始前，请fork仓库并检出新分支。然后使用Gradle包装器构建库：

shell
./gradlew build

更多信息见CONTRIBUTING.md

许可

本库采用MIT许可证