fuchsia.auth

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

NameType
plaintext vector<uint8>

Response

NameType
status AttestationSignerStatus
signature vector<uint8>?

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

NameType
view_holder_token fuchsia.ui.views/ViewHolderToken

StopOverlay

Requests base shell to stop displaying the auth view.

Request

NameType

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

NameType
request request<AuthenticationUIContext>

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

NameType
user_id string
application_url string
auth_provider_configs vector<AuthProviderConfig>
auth_context_provider AuthenticationContextProvider
token_manager request<TokenManager>

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

NameType
app_config AppConfig
auth_ui_context AuthenticationUIContext?
app_scopes vector<string>
user_profile_id string?
auth_code string?

Response

NameType
status Status
user_profile_info UserProfileInfo?

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

NameType
app_config AppConfig
user_profile_id string
app_scopes vector<string>

Response

NameType
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

NameType
app_config AppConfig
user_profile_id string
audience string?

Response

NameType
status Status
id_token string?

GetFirebaseToken

Returns a Firebase token from an auth provider for the given account and Fuchsia component, and Firebase client. The component's OAuth configuration is supplied in app_config, the Firebase client is supplied in firebase_api_key, and user_profile_id is a unique account identifier returned by the Authorize() or ListProfileIds() calls.

This api invokes firebase auth's VerifyAssertion endpoint that takes an OAuth IdToken as the fuchsia.ui.input. Audience is the intended recipient of the firebase id token.

The Firebase auth token is returned from cache if possible, otherwise it is refreshed from the auth provider.

Request

NameType
app_config AppConfig
user_profile_id string
audience string
firebase_api_key string

Response

NameType
status Status
firebase_token FirebaseToken?

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:

  1. Revoking credentials remotely at the auth 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 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

NameType
app_config AppConfig
user_profile_id string
force bool

Response

NameType
status Status

ListProfileIds

Returns a vector of all currently authorized user_profile_ids for a component's OAuth configuration provided in app_config.

Request

NameType
app_config AppConfig

Response

NameType
status Status
user_profile_ids vector<string>

STRUCTS

FirebaseToken

Defined in fuchsia.auth/auth_provider.fidl

Stores attributes related to a firebase auth token for a given firebase api key.

These tokens are minted by Firebase Auth server and are meant to be used for authorizing users into Firebase services such as DB and storage.

NameTypeDescriptionDefault
id_token string

Use this as the auth token in firebase database and storage requests.

No default
local_id string?

Use this to uniquely identify users.

No default
email string?

Use this to uniquely identify user's email address provided by the Auth Provider Firebase server.

No default
expires_in uint64

The remaining lifetime of the token in seconds.

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.

NameTypeDescriptionDefault
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

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.

NameTypeDescriptionDefault
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

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.

NameTypeDescriptionDefault
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

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.

NameTypeDescriptionDefault
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

ENUMS

AttestationSignerStatus

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.

NameValueDescription
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

Type: uint32

Defined in fuchsia.auth/token_manager.fidl

Specifies the success/failure status of TokenManager calls.

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