PROTOCOLS
AttestationSigner
Defined in fuchsia.auth/attestation_signer.fidl
SignData
Cryptographically signs the plaintext data sent in request using a
crypto key configured at initialization.
Returns the raw bytes of the signature string on success. Otherwise,
an error status is returned.
Request
| Name | Type |
|---|---|
plaintext |
vector<uint8>
|
Response
| Name | Type |
|---|---|
status |
AttestationSignerStatus
|
signature |
vector<uint8>?
|
AuthenticationContextProvider
Defined in fuchsia.auth/token_manager.fidl
Implemented by a privileged system component with the ability to display UI to the end user.
This is provided during the initialization of TokenManager service and is used for any subsequent authorize calls. The UI contexts created by this interface are used to display OAuth login and permission screens to the end user.
GetAuthenticationUIContext
Request
| Name | Type |
|---|---|
request |
server_end<AuthenticationUIContext>
|
AuthenticationUIContext
Defined in fuchsia.auth/auth_provider.fidl
This interface is implemented by base shell. It is used to notify the base shell that a view for login needs to be started / stopped.
StartOverlay
Requests base shell to display view_holder_token for authentication.
Another call to StartOverlay() will not be made until StopOverlay()
has been called.
Request
| Name | Type |
|---|---|
view_holder_token |
fuchsia.ui.views/ViewHolderToken
|
StopOverlay
Requests base shell to stop displaying the auth view.
Request
<EMPTY>
TokenManager
Defined in fuchsia.auth/token_manager.fidl
This interface manages OAuth tokens at the Fuchsia system level for different auth identity providers.
If user authorization is required for minting tokens, TokenManager uses the
auth_context_provider's UI context for displaying OAuth UI to the end user.
After initialization, TokenManager handles are typically handed out by
Framework to components like Ledger and Agents. These components fetch
OAuth tokens from any configured auth provider, and use the
auth_context_provider initialized above for new authorizations.
Authorize
The first step of OAuth is to get authorization from the user. For Fuchsia
components, this is accomplished by displaying OAuth permissions in a view
provided by the caller. This view will use auth_ui_context if supplied,
or the auth_context_provider supplied at TokenManager creation if not.
The component's OAuth configuration is provided in app_config and
app_scopes. An optional user_profile_id that uniquely identifies an
account for a given auth provider may be provided to identify an existing
account during a re-auth flow.
IoT ID authorization includes a mode where the user authorizes on a second
device and that device acquires an auth code from the auth provider.
In this mode, the auth code may be supplied in auth_code and no local
user interface will be displayed.
After the user has successfully authorized, Token manager receives and securely stores a persistent credential, such as an OAuth refresh token, for the intended scopes. TokenManager later uses this credential for minting short lived tokens.
If the operation is successful, an OK status is returned along with user
profile information in user_profile_info such as the user's email,
image_url, profile_url, and first and last names as configured on the auth
provider backend system.
Request
| Name | Type |
|---|---|
app_config |
AppConfig
|
auth_ui_context |
AuthenticationUIContext?
|
app_scopes |
vector<string>
|
user_profile_id |
string?
|
auth_code |
string?
|
Response
| Name | Type |
|---|---|
status |
Status
|
user_profile_info |
UserProfileInfo?
|
DeleteAllTokens
Deletes and revokes all long lived and short lived tokens generated for
an account and on behalf of a Fuchsia component. The component's OAuth
configuration is provided in app_config and user_profile_id
is a unique account identifier returned by the Authorize() or
ListProfileIds() calls.
Deletion of tokens involves three steps:
- Revoking credentials remotely at the auth provider.
- Deleting short lived tokens from the in-memory cache.
- Deleting persistent credentials stored locally on disk.
If force is false then a failure at step 1 will terminate the method,
ensuring client and server state remain consistent. If force is true
then steps 2&3 will be performed and the method will return OK even if
step 1 fails, ensuring the local credentials are wiped in all
circumstances.
Request
| Name | Type |
|---|---|
app_config |
AppConfig
|
user_profile_id |
string
|
force |
bool
|
Response
| Name | Type |
|---|---|
status |
Status
|
GetAccessToken
Returns a downscoped access token from an auth provider for the given user
user_profile_id and scopes to a Fuchsia component. The component's
OAuth configuration is provided in app_config and the user_profile_id
is the unique user identifier returned by the Authorize() call.
In the interests of performance, Token Manager does not place the supplied scopes in a canonical order during caching. To benefit from caching of tokens, clients must request the same scopes in the same order across calls.
The access token is returned from cache if possible, otherwise the auth provider is used to exchange the persistent credential for a new access token.
Request
| Name | Type |
|---|---|
app_config |
AppConfig
|
user_profile_id |
string
|
app_scopes |
vector<string>
|
Response
| Name | Type |
|---|---|
status |
Status
|
access_token |
string?
|
GetIdToken
Returns a JWT identity token from an auth provider to a Fuchsia component
intended for the given audience. The component's OAuth configuration is
supplied in app_config, the intended recipient of the id_token is
supplied in audience, and user_profile_id is a unique account
identifier returned by the Authorize() or ListProfileIds() calls.
user_profile_id is the unique user identifier returned by the
Authorize() call.
The identity token is returned from cache if possible, otherwise the auth provider is used to exchange the persistant credential for a new identity token.
Request
| Name | Type |
|---|---|
app_config |
AppConfig
|
user_profile_id |
string
|
audience |
string?
|
Response
| Name | Type |
|---|---|
status |
Status
|
id_token |
string?
|
ListProfileIds
Returns a vector of all currently authorized user_profile_ids for a
component's OAuth configuration provided in app_config.
Request
| Name | Type |
|---|---|
app_config |
AppConfig
|
Response
| Name | Type |
|---|---|
status |
Status
|
user_profile_ids |
vector<string>
|
TokenManagerFactory
Defined in fuchsia.auth/token_manager.fidl
This interface provides a discoverable mechanism to create TokenManager
instances for each user, and to supply auth provider configuration
information using the structs defined in auth_provider.fidl.
GetTokenManager
Creates an OAuth TokenManager instance scoped for the component specified
by application_url, the Fuchsia user specified by user_id, and the list
of auth providers specified in auth_provider_configs.
auth_context_provider is used to generate AuthenticationUIContexts during
TokenManager methods that require UI, unless the caller of those methods
supplies an alternative AuthenticationUIContext.
Request
| Name | Type |
|---|---|
user_id |
string
|
application_url |
string
|
auth_provider_configs |
vector<AuthProviderConfig>
|
auth_context_provider |
AuthenticationContextProvider
|
token_manager |
server_end<TokenManager>
|
STRUCTS
AppConfig
Defined in fuchsia.auth/token_manager.fidl
Stores OAuth configuration details for a given client application. These details are used in the OAuth authorization step.
| Field | Type | Description | Default |
|---|---|---|---|
auth_provider_type |
string
|
An OAuth identity provider matching a configuration set in AuthProviderConfig.auth_provider_type. |
No default |
client_id |
string?
|
OAuth client id. |
No default |
client_secret |
string?
|
OAuth client secret. This field is optional and will only be used on calls to Authorize. |
No default |
redirect_uri |
string?
|
OAuth application's redirect uri. This field is optional and will only be used on calls to Authorize. |
No default |
AuthProviderConfig
Defined in fuchsia.auth/token_manager.fidl
Stores configuration parameters required to connect to available
AuthProviders. It is used by TokenManager to instantiate all auth providers
during startup.
| Field | Type | Description | Default |
|---|---|---|---|
auth_provider_type |
string
|
Type of OAuth Identity provider. An identity provider authenticates and authorizes users for accessing their services. They also provide unique identifiers for users to interact with the system and may provide information about the user that is known to the provider. Sample auth provider types include: Dev : An identity provider that's used for development and testing. Google: Uses Google as the identity provider. Authorization from Google requires a working network connection and a web view. Spotify: Uses Spotify as an identity provider. |
No default |
url |
string
|
Url of the Fuchsia component implementing the AuthProvider. |
No default |
params |
vector<string>?
|
Optional parameters specified during AuthProvider startup. |
No default |
ServiceProviderAccount
Defined in fuchsia.auth/common.fidl
A unique identifier for an account with some service provider, comprised of the identity of the service provider and an account identity supplied by that service provider.
| Field | Type | Description | Default |
|---|---|---|---|
identity_provider_domain |
string
|
The primary domain of the identity provider, such as "www.google.com". |
No default |
user_profile_id |
string
|
User identifier as supplied by the identity provider. Some identity providers send verified email address as the identifier, some send an opaque string. |
No default |
UserProfileInfo
Defined in fuchsia.auth/auth_provider.fidl
User attributes returned to callers on authorizing a new user at any auth provider. These attributes are generated by calling the auth provider's user profile apis.
| Field | Type | Description | Default |
|---|---|---|---|
id |
string
|
User identifier returned by the backend identity provider server to identify the user after successful authorization. Some identity providers send verified email address as the identifier, and some send an opaque string as the user identifier. |
No default |
display_name |
string?
|
The name that is displayed on the base shell while logging in. Display name is fetched from user profile attributes as configured by the user at the given identity provider. |
No default |
url |
string?
|
User's profile url that is used by the base shell while logging in. Profile url is fetched from user profile attributes as configured by the user at the given identity provider. |
No default |
image_url |
string?
|
User's profile image url that is used by the base shell while logging in. Profile image url is fetched from user profile attributes as configured by the user at the given identity provider. |
No default |
ENUMS
AttestationSignerStatus strict
Type: uint32
Defined in fuchsia.auth/attestation_signer.fidl
This file contains an interface to cryptographically sign any plain text data using any crypto key. This interface is useful for signing JWT's in device attestation based authentication.
Specifies the success/failure status from the attestation signer.
| Name | Value | Description |
|---|---|---|
OK |
0 |
The command completed successfully |
INVALID_ARGUMENT |
1 |
The command referred to a missing, or an invalid argument. |
SIGNING_ERROR |
2 |
There was an error in generating crypto signatures for the given plaintext. This usually indicates errors for misconfigured keys or signature algorithms from the underlying crypto library. |
Status strict
Type: uint32
Defined in fuchsia.auth/token_manager.fidl
Specifies the success/failure status of TokenManager calls.
| Name | Value | Description |
|---|---|---|
OK |
0 |
The command completed successfully |
AUTH_PROVIDER_SERVICE_UNAVAILABLE |
1 |
The command referred to a missing, misconfigured, or failed auth provider. Retrying is not recommended. |
AUTH_PROVIDER_SERVER_ERROR |
2 |
The auth server was reachable but responded with an error. These errors are typically caused by a configuration problem or a revoked token and so should not be retried. |
INTERNAL_ERROR |
3 |
An internal error occurred. This usually indicates a bug within the Token Manager itself. Retry is optional. |
INVALID_AUTH_CONTEXT |
4 |
An invalid or non-functional AuthContextProvider was provided. Retrying is unlikely to correct this error. |
INVALID_REQUEST |
5 |
The request was malformed in some way, such as using an empty string for the user_profile_id. The request should not be retried. |
USER_NOT_FOUND |
6 |
The requested user profile could not be found in the database. The request should not be retried. |
IO_ERROR |
7 |
A local error occurred such as disk I/O or memory allocation. Retry, after a delay, is recommended. |
UNKNOWN_ERROR |
8 |
Some other problem occurred that cannot be classified using one of the more specific statuses. Retry is optional. |
REAUTH_REQUIRED |
9 |
The auth server requires that the user reauthenticate. The client should call the Authorize method. |
USER_CANCELLED |
10 |
The user cancelled the flow. User consent is required before any retry. |
NETWORK_ERROR |
11 |
A network error occurred while communicating with the auth server. Retry, after a delay, is recommended. |