0
# Bearer Authentication
1

2
OAuth2/JWT token authentication with automatic token refresh and management. Ideal for API authentication with access tokens and optional refresh tokens.
3

4
## Capabilities
5

6
### Bearer Provider Installation
7

8
Install Bearer authentication with token loading and refresh configuration.
9

10
```kotlin { .api }
11
/**
12
 * Install Bearer authentication provider
13
 * @param block Configuration block for BearerAuthConfig
14
 */
15
fun AuthConfig.bearer(block: BearerAuthConfig.() -> Unit)
16
```
17

18
**Usage Example:**
19

20
```kotlin
21
install(Auth) {
22
    bearer {
23
        loadTokens {
24
            // Load from secure storage
25
            val tokens = tokenStorage.getTokens()
26
            BearerTokens(tokens.accessToken, tokens.refreshToken)
27
        }
28
        
29
        refreshTokens { params ->
30
            // Call refresh endpoint
31
            val response = authClient.post("/oauth/refresh") {
32
                setBody(RefreshRequest(params.oldTokens?.refreshToken))
33
            }
34
            val newTokens = response.body<TokenResponse>()
35
            BearerTokens(newTokens.accessToken, newTokens.refreshToken)
36
        }
37
        
38
        sendWithoutRequest { request ->
39
            // Send tokens proactively for API calls
40
            request.url.host == "api.example.com"
41
        }
42
        
43
        realm = "api" // Optional realm restriction
44
    }
45
}
46
```
47

48
### BearerTokens Class
49

50
Container for Bearer authentication tokens.
51

52
```kotlin { .api }
53
/**
54
 * Container for bearer tokens
55
 * @param accessToken The access token for API requests
56
 * @param refreshToken Optional refresh token for obtaining new access tokens
57
 */
58
class BearerTokens(
59
    val accessToken: String,
60
    val refreshToken: String?
61
)
62
```
63

64
### BearerAuthConfig Class
65

66
Configuration for Bearer authentication provider.
67

68
```kotlin { .api }
69
/**
70
 * Configuration for Bearer authentication
71
 */
72
class BearerAuthConfig {
73
    /**
74
     * Optional realm restriction for this provider
75
     */
76
    var realm: String?
77
    
78
    /**
79
     * Configure callback to load cached tokens from storage
80
     * Note: Using the same client instance here will result in deadlock
81
     * @param block Function that returns cached tokens or null
82
     */
83
    fun loadTokens(block: suspend () -> BearerTokens?)
84
    
85
    /**
86
     * Configure callback to refresh tokens when 401 is received
87
     * @param block Function that receives refresh parameters and returns new tokens
88
     */
89
    fun refreshTokens(block: suspend RefreshTokensParams.() -> BearerTokens?)
90
    
91
    /**
92
     * Configure when to send credentials without waiting for 401
93
     * @param block Function that returns true if credentials should be sent preemptively
94
     */
95
    fun sendWithoutRequest(block: (HttpRequestBuilder) -> Boolean)
96
}
97
```
98

99
### RefreshTokensParams Class
100

101
Parameters provided to the token refresh callback.
102

103
```kotlin { .api }
104
/**
105
 * Parameters for token refresh callback
106
 */
107
class RefreshTokensParams(
108
    val client: HttpClient,
109
    val response: HttpResponse,
110
    val oldTokens: BearerTokens?
111
) {
112
    /**
113
     * Mark refresh request to prevent authentication loops
114
     */
115
    fun HttpRequestBuilder.markAsRefreshTokenRequest()
116
}
117
```
118

119
**Usage Example:**
120

121
```kotlin
122
refreshTokens { params ->
123
    // Use the provided client to make refresh request
124
    val refreshRequest = HttpRequestBuilder().apply {
125
        markAsRefreshTokenRequest() // Prevent auth loop
126
        method = HttpMethod.Post
127
        url("https://auth.example.com/refresh")
128
        setBody(params.oldTokens?.refreshToken)
129
    }
130
    
131
    val response = params.client.request(refreshRequest)
132
    if (response.status.isSuccess()) {
133
        val tokenData = response.body<TokenResponse>()
134
        BearerTokens(tokenData.accessToken, tokenData.refreshToken)
135
    } else {
136
        null // Refresh failed
137
    }
138
}
139
```
140

141
### BearerAuthProvider Class
142

143
Implementation of Bearer authentication provider.
144

145
```kotlin { .api }
146
/**
147
 * Bearer authentication provider implementation
148
 */
149
class BearerAuthProvider(
150
    private val refreshTokens: suspend RefreshTokensParams.() -> BearerTokens?,
151
    loadTokens: suspend () -> BearerTokens?,
152
    private val sendWithoutRequestCallback: (HttpRequestBuilder) -> Boolean = { true },
153
    private val realm: String?
154
) : AuthProvider {
155
    /**
156
     * Clear cached tokens from memory
157
     * Call when tokens are updated externally or during logout
158
     */
159
    fun clearToken()
160
}
161
```
162

163
## Token Management
164

165
The Bearer provider includes sophisticated token management:
166

167
### Automatic Header Addition
168

169
When tokens are available, the provider automatically adds the Authorization header:
170

171
```
172
Authorization: Bearer <access_token>
173
```
174

175
### Token Caching
176

177
- Tokens are cached in memory after first load
178
- `loadTokens` is called only when cache is empty
179
- `clearToken()` forces reload on next request
180

181
### Refresh Logic
182

183
1. When 401 response is received, `refreshTokens` callback is invoked
184
2. If refresh succeeds, new tokens are cached and request retried
185
3. If refresh fails, original 401 response is returned
186
4. Refresh requests are automatically marked with circuit breaker
187

188
### Realm Handling
189

190
If a realm is specified in configuration:
191
- Provider only applies to WWW-Authenticate headers with matching realm
192
- Multiple Bearer providers can coexist with different realms
193

194
## Error Scenarios
195

196
- **Load Tokens Failure**: Request proceeds without authentication if `loadTokens` returns null
197
- **Refresh Failure**: Original 401 response returned if `refreshTokens` returns null  
198
- **Network Errors**: Refresh failures due to network issues return original response
199
- **Invalid Tokens**: Malformed or expired tokens trigger refresh attempt
200

201
## Security Considerations
202

203
- Store tokens securely using platform-specific secure storage
204
- Use HTTPS for all token-related requests
205
- Implement proper token expiration handling
206
- Clear tokens on logout or app termination
207
- Avoid logging token values in production