revet-auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Revet Auth Library

Revet Auth 库

OAuth 2.1 and OpenID Connect authorization server implementation for Kotlin/Quarkus applications.

Status: In development. APIs may change.

面向Kotlin/Quarkus应用的OAuth 2.1和OpenID Connect授权服务器实现。

**状态：**开发中，API可能会发生变更。

Dependency Coordinates

依赖坐标

Group ID:

com.revethq.auth

Version:

0.0.1-SNAPSHOT

Group ID：

com.revethq.auth

版本：

0.0.1-SNAPSHOT

Modules

模块

Artifact	Purpose
`core`	Domain models, services, DTOs
`web`	Quarkus REST endpoints, OAuth flows
`persistence`	Data access layer

构件	用途
`core`	领域模型、服务、DTO
`web`	Quarkus REST端点、OAuth流程
`persistence`	数据访问层

Gradle

kotlin

implementation("com.revethq.auth:core:0.0.1-SNAPSHOT")
implementation("com.revethq.auth:web:0.0.1-SNAPSHOT")

kotlin

implementation("com.revethq.auth:core:0.0.1-SNAPSHOT")
implementation("com.revethq.auth:web:0.0.1-SNAPSHOT")

OAuth 2.1 Flows

OAuth 2.1 授权流程

Authorization Code Flow (with PKCE)

授权码流程（带PKCE）

1. GET  /{authServerId}/authorization/
   ?client_id=...&redirect_uri=...&scope=...
   &code_challenge=...&code_challenge_method=S256

2. POST /{authServerId}/authorization/
   (user submits credentials)

3. Redirect to client with code

4. POST /{authServerId}/token/
   grant_type=authorization_code
   &code=...&redirect_uri=...&code_verifier=...

5. Returns access_token, id_token, refresh_token

1. GET  /{authServerId}/authorization/
   ?client_id=...&redirect_uri=...&scope=...
   &code_challenge=...&code_challenge_method=S256

2. POST /{authServerId}/authorization/
   (用户提交凭证)

3. 携带授权码重定向至客户端

4. POST /{authServerId}/token/
   grant_type=authorization_code
   &code=...&redirect_uri=...&code_verifier=...

5. 返回access_token、id_token、refresh_token

Client Credentials Flow

客户端凭证流程

POST /{authServerId}/token/
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=...
&client_secret=...
&scope=...

POST /{authServerId}/token/
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=...
&client_secret=...
&scope=...

Refresh Token Flow

刷新令牌流程

POST /{authServerId}/token/
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=...
&client_id=...

POST /{authServerId}/token/
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=...
&client_id=...

Core Domain Models

核心领域模型

AuthorizationServer

kotlin

data class AuthorizationServer(
    var id: UUID? = null,
    var name: String? = null,
    var serverUrl: URL? = null,
    var audience: String? = null,
    var clientCredentialsTokenExpiration: Long = 3600L,
    var authorizationCodeTokenExpiration: Long = 3600L,
    var metadata: Metadata? = null,
    var scopes: List<Scope>? = null,
    var createdOn: OffsetDateTime? = null,
    var updatedOn: OffsetDateTime? = null
)

kotlin

data class AuthorizationServer(
    var id: UUID? = null,
    var name: String? = null,
    var serverUrl: URL? = null,
    var audience: String? = null,
    var clientCredentialsTokenExpiration: Long = 3600L,
    var authorizationCodeTokenExpiration: Long = 3600L,
    var metadata: Metadata? = null,
    var scopes: List<Scope>? = null,
    var createdOn: OffsetDateTime? = null,
    var updatedOn: OffsetDateTime? = null
)

Client

kotlin

data class Client(
    var id: UUID? = null,
    var name: String? = null,
    var authorizationServerId: UUID? = null,
    var redirectUris: List<URI>? = null,
    var scopes: List<Scope>? = null,
    var metadata: Metadata? = null,
    var createdOn: OffsetDateTime? = null,
    var updatedOn: OffsetDateTime? = null
)

kotlin

data class Client(
    var id: UUID? = null,
    var name: String? = null,
    var authorizationServerId: UUID? = null,
    var redirectUris: List<URI>? = null,
    var scopes: List<Scope>? = null,
    var metadata: Metadata? = null,
    var createdOn: OffsetDateTime? = null,
    var updatedOn: OffsetDateTime? = null
)

Application (Machine-to-Machine)

Application（机器到机器）

kotlin

data class Application(
    var id: UUID? = null,
    var clientId: String? = null,
    var name: String? = null,
    var authorizationServerId: UUID? = null,
    var scopes: List<Scope>? = null,
    var metadata: Metadata? = null,
    var createdOn: OffsetDateTime? = null,
    var updatedOn: OffsetDateTime? = null
)

kotlin

data class Application(
    var id: UUID? = null,
    var clientId: String? = null,
    var name: String? = null,
    var authorizationServerId: UUID? = null,
    var scopes: List<Scope>? = null,
    var metadata: Metadata? = null,
    var createdOn: OffsetDateTime? = null,
    var updatedOn: OffsetDateTime? = null
)

Scope

kotlin

data class Scope(
    var id: UUID? = null,
    var authorizationServer: AuthorizationServer? = null,
    var name: String? = null,
    var metadata: Metadata? = null,
    var createdOn: OffsetDateTime? = null,
    var updatedOn: OffsetDateTime? = null
)

kotlin

data class Scope(
    var id: UUID? = null,
    var authorizationServer: AuthorizationServer? = null,
    var name: String? = null,
    var metadata: Metadata? = null,
    var createdOn: OffsetDateTime? = null,
    var updatedOn: OffsetDateTime? = null
)

OpenID Connect Endpoints

OpenID Connect 端点

Discovery

发现端点

GET /{authServerId}/.well-known/openid-configuration

Returns:

```
issuer
```
```
authorization_endpoint
```
```
token_endpoint
```
```
userinfo_endpoint
```
```
jwks_uri
```
```
scopes_supported
```
```
response_types_supported
```
```
grant_types_supported
```

GET /{authServerId}/.well-known/openid-configuration

```
issuer
```
```
authorization_endpoint
```
```
token_endpoint
```
```
userinfo_endpoint
```
```
jwks_uri
```
```
scopes_supported
```
```
response_types_supported
```
```
grant_types_supported
```

JWKS

GET /{authServerId}/jwks/

Returns JSON Web Key Set for token verification. Algorithm: RS256.

GET /{authServerId}/jwks/

返回用于令牌验证的JSON Web Key Set，算法为RS256。

UserInfo

GET /{authServerId}/userinfo/
Authorization: Bearer {access_token}

GET /{authServerId}/userinfo/
Authorization: Bearer {access_token}

Token Response

令牌响应

kotlin

data class AccessTokenResponse(
    val accessToken: String?,
    val tokenType: String?,      // "Bearer"
    val expiresIn: Int?,
    val refreshToken: String?,
    val scope: String?,
    val idToken: String?         // OIDC flows
)

kotlin

data class AccessTokenResponse(
    val accessToken: String?,
    val tokenType: String?,      // "Bearer"
    val expiresIn: Int?,
    val refreshToken: String?,
    val scope: String?,
    val idToken: String?         // OIDC flows
)

Service Interfaces

服务接口

AuthorizationServerService

kotlin

interface AuthorizationServerService {
    fun getAuthorizationServer(id: UUID): AuthorizationServer
    fun createAuthorizationServer(server: AuthorizationServer): AuthorizationServer
    fun getSigningKeysForAuthorizationServer(id: UUID): SigningKey
    fun validateJwtForAuthorizationServer(id: UUID, jwt: String): Map<String, Any>
    fun getJwksForAuthorizationServer(id: UUID): List<JWK>

    fun generateClientCredentialsAccessToken(
        authorizationServerId: UUID,
        applicationId: UUID,
        subject: String,
        scopes: List<Scope>,
        expiresInSeconds: Long
    ): AccessToken

    fun generateAuthorizationCodeFlowAccessToken(
        authorizationServerId: UUID,
        userId: UUID,
        subject: String,
        clientId: String,
        scopes: List<Scope>,
        expiresInSeconds: Long,
        nonce: String?
    ): AccessToken
}

kotlin

interface AuthorizationServerService {
    fun getAuthorizationServer(id: UUID): AuthorizationServer
    fun createAuthorizationServer(server: AuthorizationServer): AuthorizationServer
    fun getSigningKeysForAuthorizationServer(id: UUID): SigningKey
    fun validateJwtForAuthorizationServer(id: UUID, jwt: String): Map<String, Any>
    fun getJwksForAuthorizationServer(id: UUID): List<JWK>

    fun generateClientCredentialsAccessToken(
        authorizationServerId: UUID,
        applicationId: UUID,
        subject: String,
        scopes: List<Scope>,
        expiresInSeconds: Long
    ): AccessToken

    fun generateAuthorizationCodeFlowAccessToken(
        authorizationServerId: UUID,
        userId: UUID,
        subject: String,
        clientId: String,
        scopes: List<Scope>,
        expiresInSeconds: Long,
        nonce: String?
    ): AccessToken
}

UserService

kotlin

interface UserService {
    fun createUser(pair: Pair<User, Profile>): Pair<User, Profile>
    fun getUser(userId: UUID): Pair<User, Profile>
    fun getUser(username: String): Pair<User, Profile>
    fun setPassword(user: User, password: String)
    fun validatePassword(userId: UUID, password: String): Boolean
}

kotlin

interface UserService {
    fun createUser(pair: Pair<User, Profile>): Pair<User, Profile>
    fun getUser(userId: UUID): Pair<User, Profile>
    fun getUser(username: String): Pair<User, Profile>
    fun setPassword(user: User, password: String)
    fun validatePassword(userId: UUID, password: String): Boolean
}

ApplicationService

kotlin

interface ApplicationService {
    fun createApplication(app: Application, profile: Profile): Pair<Application, Profile>
    fun getApplication(id: UUID): Pair<Application, Profile>
    fun createApplicationSecret(secret: ApplicationSecret): ApplicationSecret
    fun isApplicationSecretValid(
        authorizationServerId: UUID,
        secretId: UUID,
        secret: String
    ): Boolean
}

kotlin

interface ApplicationService {
    fun createApplication(app: Application, profile: Profile): Pair<Application, Profile>
    fun getApplication(id: UUID): Pair<Application, Profile>
    fun createApplicationSecret(secret: ApplicationSecret): ApplicationSecret
    fun isApplicationSecretValid(
        authorizationServerId: UUID,
        secretId: UUID,
        secret: String
    ): Boolean
}

Identity Provider Federation

身份提供商联合

kotlin

data class IdentityProvider(
    var id: UUID? = null,
    var name: String? = null,
    var authorizationServerId: UUID? = null,
    var discoveryMethod: DiscoveryMethodEnum? = null,
    var discoveryEndpoint: String? = null,
    var wellKnownEndpoints: WellKnownEndpoints? = null,
    var clientId: String? = null,
    var clientSecret: String? = null,
    var usePkce: Boolean? = null,
    var metadata: Metadata? = null
)

enum class DiscoveryMethodEnum {
    MANUAL,
    WELL_KNOWN
}

kotlin

data class IdentityProvider(
    var id: UUID? = null,
    var name: String? = null,
    var authorizationServerId: UUID? = null,
    var discoveryMethod: DiscoveryMethodEnum? = null,
    var discoveryEndpoint: String? = null,
    var wellKnownEndpoints: WellKnownEndpoints? = null,
    var clientId: String? = null,
    var clientSecret: String? = null,
    var usePkce: Boolean? = null,
    var metadata: Metadata? = null
)

enum class DiscoveryMethodEnum {
    MANUAL,
    WELL_KNOWN
}

Management API Endpoints

管理API端点

POST   /applications                Create application
GET    /applications/{id}           Get application
DELETE /applications/{id}           Delete application

POST   /clients                     Create client
GET    /clients/{id}                Get client
DELETE /clients/{id}                Delete client

POST   /users                       Create user
GET    /users/{id}                  Get user
PUT    /users/{id}                  Update user
DELETE /users/{id}                  Delete user

POST   /scopes                      Create scope
GET    /scopes                      List scopes
DELETE /scopes/{id}                 Delete scope

POST   /applications                创建应用
GET    /applications/{id}           获取应用
DELETE /applications/{id}           删除应用

POST   /clients                     创建客户端
GET    /clients/{id}                获取客户端
DELETE /clients/{id}                删除客户端

POST   /users                       创建用户
GET    /users/{id}                  获取用户
PUT    /users/{id}                  更新用户
DELETE /users/{id}                  删除用户

POST   /scopes                      创建权限范围
GET    /scopes                      列出权限范围
DELETE /scopes/{id}                 删除权限范围

Constraints

约束条件

Token signing: RS256 algorithm
PKCE required for authorization code flow
Client secrets are hashed, never stored plaintext
Token expiration: configurable per authorization server

令牌签名：采用RS256算法
授权码流程要求使用PKCE
客户端密钥会被哈希处理，绝不会以明文存储
令牌过期时间：可按授权服务器进行配置