0
# Shared Token Cache Authentication
1

2
Legacy authentication mechanism using MSAL shared token cache, formerly used for Visual Studio integration. This credential provides compatibility with legacy token caches.
3

4
## Capabilities
5

6
### Shared Token Cache Credential
7

8
Provides token credentials from the MSAL shared token cache.
9

10
```java { .api }
11
/**
12
 * Shared token cache credential for legacy token cache integration
13
 */
14
class SharedTokenCacheCredential implements TokenCredential {
15
    Mono<AccessToken> getToken(TokenRequestContext request);
16
    // Note: Does not support synchronous getTokenSync method
17
}
18

19
class SharedTokenCacheCredentialBuilder extends AadCredentialBuilderBase<SharedTokenCacheCredentialBuilder> {
20
    SharedTokenCacheCredentialBuilder username(String username);
21
    SharedTokenCacheCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
22
    SharedTokenCacheCredentialBuilder authenticationRecord(AuthenticationRecord authenticationRecord);
23
    SharedTokenCacheCredential build();
24
}
25
```
26

27
**Usage Examples:**
28

29
```java
30
import com.azure.identity.SharedTokenCacheCredential;
31
import com.azure.identity.SharedTokenCacheCredentialBuilder;
32

33
// Basic usage with username
34
TokenCredential credential = new SharedTokenCacheCredentialBuilder()
35
    .clientId("your-client-id")
36
    .tenantId("your-tenant-id") 
37
    .username("user@example.com")
38
    .build();
39

40
// With authentication record for specific account
41
AuthenticationRecord record = // ... previously obtained record
42
TokenCredential recordCredential = new SharedTokenCacheCredentialBuilder()
43
    .clientId("your-client-id")
44
    .tenantId("your-tenant-id")
45
    .authenticationRecord(record)
46
    .build();
47

48
// Use with Azure SDK clients
49
SecretClient client = new SecretClientBuilder()
50
    .vaultUrl("https://myvault.vault.azure.net/")
51
    .credential(credential)
52
    .buildClient();
53
```
54

55
## Legacy Integration
56

57
This credential was primarily designed for:
58
- **Visual Studio integration** - Legacy authentication for Visual Studio
59
- **MSAL token cache compatibility** - Reading existing MSAL token caches
60
- **Migration scenarios** - Transitioning from older authentication methods
61

62
## Token Cache Configuration
63

64
```java
65
// With custom token cache settings
66
TokenCredential credential = new SharedTokenCacheCredentialBuilder()
67
    .clientId("your-client-id")
68
    .tenantId("your-tenant-id")
69
    .username("user@example.com")
70
    .tokenCachePersistenceOptions(new TokenCachePersistenceOptions()
71
        .setName("MyLegacyTokenCache")
72
        .setUnencryptedStorageAllowed(false))
73
    .build();
74
```
75

76
## Account Selection
77

78
### Using Username
79
```java
80
// Specify exact username to select account
81
TokenCredential credential = new SharedTokenCacheCredentialBuilder()
82
    .username("john.doe@contoso.com")
83
    .clientId("client-id")
84
    .build();
85
```
86

87
### Using Authentication Record
88
```java
89
// Use authentication record for precise account selection
90
AuthenticationRecord record = AuthenticationRecord.deserialize(inputStream);
91
TokenCredential credential = new SharedTokenCacheCredentialBuilder()
92
    .authenticationRecord(record)
93
    .clientId("client-id")
94
    .build();
95
```
96

97
## Migration Path
98

99
**From SharedTokenCacheCredential to modern credentials:**
100

101
```java
102
// Legacy approach (not recommended)
103
TokenCredential legacyCredential = new SharedTokenCacheCredentialBuilder()
104
    .username("user@example.com")
105
    .clientId("client-id")
106
    .build();
107

108
// Modern recommended approach
109
TokenCredential modernCredential = new DefaultAzureCredentialBuilder()
110
    .build();
111

112
// Or for development scenarios
113
TokenCredential devCredential = new AzureCliCredentialBuilder()
114
    .build();
115
```
116

117
## Limitations
118

119
- **Read-only**: Cannot create new token cache entries
120
- **Platform dependent**: Token cache format varies by platform
121
- **Legacy format**: May not support newest authentication features
122
- **No sync support**: Only supports asynchronous token acquisition
123

124
## Troubleshooting
125

126
**Common Issues:**
127
- **"No cached token found"**: Ensure token cache contains valid entries for the specified user
128
- **Username mismatch**: Verify username exactly matches cached account
129
- **Cache format errors**: Token cache may be corrupted or from incompatible version
130
- **Permission errors**: Check file system permissions for token cache access
131

132
**Diagnostics:**
133
```java
134
// Enable detailed logging
135
TokenCredential credential = new SharedTokenCacheCredentialBuilder()
136
    .username("user@example.com")
137
    .clientId("client-id")
138
    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
139
    .build();
140
```
141

142
## Alternative Recommendations
143

144
Instead of `SharedTokenCacheCredential`, consider:
145

146
- **`DefaultAzureCredential`** - Comprehensive authentication chain
147
- **`InteractiveBrowserCredential`** - Modern interactive authentication
148
- **`AzureCliCredential`** - Development environment authentication
149
- **`VisualStudioCodeCredential`** - VS Code integration (if applicable)
150

151
## Exception Handling
152

153
Throws `CredentialUnavailableException` when:
154
- Token cache is empty or doesn't contain entries for specified user
155
- Username doesn't match any cached accounts
156
- Token cache is corrupted or inaccessible
157
- Authentication record references non-existent account