0
# Plugin Configuration
1

2
Core authentication plugin installation and configuration with support for multiple authentication providers, customizable unauthorized response detection, and circuit breaker functionality.
3

4
## Capabilities
5

6
### Auth Plugin Installation
7

8
Install the Auth plugin on an HTTP client with configuration block.
9

10
```kotlin { .api }
11
/**
12
 * Install Auth plugin with configuration
13
 * @param block Configuration block for setting up authentication providers
14
 */
15
fun HttpClientConfig<*>.Auth(block: AuthConfig.() -> Unit)
16

17
/**
18
 * Core authentication plugin for Ktor client
19
 */
20
val Auth: ClientPlugin<AuthConfig>
21
```
22

23
**Usage Example:**
24

25
```kotlin
26
import io.ktor.client.*
27
import io.ktor.client.plugins.auth.*
28

29
val client = HttpClient {
30
    Auth {
31
        // Add authentication providers here
32
    }
33
}
34
```
35

36
### Authentication Configuration
37

38
Configuration class for the Auth plugin providing provider management and response detection customization.
39

40
```kotlin { .api }
41
/**
42
 * Configuration used by Auth plugin
43
 */
44
class AuthConfig {
45
    /**
46
     * AuthProvider list to use
47
     */
48
    val providers: MutableList<AuthProvider>
49
    
50
    /**
51
     * Sets a custom function to control whether a response is unauthorized and should trigger a refresh / re-auth
52
     * By default checks against HTTP status 401
53
     * @param block Function that determines if a response should trigger re-authentication
54
     */
55
    fun reAuthorizeOnResponse(block: suspend (HttpResponse) -> Boolean)
56
}
57
```
58

59
**Usage Example:**
60

61
```kotlin
62
Auth {
63
    // Configure custom unauthorized response detection
64
    reAuthorizeOnResponse { response ->
65
        response.status == HttpStatusCode.Unauthorized || 
66
        response.status == HttpStatusCode.Forbidden
67
    }
68
    
69
    // Add providers to the providers list
70
    basic { /* basic auth config */ }
71
    bearer { /* bearer auth config */ }
72
}
73
```
74

75
### Circuit Breaker
76

77
Attribute key for marking requests that should skip authentication and token refresh procedures to prevent infinite loops.
78

79
```kotlin { .api }
80
/**
81
 * Shows that request should skip auth and refresh token procedure
82
 */
83
val AuthCircuitBreaker: AttributeKey<Unit>
84
```
85

86
**Usage Example:**
87

88
```kotlin
89
// Mark a request to skip authentication
90
val request = HttpRequestBuilder().apply {
91
    attributes.put(AuthCircuitBreaker, Unit)
92
}
93
```
94

95
### Client Authentication Provider Access
96

97
Extension properties and functions for accessing configured authentication providers from an HTTP client.
98

99
```kotlin { .api }
100
/**
101
 * Get list of authentication providers from HTTP client
102
 */
103
val HttpClient.authProviders: List<AuthProvider>
104

105
/**
106
 * Get specific authentication provider by type from HTTP client
107
 * @return Provider instance or null if not found
108
 */
109
inline fun <reified T : AuthProvider> HttpClient.authProvider(): T?
110
```
111

112
**Usage Examples:**
113

114
```kotlin
115
import io.ktor.client.*
116
import io.ktor.client.plugins.auth.*
117
import io.ktor.client.plugins.auth.providers.*
118

119
// Get all providers
120
val allProviders = client.authProviders
121

122
// Get specific provider type
123
val basicProvider = client.authProvider<BasicAuthProvider>()
124
val bearerProvider = client.authProvider<BearerAuthProvider>()
125

126
// Clear tokens if needed
127
basicProvider?.clearToken()
128
bearerProvider?.clearToken()
129
```
130

131
## Core Authentication Provider Interface
132

133
```kotlin { .api }
134
/**
135
 * Base interface for authentication providers
136
 */
137
interface AuthProvider {
138
    /**
139
     * Determines whether credentials should be sent without waiting for HttpStatusCode.Unauthorized
140
     * @param request The HTTP request being processed
141
     * @return true if credentials should be sent proactively
142
     */
143
    fun sendWithoutRequest(request: HttpRequestBuilder): Boolean
144
    
145
    /**
146
     * Checks if the current provider is applicable to a request based on authentication header
147
     * @param auth Authentication header from WWW-Authenticate response
148
     * @return true if this provider can handle the authentication challenge
149
     */
150
    fun isApplicable(auth: HttpAuthHeader): Boolean
151
    
152
    /**
153
     * Adds authentication method headers and credentials to the request
154
     * @param request HTTP request builder to modify
155
     * @param authHeader Value of WWW-Authenticate header from failed response, if exists
156
     */
157
    suspend fun addRequestHeaders(request: HttpRequestBuilder, authHeader: HttpAuthHeader? = null)
158
    
159
    /**
160
     * Refreshes authentication token if required
161
     * @param response HTTP response that triggered token refresh
162
     * @return true if the token was successfully refreshed
163
     */
164
    suspend fun refreshToken(response: HttpResponse): Boolean
165
}
166
```