@@ -68,6 +68,7 @@ key value NoSQL database that uses RocksDB as storage engine and is compatible w
6868
6969- Redis commands except QUIT and SYNC.
7070- Automatic connection pooling.
71+ - [ StreamingCredentialsProvider (e.g. entra id, oauth)] ( #1-streaming-credentials-provider-highest-priority ) (experimental)
7172- [ Pub/Sub] ( https://redis.uptrace.dev/guide/go-redis-pubsub.html ) .
7273- [ Pipelines and transactions] ( https://redis.uptrace.dev/guide/go-redis-pipelines.html ) .
7374- [ Scripting] ( https://redis.uptrace.dev/guide/lua-scripting.html ) .
@@ -136,17 +137,121 @@ func ExampleClient() {
136137}
137138```
138139
139- The above can be modified to specify the version of the RESP protocol by adding the ` protocol `
140- option to the ` Options ` struct:
140+ ### Authentication
141+
142+ The Redis client supports multiple ways to provide authentication credentials, with a clear priority order. Here are the available options:
143+
144+ #### 1. Streaming Credentials Provider (Highest Priority) - Experimental feature
145+
146+ The streaming credentials provider allows for dynamic credential updates during the connection lifetime. This is particularly useful for managed identity services and token-based authentication.
141147
142148``` go
143- rdb := redis.NewClient (&redis.Options {
144- Addr : " localhost:6379"
145- Password : " " // no password set
146- DB : 0 , // use default DB
147- Protocol : 3 , // specify 2 for RESP 2 or 3 for RESP 3
148- })
149+ type StreamingCredentialsProvider interface {
150+ Subscribe (listener CredentialsListener ) (Credentials, UnsubscribeFunc, error )
151+ }
152+
153+ type CredentialsListener interface {
154+ OnNext (credentials Credentials ) // Called when credentials are updated
155+ OnError (err error ) // Called when an error occurs
156+ }
157+
158+ type Credentials interface {
159+ BasicAuth () (username string , password string )
160+ RawCredentials () string
161+ }
162+ ```
163+
164+ Example usage:
165+ ``` go
166+ rdb := redis.NewClient (&redis.Options {
167+ Addr : " localhost:6379"
168+ StreamingCredentialsProvider : &MyCredentialsProvider{},
169+ })
170+ ```
171+
172+ ** Note:** The streaming credentials provider can be used with [ go-redis-entraid] ( https://github.com/redis/go-redis-entraid ) to enable Entra ID (formerly Azure AD) authentication. This allows for seamless integration with Azure's managed identity services and token-based authentication.
173+
174+ Example with Entra ID:
175+ ``` go
176+ import (
177+ " github.com/redis/go-redis/v9"
178+ " github.com/redis/go-redis-entraid"
179+ )
180+
181+ // Create an Entra ID credentials provider
182+ provider := entraid.NewDefaultAzureIdentityProvider ()
183+
184+ // Configure Redis client with Entra ID authentication
185+ rdb := redis.NewClient (&redis.Options {
186+ Addr : " your-redis-server.redis.cache.windows.net:6380"
187+ StreamingCredentialsProvider : provider,
188+ TLSConfig : &tls.Config {
189+ MinVersion: tls.VersionTLS12 ,
190+ },
191+ })
192+ ```
149193
194+ #### 2. Context-based Credentials Provider
195+
196+ The context-based provider allows credentials to be determined at the time of each operation, using the context.
197+
198+ ``` go
199+ rdb := redis.NewClient (&redis.Options {
200+ Addr : " localhost:6379"
201+ CredentialsProviderContext : func (ctx context.Context ) (string , string , error ) {
202+ // Return username, password, and any error
203+ return " user" " pass" nil
204+ },
205+ })
206+ ```
207+
208+ #### 3. Regular Credentials Provider
209+
210+ A simple function-based provider that returns static credentials.
211+
212+ ``` go
213+ rdb := redis.NewClient (&redis.Options {
214+ Addr : " localhost:6379"
215+ CredentialsProvider : func () (string , string ) {
216+ // Return username and password
217+ return " user" " pass"
218+ },
219+ })
220+ ```
221+
222+ #### 4. Username/Password Fields (Lowest Priority)
223+
224+ The most basic way to provide credentials is through the ` Username ` and ` Password ` fields in the options.
225+
226+ ``` go
227+ rdb := redis.NewClient (&redis.Options {
228+ Addr : " localhost:6379"
229+ Username : " user"
230+ Password : " pass"
231+ })
232+ ```
233+
234+ #### Priority Order
235+
236+ The client will use credentials in the following priority order:
237+ 1 . Streaming Credentials Provider (if set)
238+ 2 . Context-based Credentials Provider (if set)
239+ 3 . Regular Credentials Provider (if set)
240+ 4 . Username/Password fields (if set)
241+
242+ If none of these are set, the client will attempt to connect without authentication.
243+
244+ ### Protocol Version
245+
246+ The client supports both RESP2 and RESP3 protocols. You can specify the protocol version in the options:
247+
248+ ``` go
249+ rdb := redis.NewClient (&redis.Options {
250+ Addr : " localhost:6379"
251+ Password : " " // no password set
252+ DB : 0 , // use default DB
253+ Protocol : 3 , // specify 2 for RESP 2 or 3 for RESP 3
254+ })
150255```
151256
152257### Connecting via a redis url
0 commit comments