Document macOS persistent caching errors (#23571)
This commit is contained in:
Charles Lowell
GitHub
Родитель
10d6b405b6
Коммит
e588254261
|
|
@ -22,13 +22,13 @@ Some credential types support opt-in persistent token caching (see [the below ta
|
|||
|
||||
Persistent caches are encrypted at rest using a mechanism that depends on the operating system:
|
||||
|
||||
| Operating system | Encryption facility |
|
||||
|------------------|---------------------------------------|
|
||||
| Linux | kernel key retention service (keyctl) |
|
||||
| macOS | Keychain |
|
||||
| Windows | Data Protection API (DPAPI) |
|
||||
| Operating system | Encryption facility |
|
||||
| ---------------- | ---------------------------------------------- |
|
||||
| Linux | kernel key retention service (keyctl) |
|
||||
| macOS | Keychain (requires cgo and native build tools) |
|
||||
| Windows | Data Protection API (DPAPI) |
|
||||
|
||||
Persistent caching requires encryption. When the required encryption facility is unuseable, or the application is running on an unsupported OS, the persistent cache constructor returns an error. This doesn't mean that authentication is impossible, only that credentials can't persist authentication data and the application will need to reauthenticate the next time it runs. See the [package documentation][example] for example code showing how to configure persistent caching and access cached data.
|
||||
Persistent caching requires encryption. When the required encryption facility is unuseable, or the application is running on an unsupported OS, the persistent cache constructor returns an error. This doesn't mean that authentication is impossible, only that credentials can't persist authentication data and the application will need to reauthenticate the next time it runs. See the package documentation for examples showing how to configure persistent caching and access cached data for [users][user_example] and [service principals][sp_example].
|
||||
|
||||
### Credentials supporting token caching
|
||||
|
||||
|
|
@ -37,7 +37,7 @@ The following table indicates the state of in-memory and persistent caching in e
|
|||
**Note:** in-memory caching is enabled by default for every type supporting it. Persistent token caching must be enabled explicitly. See the [package documentation][user_example] for an example showing how to do this for credential types authenticating users. For types that authenticate service principals, set the `Cache` field on the constructor's options as shown in [this example][sp_example].
|
||||
|
||||
| Credential | In-memory token caching | Persistent token caching |
|
||||
|--------------------------------|---------------------------------------------------------------------|--------------------------|
|
||||
| ------------------------------ | ------------------------------------------------------------------- | ------------------------ |
|
||||
| `AzureCLICredential` | Not Supported | Not Supported |
|
||||
| `AzureDeveloperCLICredential` | Not Supported | Not Supported |
|
||||
| `AzurePipelinesCredential` | Supported | Supported |
|
||||
|
|
|
|||
|
|
@ -8,6 +8,7 @@ This troubleshooting guide covers failure investigation techniques, common error
|
|||
- [Permission issues](#permission-issues)
|
||||
- [Find relevant information in errors](#find-relevant-information-in-errors)
|
||||
- [Enable and configure logging](#enable-and-configure-logging)
|
||||
- [Troubleshoot persistent token caching issues](#troubleshoot-persistent-token-caching-issues)
|
||||
- [Troubleshoot AzureCLICredential authentication issues](#troubleshoot-azureclicredential-authentication-issues)
|
||||
- [Troubleshoot AzureDeveloperCLICredential authentication issues](#troubleshoot-azuredeveloperclicredential-authentication-issues)
|
||||
- [Troubleshoot AzurePipelinesCredential authentication issues](#troubleshoot-azurepipelinescredential-authentication-issues)
|
||||
|
|
@ -236,6 +237,29 @@ azd auth token --output json --scope https://management.core.windows.net/.defaul
|
|||
| No service connection found with identifier |The `serviceConnectionID` argument to `NewAzurePipelinesCredential` is incorrect| Verify the service connection ID. This parameter refers to the `resourceId` of the Azure Service Connection. It can also be found in the query string of the service connection's configuration in Azure DevOps. [Azure Pipelines documentation](https://learn.microsoft.com/azure/devops/pipelines/library/service-endpoints?view=azure-devops&tabs=yaml) has more information about service connections.|
|
||||
|401 (Unauthorized) response from OIDC endpoint|The `systemAccessToken` argument to `NewAzurePipelinesCredential` is incorrect|Check pipeline configuration. This value comes from the predefined variable `System.AccessToken` [as described in Azure Pipelines documentation](https://learn.microsoft.com/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken).|
|
||||
|
||||
## Troubleshoot persistent token caching issues
|
||||
|
||||
### macOS
|
||||
|
||||
[azidentity/cache](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity/cache) encrypts persistent caches with the system Keychain on macOS. You may see build and runtime errors there because calling the Keychain API requires cgo and macOS prohibits Keychain access in some scenarios.
|
||||
|
||||
#### Build errors
|
||||
|
||||
Build errors about undefined `accessor` symbols indicate that cgo wasn't enabled. For example:
|
||||
```
|
||||
$ GOOS=darwin go build
|
||||
# github.com/Azure/azure-sdk-for-go/sdk/azidentity/cache
|
||||
../../go/pkg/mod/github.com/!azure/azure-sdk-for-go/sdk/azidentity/cache@v0.3.0/darwin.go:18:19: undefined: accessor.New
|
||||
../../go/pkg/mod/github.com/!azure/azure-sdk-for-go/sdk/azidentity/cache@v0.3.0/darwin.go:18:38: undefined: accessor.WithAccount
|
||||
```
|
||||
|
||||
Try `go build` again with `CGO_ENABLED=1`. You may need to install native build tools.
|
||||
|
||||
#### Runtime errors
|
||||
|
||||
macOS prohibits Keychain access from environments without a GUI such as SSH sessions. If your application calls the persistent cache constructor ([cache.New](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity/cache#New)) from an SSH session on a macOS host, you'll see an error like
|
||||
`persistent storage isn't available due to error "User interaction is not allowed. (-25308)"`. This doesn't mean authentication is impossible, only that credentials can't persist data and the application must reauthenticate the next time it runs.
|
||||
|
||||
## Get additional help
|
||||
|
||||
Additional information on ways to reach out for support can be found in [SUPPORT.md](https://github.com/Azure/azure-sdk-for-go/blob/main/SUPPORT.md).
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Azure Identity Cache Module for Go
|
||||
|
||||
This module implements a cross-platform persistent token cache for [azidentity](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity) credentials. See that module's [examples](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#pkg-examples) for sample code showing how to configure persistent caching for a credential.
|
||||
This module implements a cross-platform persistent token cache for [azidentity](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity) credentials. See that module's [examples](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#pkg-examples) for sample code showing how to configure persistent caching for a credential, and its [token caching document](https://aka.ms/azsdk/go/identity/caching) for more information about the implementation.
|
||||
|
||||
## Provide Feedback
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче