fuchsia.identity.tokens

Defines the data types and protocols used to request user authorization tokens and identity information from service providers and identity providers.

The actual interaction with these providers is through lower level protocols defined in fuchsia.id.external.

PROTOCOLS

TokenManager

Defined in fuchsia.identity.tokens/token_manager.fidl

TokenManager maintains a set of credentials for accounts with service providers (such as Google) and provides access to standard tokens based on these credentials (such as OAuth2 access tokens and OpenID Connect ID tokens). This provides a "single sign-on" experience for these services on Fuchsia, where multiple components can use a service without requiring that the user signs in multiple times.

ListServiceProviders

Returns the list of service providers that are available through this TokenManager.

  • service_providers a vector of available service providers.

Request

NameType

Response

NameType
result TokenManager_ListServiceProviders_Result

ListAccounts

Returns the list of currently authorized accounts for a particular service provider.

  • service_provider the service provider to query.
  • account_ids a vector of authorized accounts for service_provider.

Request

NameType
service_provider ServiceProvider

Response

NameType
result TokenManager_ListAccounts_Result

AddAccount

Acquires credentials for a new account from a service provider.

This process typically requires the user to interactively authenticate with the service provider and authorize the requested access.

Once AddAccount has succeeded, tokens for the account may be acquired using the other TokenManager methods.

  • service_provider The ServiceProvider used to authorize the new account.
  • scopes A list of OAuth scope strings that the caller wishes to subsequently use in GetOauthAccessToken. The AuthProvider component chooses if and how to combine these with any default or threshold scopes.
  • account_id A unique identifier within this service provider for the newly authorized account.
  • error ABORTED The user cancelled or failed an interactive flow.
  • error SERVICE_PROVIDER_DENIED The service provider refused to grant the requested token.

Request

NameType
service_provider ServiceProvider
scopes vector<string>[64]

Response

NameType
result TokenManager_AddAccount_Result

ReauthorizeAccount

Refreshes credentials or changes credential scopes for an account that was previously authorized.

This process may require the user to interactively authenticate with the service provider and authorize the requested access.

  • service_provider The ServiceProvider used to reauthorize the account.
  • account_id An AccountId that has previously been authorized for this ServiceProvider.
  • scopes A list of OAuth scope strings that the caller wishes to subsequently use in GetOauthAccessToken. The AuthProvider component chooses if and how to combine these with any default or threshold scopes.
  • error ABORTED The user cancelled or failed an interactive flow.
  • error SERVICE_PROVIDER_DENIED The service provider refused to grant the requested token.

Request

NameType
service_provider ServiceProvider
account_id AccountId
scopes vector<string>[64]

Response

NameType
result TokenManager_ReauthorizeAccount_Result

GetOauthAccessToken

Returns an OAuth 2.0 access token for the specified account.

The access token may optionally be sidescoped (i.e. issued to a different client_id than the default client_id used during authorization) and may contain a smaller set of scopes than those acquired during authorization.

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. 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.

  • service_provider The ServiceProvider from which the token should be requested.
  • account_id An AccountId that has previously been authorized for this ServiceProvider.
  • client_id The ClientId that the token will be used by. If ommitted (and if supported by the auth provider component) a default client_id is used.
  • scopes A list of OAuth scopes that should be included in the token, as defined by the service provider's API documention.
  • access_token An OauthAccessToken.
  • error ABORTED The user rejected an interactive permission request.
  • error SERVICE_PROVIDER_DENIED The service provider refused to grant the requested token.
  • error SERVICE_PROVIDER_REAUTHORIZE The service provider requires that the user reauthenticate before supplying the requested token. The client should call the ReauthorizeAccount method before retrying the request.

Request

NameType
service_provider ServiceProvider
account_id AccountId
client_id ClientId
scopes vector<string>[64]

Response

NameType
result TokenManager_GetOauthAccessToken_Result

GetOpenIdUserInfo

Returns user information for the specified account as defined by OpenID Connect.

  • service_provider The ServiceProvider from which the token should be requested.
  • account_id An AccountId that has previously been authorized for this ServiceProvider.
  • user_info An OpenIdUserInfo containing account information.
  • error ABORTED The user rejected an interactive permission request.
  • error SERVICE_PROVIDER_REAUTHORIZE The service provider requires that the user reauthenticate before supplying the user info.
  • error UNSUPPORTED_OPERATION The auth provider does not support OpenID Connect.

Request

NameType
service_provider ServiceProvider
account_id AccountId

Response

NameType
result TokenManager_GetOpenIdUserInfo_Result

GetOpenIdToken

Returns an OpenID Connect ID token for the specified account.

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.

  • service_provider The ServiceProvider from which the token should be requested.
  • account_id An AccountId that has previously been authorized for this ServiceProvider.
  • audience The Audience that the ID token will be used by. If ommitted (and if supported by the auth provider component) a default audience is used.
  • id_token An OpenIdToken.
  • error ABORTED The user rejected an interactive permission request.
  • error SERVICE_PROVIDER_DENIED The service provider refused to grant the requested token.
  • error SERVICE_PROVIDER_REAUTHORIZE The service provider requires that the user reauthenticate before supplying the user info.
  • error UNSUPPORTED_OPERATION The auth provider does not support OpenID Connect.

Request

NameType
service_provider ServiceProvider
account_id AccountId
audience Audience

Response

NameType
result TokenManager_GetOpenIdToken_Result

DeleteAccount

Deletes and revokes all long lived and short lived tokens generated for an account.

Deletion of tokens involves three steps:

  1. Revoking credentials remotely at the service provider.
  2. Deleting short lived tokens from the in-memory cache.
  3. Deleting persistent credentials stored locally on disk.

If force is false then a failure at step 1 terminates the method, ensuring client and server state remain consistent. If force is true then steps 2&3 are performed and the method returns success even if step 1 fails, ensuring the local credentials are wiped in all circumstances.

  • service_provider The ServiceProvider from which the token should be requested.
  • account_id An AccountId that has previously been authorized for this ServiceProvider.
  • force Whether to force local deletion even when the remote revocation cannot be completed.

Request

NameType
service_provider ServiceProvider
account_id AccountId
force bool

Response

NameType
result TokenManager_DeleteAccount_Result

TokenManagerFactory

Defined in fuchsia.identity.tokens/token_manager_factory.fidl

TokenManagerFactory provides access to a global TokenManager on systems that do not include an AccountManager.

On systems that do include AccountManager, that API should be used to acquire a separate TokenManager instance for each system account.

GetTokenManager

Connects a new TokenManager channel.

  • ui_context_provider An AuthenticationContextProvider capable of generating the AuthenticationUiContext channels used to display interactive authentication and authorization flows.
  • token_manager The server end of a TokenManager channel.

Request

NameType
ui_context_provider fuchsia.auth/AuthenticationContextProvider
token_manager request<TokenManager>

STRUCTS

TokenManager_ListServiceProviders_Response

Defined in fuchsia.identity.tokens/token_manager.fidl

NameTypeDescriptionDefault
service_providers vector<string>[128] No default

TokenManager_ListAccounts_Response

Defined in fuchsia.identity.tokens/token_manager.fidl

NameTypeDescriptionDefault
account_ids vector<string>[128] No default

TokenManager_AddAccount_Response

Defined in fuchsia.identity.tokens/token_manager.fidl

NameTypeDescriptionDefault
account_id AccountId No default

TokenManager_ReauthorizeAccount_Response

Defined in fuchsia.identity.tokens/token_manager.fidl

NameTypeDescriptionDefault

TokenManager_GetOauthAccessToken_Response

Defined in fuchsia.identity.tokens/token_manager.fidl

NameTypeDescriptionDefault
access_token OauthAccessToken No default

TokenManager_GetOpenIdUserInfo_Response

Defined in fuchsia.identity.tokens/token_manager.fidl

NameTypeDescriptionDefault
user_info OpenIdUserInfo No default

TokenManager_GetOpenIdToken_Response

Defined in fuchsia.identity.tokens/token_manager.fidl

NameTypeDescriptionDefault
id_token OpenIdToken No default

TokenManager_DeleteAccount_Response

Defined in fuchsia.identity.tokens/token_manager.fidl

NameTypeDescriptionDefault

ENUMS

Error

Type: uint32

Defined in fuchsia.identity.tokens/common.fidl

Specifies the reason that a fuchsia.identity.tokens 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 Token Manager itself. Retry is optional.

UNSUPPORTED_OPERATION 3

The requested operation is not supported for the requested entity. For example, some service providers may not support some types of token. The request should not be retried.

INVALID_REQUEST 4

The request was malformed in some way, such as using an empty string for service provider. 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 a server or the server was unreachable. Retry, after a delay, is recommended.

INVALID_SERVICE_PROVIDER 7

The request referred to a missing service provider or one where the auth provider component is misconfigured or failed.

INVALID_ACCOUNT 8

The request referred to an account that is not found for the specified service provider. The request should not be retried.

SERVICE_PROVIDER_ERROR 10

The service provider returned a error that indicates a failure within the service provider itself. Retry, after a delay, is recommended.

SERVICE_PROVIDER_DENIED 11

The service provider refused to grant the requested token. The request should not be retried.

SERVICE_PROVIDER_REAUTHORIZE 12

The service provider requires that the user reauthenticate before supplying the requested token. The client should call the ReauthorizeAccount method before retrying the request.

ABORTED 13

The user cancelled or failed an interactive flow. The caller should gather user consent before any retry of the request.

TABLES

OauthRefreshToken

Defined in fuchsia.identity.tokens/token_types.fidl

A long-lived OAuth 2.0 Refresh Token.

OrdinalNameTypeDescription
1 content string

The content of the token.

2 account_id AccountId

A unique identifier for the account that the token refers to, as specified by the authorization server.

OauthAccessToken

Defined in fuchsia.identity.tokens/token_types.fidl

An OAuth 2.0 Access Token.

OrdinalNameTypeDescription
1 content string

The content of the token.

2 expiry_time zx/time

The time on ZX_CLOCK_UTC at which the token will expire. If the field is absent the token does not have a fixed expiry time.

OpenIdToken

Defined in fuchsia.identity.tokens/token_types.fidl

An OpenID Connect ID Token.

OrdinalNameTypeDescription
1 content string

The content of the JSON Web Token.

2 expiry_time zx/time

The time on ZX_CLOCK_UTC at which the token will expire. If the field is absent the token does not have a fixed expiry time.

OpenIdUserInfo

Defined in fuchsia.identity.tokens/token_types.fidl

The reponse from an OpenID Connect UserInfo endpoint.

OrdinalNameTypeDescription
1 subject string[255]

The subject to which this info applies.

2 name string

The user's full name.

3 email string

The user's email address.

4 picture string

A URL to a profile picture for the user.

UNIONS

TokenManager_ListServiceProviders_Result

Defined in fuchsia.identity.tokens/token_manager.fidl

NameTypeDescription
response TokenManager_ListServiceProviders_Response
err Error

TokenManager_ListAccounts_Result

Defined in fuchsia.identity.tokens/token_manager.fidl

NameTypeDescription
response TokenManager_ListAccounts_Response
err Error

TokenManager_AddAccount_Result

Defined in fuchsia.identity.tokens/token_manager.fidl

NameTypeDescription
response TokenManager_AddAccount_Response
err Error

TokenManager_ReauthorizeAccount_Result

Defined in fuchsia.identity.tokens/token_manager.fidl

NameTypeDescription
response TokenManager_ReauthorizeAccount_Response
err Error

TokenManager_GetOauthAccessToken_Result

Defined in fuchsia.identity.tokens/token_manager.fidl

NameTypeDescription
response TokenManager_GetOauthAccessToken_Response
err Error

TokenManager_GetOpenIdUserInfo_Result

Defined in fuchsia.identity.tokens/token_manager.fidl

NameTypeDescription
response TokenManager_GetOpenIdUserInfo_Response
err Error

TokenManager_GetOpenIdToken_Result

Defined in fuchsia.identity.tokens/token_manager.fidl

NameTypeDescription
response TokenManager_GetOpenIdToken_Response
err Error

TokenManager_DeleteAccount_Result

Defined in fuchsia.identity.tokens/token_manager.fidl

NameTypeDescription
response TokenManager_DeleteAccount_Response
err Error

CONSTANTS

NameValueTypeDescription
MAX_ACCOUNT_ID_SIZE 256 uint32

The maximum length of an account ID string, in bytes.

MAX_CLIENT_ID_SIZE 256 uint32

The maximum length of an OAuth client ID, in bytes.

MAX_SCOPE_SIZE 256 uint32

The maximum length of an OAuth scope, in bytes.

MAX_SCOPE_COUNT 64 uint32

The maximum number of OAuth scopes that may be requested for a single token.

MAX_AUDIENCE_SIZE 256 uint32

The maximum length of an OpenID audience string, in bytes.

MAX_AUDIENCE_COUNT 16 uint32

The maximum number of audiences that may be requested for a single ID token.

MAX_SERVICE_PROVIDER_COUNT 128 uint32

The maximum number of service providers for which AuthProvider components can be simultaneously installed.

MAX_ACCOUNT_COUNT 128 uint32

The maximum number of Accounts that can be authorized within a service provider for a single instance of TokenManager.

TYPE ALIASES

NameValueDescription
AccountId string[MAX_ACCOUNT_ID_SIZE]

An identifier for the account that a token is issued against, as specified by the authorization server. Account identifiers are guaranteed to be unique within an auth provider type.

ClientId string[MAX_CLIENT_ID_SIZE]

An OAuth client ID string.

Scope string[MAX_SCOPE_SIZE]

An OAuth scope string.

Audience string[MAX_AUDIENCE_SIZE]

An OpenID audience string.

ServiceProvider string

The primary domain name of the service provider used to authorize accounts. Only one AuthProvider component can be installed for each service provider at a time.