fuchsia.identity.account

PROTOCOLS

AccountManager

Defined in fuchsia.identity.account/account_manager.fidl

AccountManager manages the overall state of Fuchsia accounts and personae on a Fuchsia device, installation of the AuthProviders that are used to obtain authentication tokens for these accounts, and access to TokenManagers for these accounts.

The AccountManager is the most powerful protocol in the authentication system and is intended only for use by the most trusted parts of the system.

GetAccountIds

Returns a vector of all unlocked accounts provisioned on the current device.

Request

NameType

Response

NameType
account_ids vector<uint64>[128]

GetAccountAuthStates

Returns a vector of all unlocked accounts provisioned on the current device and the current authentication state for each.

Request

NameType

Response

NameType
result AccountManager_GetAccountAuthStates_Result

GetAccount

Connects a channel to read properties of and perform operations on one account.

id The account's identifier as returned by GetAccountIds() context_provider An AuthenticationContextProvider capable of supplying UI contexts used for interactive authentication on this account account The server end of an Account channel

Request

NameType
id uint64
context_provider fuchsia.auth/AuthenticationContextProvider
account request<Account>

Response

NameType
result AccountManager_GetAccount_Result

RegisterAccountListener

Connects a channel that will receive changes in the provisioned accounts and their authentication state. Optionally this channel will also receive the initial set of accounts and authentication states onto which changes may be applied.

listener The client end of an AccountListener channel options An AccountListenerOptions that defines the set of events to be sent to the listener.

Request

NameType
listener AccountListener
options AccountListenerOptions

Response

NameType
result AccountManager_RegisterAccountListener_Result

RemoveAccount

Removes a provisioned Fuchsia account from the current device, revoking any credentials that are held for the account.

id The account's identifier as returned by GetAccountIds() force If true, continues removing the account even if revocation of credentials fails. If false, any revocation failure will result in an error and the account will remain. In this case, a subset of the credentials may have been deleted.

Request

NameType
id uint64
force bool

Response

NameType
result AccountManager_RemoveAccount_Result

ProvisionFromAuthProvider

Adds a Fuchsia account to the current device based on authenticating to a service provider (such as Google). If the service provider account is not already a recovery account for any Fuchsia account, a new Fuchsia account will be created with its recovery account set to the service provider account.

auth_context_provider An AuthenticationContextProvider capable of supplying UI contexts used for interactive authentication auth_provider_type A unique identifier for an installed AuthProvider that should be used to authenticate with the service provider lifetime The lifetime of the account

Returns: account_id The identifier of the newly added account

Request

NameType
auth_context_provider fuchsia.auth/AuthenticationContextProvider
auth_provider_type string[128]
lifetime Lifetime

Response

NameType
result AccountManager_ProvisionFromAuthProvider_Result

ProvisionNewAccount

Adds a new, initially empty, Fuchsia account to the current device.

lifetime The lifetime of the account

Returns: account_id The identifier of the newly added account

Request

NameType
lifetime Lifetime

Response

NameType
result AccountManager_ProvisionNewAccount_Result

AccountListener

Defined in fuchsia.identity.account/account_manager.fidl

A protocol to receive events when the set of accounts on a device or the authentication states of these accounts change.

AccountListeners may be registered through the AccountManager protocol and this registration also defines which types of event should be sent to the listener. Optionally, the AccountListener will receive an initial state event onto which the change events may be safely accumulated.

All methods include an empty response to follow the "Throttle push using acknowledgements" FIDL design pattern.

OnInitialize

A method that is called to communicate the initial set of accounts and their authentication states. OnInitialize is called exactly once if and only if AccountListenerOptions.initial_state was set when creating the AccountListener. When called, it will always be the first call on the channel. If no accounts are present on the device the vector will be empty.

Request

NameType
account_auth_states vector<AccountAuthState>[128]

Response

NameType

OnAccountAdded

A method that is called when a new account is added to the device. This method is only called if AccountListenerOptions.add_account was set when creating the AccountListener.

Request

NameType
id uint64

Response

NameType

OnAccountRemoved

A method that is called when a provisioned account is removed. This method is only called if AccountListenerOptions.remove_account was set when creating the AccountListener.

Request

NameType
id uint64

Response

NameType

OnAuthStateChanged

A method that is called when the authentication state of any provisioned account changes.

Request

NameType
account_auth_state AccountAuthState

Response

NameType

AuthListener

Defined in fuchsia.identity.account/auth_target.fidl

A protocol to receive events when the authentication state of an account changes.

AuthListeners may be registered through the AuthTarget protocol and this registration also defines the types of authentication state changes that should be sent to the listener.

All methods include an empty response to follow the "Throttle push using acknowledgements" FIDL design pattern.

OnInitialize

A method that is called when the AccountListener is first connected.

Request

NameType
auth_state fuchsia.auth/AuthState

Response

NameType

OnAuthStateChanged

A method that is called when the authentication state of the account changes.

Request

NameType
auth_state fuchsia.auth/AuthState

Response

NameType

AuthTarget

Defined in fuchsia.identity.account/auth_target.fidl

A protocol that is extended by other protocols defining an entity (referred to as the "target") with an authentication state, such as a Fuchsia account or persona.

AuthTarget defines a set of methods to monitor the current authentication state of an entity and to request changes in that authentication state.

GetAuthState

Returns the current AuthState of the target.

Request

NameType

Response

NameType
result AuthTarget_GetAuthState_Result

RegisterAuthListener

Connects a channel that will receive changes in the authentication state of the target.

listener The client end of an AuthListener channel initial_state If true, the listener will receive the initial auth state in addition to any changes. granularity An AuthChangeGranularity expressing the magnitude of change in authentication state than should lead to a callback

Request

NameType
listener AuthListener
initial_state bool
granularity fuchsia.auth/AuthChangeGranularity

Response

NameType
result AuthTarget_RegisterAuthListener_Result

Account

Defined in fuchsia.identity.account/auth_target.fidl

A protocol that exposes information about the personae and recovery account for a Fuchsia account and provides methods to manipulate these.

An Account provides access to sensitive long term identifiers and is only intended only for use by a small number of trusted system components.

GetAuthState

Returns the current AuthState of the target.

Request

NameType

Response

NameType
result AuthTarget_GetAuthState_Result

RegisterAuthListener

Connects a channel that will receive changes in the authentication state of the target.

listener The client end of an AuthListener channel initial_state If true, the listener will receive the initial auth state in addition to any changes. granularity An AuthChangeGranularity expressing the magnitude of change in authentication state than should lead to a callback

Request

NameType
listener AuthListener
initial_state bool
granularity fuchsia.auth/AuthChangeGranularity

Response

NameType
result AuthTarget_RegisterAuthListener_Result

GetAccountName

Returns a human readable name for the account. Account names are set by a human and are not guaranteed to be meaningful or unique, even among the accounts on a single device.

Request

NameType

Response

NameType
name string[128]

GetLifetime

Returns the account's lifetime.

Request

NameType

Response

NameType
lifetime Lifetime

GetPersonaIds

Returns a vector of all the personae defined for the account. NOTE: Currently all Fuchsia accounts have exactly one persona.

Request

NameType

Response

NameType
persona_ids vector<uint64>[128]

GetDefaultPersona

Connects a channel to read properties of and access tokens for the default persona for the account.

persona The client end of a Persona channel

Returns: id The identifier for the default persona

Request

NameType
persona request<Persona>

Response

NameType
result Account_GetDefaultPersona_Result

GetPersona

Connects a channel to read properties of and access tokens for one of the personae for the account.

id The persona's identifier as returned by GetPersonaIds() persona The client end of a Persona channel

Request

NameType
id uint64
persona request<Persona>

Response

NameType
result Account_GetPersona_Result

GetRecoveryAccount

Returns the service provider account that can be used to access the Fuchsia account if more direct methods of authentication are not available, provided such an account exists.

Returns: The ServiceProviderAccount used for recovery if one exists

Request

NameType

Response

NameType
result Account_GetRecoveryAccount_Result

SetRecoveryAccount

Sets the service provider account that can be used to access the Fuchsia account if more direct methods of authentication are not available.

account The ServiceProviderAccount to use as the recovery account. This must be an existing account that has already been provisioned on the current device using TokenManager.

Request

NameType
account fuchsia.auth/ServiceProviderAccount

Response

NameType
result Account_SetRecoveryAccount_Result

Persona

Defined in fuchsia.identity.account/auth_target.fidl

A protocol that exposes basic information about a Fuchsia persona and access to the authentication tokens that are visible through it.

Note a Persona purposefully does not provide access to a long term identifier for the persona. This is to support components in the system that work with short lived identifiers (e.g. SessionManager), but note that long term identifiers can usually still be derived via the TokenManger protocol.

GetAuthState

Returns the current AuthState of the target.

Request

NameType

Response

NameType
result AuthTarget_GetAuthState_Result

RegisterAuthListener

Connects a channel that will receive changes in the authentication state of the target.

listener The client end of an AuthListener channel initial_state If true, the listener will receive the initial auth state in addition to any changes. granularity An AuthChangeGranularity expressing the magnitude of change in authentication state than should lead to a callback

Request

NameType
listener AuthListener
initial_state bool
granularity fuchsia.auth/AuthChangeGranularity

Response

NameType
result AuthTarget_RegisterAuthListener_Result

GetLifetime

Returns the lifetime of this persona.

Request

NameType

Response

NameType
lifetime Lifetime

GetTokenManager

Connects a channel to acquire and revoke authentication tokens for service provider (aka cloud service) accounts that are visible through this persona.

application_url A url for the Fuchsia agent that this channel will be used by. Applications are only allowed to access tokens that they created. token_manager The client end of a Persona channel

Request

NameType
application_url string[2083]
token_manager request<fuchsia.auth/TokenManager>

Response

NameType
result Persona_GetTokenManager_Result

STRUCTS

AccountManager_GetAccountAuthStates_Response

generated

NameTypeDescriptionDefault
account_auth_states vector<AccountAuthState>[128] No default

AccountManager_GetAccount_Response

generated

NameTypeDescriptionDefault

AccountManager_RegisterAccountListener_Response

generated

NameTypeDescriptionDefault

AccountManager_RemoveAccount_Response

generated

NameTypeDescriptionDefault

AccountManager_ProvisionFromAuthProvider_Response

generated

NameTypeDescriptionDefault
account_id uint64 No default

AccountManager_ProvisionNewAccount_Response

generated

NameTypeDescriptionDefault
account_id uint64 No default

AccountAuthState

Defined in fuchsia.identity.account/account_manager.fidl

An AuthState along with the account that it applies to.

NameTypeDescriptionDefault
account_id uint64 A unique identifier for the Fuchsia account on the current device. No default
auth_state fuchsia.auth/AuthState An authentication state for the Fuchsia account. No default

AccountListenerOptions

Defined in fuchsia.identity.account/account_manager.fidl

The configuration for an AccountListener, defining the set of events that it will receive.

NameTypeDescriptionDefault
initial_state bool If true, the listener will receive the initial auth state for all accounts. No default
add_account bool If true, the listener will receive events when a new account is added to the device. No default
remove_account bool If true, the listener will receive events. No default
granularity fuchsia.auth/AuthChangeGranularity An `AuthChangeGranularity` expressing the magnitude of change in authentication state that will lead to AuthStateChange events. No default

AuthTarget_GetAuthState_Response

generated

NameTypeDescriptionDefault
auth_state fuchsia.auth/AuthState No default

AuthTarget_RegisterAuthListener_Response

generated

NameTypeDescriptionDefault

Account_GetDefaultPersona_Response

generated

NameTypeDescriptionDefault
id uint64 No default

Account_GetPersona_Response

generated

NameTypeDescriptionDefault

Account_GetRecoveryAccount_Response

generated

NameTypeDescriptionDefault
account fuchsia.auth/ServiceProviderAccount? No default

Account_SetRecoveryAccount_Response

generated

NameTypeDescriptionDefault

Persona_GetTokenManager_Response

generated

NameTypeDescriptionDefault

ENUMS

Lifetime

Type: uint8

Defined in fuchsia.identity.account/common.fidl

Provides an upper bound to how long a Fuchsia account can live on the current device.

NameValueDescription
EPHEMERAL 1 The account lives at the longest to the end of the power cycle it was created in.
PERSISTENT 2 The account lives on the device until it is removed.

Error

Type: uint32

Defined in fuchsia.identity.account/common.fidl

Specifies the reason that a fuchsia.identity.account method failed.

NameValueDescription
UNKNOWN 1 Some other problem occurred that cannot be classified using one of the more specific statuses. Retry is optional.
INTERNAL 2 An internal error occurred. This usually indicates a bug within the account system itself. Retry is optional.
UNSUPPORTED_OPERATION 3 The requested operation is not supported. This generally indicates that implementation of a new feature is not yet complete. The request should not be retried.
INVALID_REQUEST 4 The request was malformed in some way, such as using an empty string for auth_provider_type. The request should not be retried.
RESOURCE 5 A local resource error occurred such as I/O, FIDL, or memory allocation failure. Retry, after a delay, is recommended.
NETWORK 6 A network error occurred while communicating with an auth server. Retry, after a delay, is recommended.
NOT_FOUND 7 The requested account or persona is not present on the current device. The request should not be retried.
REMOVAL_IN_PROGRESS 8 The request cannot be processed due to an ongoing account or persona removal. The removal is not guaranteed to suceed and so retry, after a delay, is recommended.
FAILED_PRECONDITION 9 The server is not in the state required to perform the requested operation. The request should not be retried unless the server state has been corrected before the retry.

UNIONS

AccountManager_GetAccountAuthStates_Result

generated

NameTypeDescription
response AccountManager_GetAccountAuthStates_Response
err Error

AccountManager_GetAccount_Result

generated

NameTypeDescription
response AccountManager_GetAccount_Response
err Error

AccountManager_RegisterAccountListener_Result

generated

NameTypeDescription
response AccountManager_RegisterAccountListener_Response
err Error

AccountManager_RemoveAccount_Result

generated

NameTypeDescription
response AccountManager_RemoveAccount_Response
err Error

AccountManager_ProvisionFromAuthProvider_Result

generated

NameTypeDescription
response AccountManager_ProvisionFromAuthProvider_Response
err Error

AccountManager_ProvisionNewAccount_Result

generated

NameTypeDescription
response AccountManager_ProvisionNewAccount_Response
err Error

AuthTarget_GetAuthState_Result

generated

NameTypeDescription
response AuthTarget_GetAuthState_Response
err Error

AuthTarget_RegisterAuthListener_Result

generated

NameTypeDescription
response AuthTarget_RegisterAuthListener_Response
err Error

Account_GetDefaultPersona_Result

generated

NameTypeDescription
response Account_GetDefaultPersona_Response
err Error

Account_GetPersona_Result

generated

NameTypeDescription
response Account_GetPersona_Response
err Error

Account_GetRecoveryAccount_Result

generated

NameTypeDescription
response Account_GetRecoveryAccount_Response
err Error

Account_SetRecoveryAccount_Result

generated

NameTypeDescription
response Account_SetRecoveryAccount_Response
err Error

Persona_GetTokenManager_Result

generated

NameTypeDescription
response Persona_GetTokenManager_Response
err Error

CONSTANTS

NameValueTypeDescription
MAX_ACCOUNTS_PER_DEVICE 128 uint32 The maximum number of Fuchsia accounts that may be simultaneously provisioned on a device. This number may be increased in the future.
MAX_PERSONAE_PER_ACCOUNT 128 uint32 The maximum number of personae that may be simultaneously defined within a Fuchsia account. This number may be increased in the future.
MAX_ID_SIZE 256 uint32 The maximum length of the global Fuchsia account and persona identifiers, in bytes.
MAX_NAME_SIZE 128 uint32 The maximum length of the (UTF-8 encoded) human readable names, in bytes.
MAX_AUTH_PROVIDER_TYPE_SIZE 128 uint32 The maximum length of an (UTF-8 encoded) auth provider type, in bytes.