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

AuthProvider

Defined in fuchsia.auth/auth_provider.fidl

OAuth identity service that provisions new users and provides authorization tokens for the currently enrolled users. Some common Auth Providers are Google, Facebook, Spotify and Twitter.

GetPersistentCredential

Authenticates and authorizes a user against an auth provider backend system using the OAuth protocol and returns the persistent credential such as Google's refresh token or Facebook's access token for this user. These persistent credentials are long lived and their expiration time is set by the identity provider, for example Google's refresh tokens are valid until the user changes their password or revokes access explicitly, whereas Facebook access tokens are valid for up to 60 days or until the user revokes access.

During OAuth handshake, user needs to explicitly consent to the permissions as configured at the server. The consent is presented in a web_view using an auth_ui_context overlay provided by the base_shell.

An optional user_profile_id is provided for simplifying reauthorization flow.

Request

NameType
auth_ui_context AuthenticationUIContext?
user_profile_id string?

Response

NameType
status AuthProviderStatus
credential string?
user_profile_info UserProfileInfo?

GetAppAccessToken

Exchanges a persistent user credential for a short lived app specific OAuth access token for the specified client_id and scopes. The credential is a long lived OAuth token as generated by the external identity provider in the above GetPersistentCredential() call. If no client_id is specified a default will be used.

Access tokens are used by applications to make API requests against services offered by the Auth Provider.

Returns an auth_token response containing an access token, if successful. Otherwise, an error status is returned.

Request

NameType
credential string
client_id string?
scopes vector<string>

Response

NameType
status AuthProviderStatus
auth_token AuthToken?

GetAppIdToken

Exchanges a persistent user credential for an OAuth Identity token for the specified audience. The audience is the intended recipient of the id_token. The credential is a long lived OAuth token as generated by the external identity provider in the above GetPersistentCredential() call.

OAuth Id tokens are JSON Web Tokens (JWT) that contains digitally signed identity information about the user for the intended recipient.

Returns an auth_token response containing an id token, if successful. Otherwise, an error status is returned.

Request

NameType
credential string
audience string?

Response

NameType
status AuthProviderStatus
auth_token AuthToken?

GetAppFirebaseToken

Gets a firebase auth token for the user identified by id_token and the requested |firebase_api key|. The id_token is a JWT Identity token returned from GetAppIdToken() call above.

Returns a firebase_token from the server if successful. Otherwise, an error status is returned.

Request

NameType
id_token string
firebase_api_key string

Response

NameType
status AuthProviderStatus
firebase_token FirebaseToken?

RevokeAppOrPersistentCredential

Revokes user's grants at the Auth Provider by revoking a credential. The credential is either a long lived OAuth token as returned by the GetPersistentCredential() call or an app specific access token as returned by the GetAppAccessToken() call.

Request

NameType
credential string

Response

NameType
status AuthProviderStatus

GetPersistentCredentialFromAttestationJWT

Authenticates and authorizes a user against a remote attestation based auth provider backend system that mints bound persistent credentials.

This method is capable of performing user authorization directly on the device or use the OAuth authorization code generated out-of-band on a secondary device that is sent over a secure channel to the target device. In the latter case, auth_code generated out-of-band is passed as an argument in the attestation jwt_params. Where as in the former case, user needs to explicitly consent to the permissions on the target device and the auth_code is returned to the device directly. The consent is presented in a web_view using an auth_ui_context overlay provided by the base_shell. An optional user_profile_id is provided for simplifying reauthorization flow.

The authorization code is exchanged to a bound refresh token using an attestation JWT constructed from jwt_params and is signed by the attestation_signer component passed in the request.

If the operation is successful, a long-lived credential that is bound to the originating device is returned along with an optional auth_token containing short-lived access token and an optional nonce that is used on next token exchange request. An optional user_profile_info containing user profile attributes is also returned if successful. Otherwise, an error status is returned.

Request

NameType
attestation_signer AttestationSigner
jwt_params AttestationJWTParams
auth_ui_context AuthenticationUIContext?
user_profile_id string?

Response

NameType
status AuthProviderStatus
credential string?
auth_token AuthToken?
auth_challenge AuthChallenge?
user_profile_info UserProfileInfo?

GetAppAccessTokenFromAssertionJWT

Exchanges a bound persistent user credential for a short lived app specific OAuth access token using the specified assertion JWT. The assertion JWT is constructed from jwt_params and is signed by the attestation_signer component passed in the request.

Access tokens are used by applications to make API requests against services offered by the Auth Provider.

Returns an auth_token response containing an access token and an optional updated_credential and auth_challenge to be used on next token refresh request, if successful. Otherwise, an error status is returned.

Request

NameType
attestation_signer AttestationSigner
jwt_params AssertionJWTParams
credential string
scopes vector<string>

Response

NameType
status AuthProviderStatus
updated_credential string?
auth_token AuthToken?
auth_challenge AuthChallenge?

AuthProviderFactory

Defined in fuchsia.auth/auth_provider_factory.fidl

AuthProviderFactory creates an Auth Provider that talks to a particular backend OAuth service such as Google, Facebook, or Twitter that can generate tokens as defined by auth_provider.fidl.

GetAuthProvider

Creates an auth provider instance for the given OAuth provider.

Request

NameType
auth_provider request<AuthProvider>

Response

NameType
status AuthProviderStatus

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

AuthToken

Defined in fuchsia.auth/auth_provider.fidl

OAuth token response populated after parsing JSON object that contains short-lived access token or id token returned by the auth provider.

NameTypeDescriptionDefault
token_type TokenType Type of token. No default
token string Contains access token or a JWT identity token. No default
expires_in uint64 The remaining lifetime of the token in seconds. No default

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

AuthChallenge

Defined in fuchsia.auth/auth_provider.fidl

Challenge response returned by the auth provider during remote attestation based authentication.

NameTypeDescriptionDefault
challenge string The value of nonce to be used for the next token refresh request No default
expires_in uint64 The lifetime of `challenge` in seconds. No default

CredentialECKey

Defined in fuchsia.auth/auth_provider.fidl

Stores Elliptic Curve public key parameters of the credential key.

NameTypeDescriptionDefault
curve string Supported elliptic curve value used in JWT attestation. Refer to Section 6.2.1.1 of RFC7518 for the canonical list of supported elliptic curves. For example:(P-256,P-384,P-521) No default
key_x_val string Value of x of the generated EC key No default
key_y_val string Value of y of the generated EC key No default
fingerprint_sha_256 string Base64 encoded SHA256 hash of the EC public key No default

AttestationJWTParams

Defined in fuchsia.auth/auth_provider.fidl

Contains parameters required by the auth provider component to build attestation JWTs.

NameTypeDescriptionDefault
credential_eckey CredentialECKey Contains the ephemeral Elliptic curve credential public key which will be bound to the newly generated refresh token grant. No default
certificate_chain vector<string> The full chain of certificates from the device attestation certificate to the root certificate that was registered on the OAuth client id. Each string should be base64-encoded DER PKIX certificate value. No default
auth_code string OAuth authorization code bound to the given user and device No default

AssertionJWTParams

Defined in fuchsia.auth/auth_provider.fidl

Contains parameters required by the auth provider to build assertion JWTs.

NameTypeDescriptionDefault
credential_eckey CredentialECKey Contains Elliptic curve credential public key which is bound to existing refresh token. No default
challenge string? An optional challenge that could be used for the next token refresh request 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

AuthState

Defined in fuchsia.auth/common.fidl

An assessment of the current presence and engagement of the human that owns a Fuchsia account, including the system's confidence in that assessment and its timeliness.

Note this struct is currently defined to enable multi-user experimentation. Substantial work is required before any realistic use cases.

NameTypeDescriptionDefault
summary AuthStateSummary A high level assessment of whether the human that owns a Fuchsia account is present and engaged. No default

AuthChangeGranularity

Defined in fuchsia.auth/common.fidl

An expression of the types of changes an auth state that should be reported over listener interfaces. By default no changes will be reported.

NameTypeDescriptionDefault
summary_changes bool If true, any changes in the `AuthStateSummary` enumeration will be reported. 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
INVALID_ARGUMENT 1
SIGNING_ERROR 2

AuthProviderStatus

Type: uint32

Defined in fuchsia.auth/auth_provider.fidl

Specifies the success/failure status from auth provider.

NameValueDescription
OK 0
BAD_REQUEST 1
BAD_RESPONSE 2
OAUTH_SERVER_ERROR 3
USER_CANCELLED 4
REAUTH_REQUIRED 5
NETWORK_ERROR 6
UNSUPPORTED_PROVIDER 7
INTERNAL_ERROR 8
UNKNOWN_ERROR 9

TokenType

Type: uint32

Defined in fuchsia.auth/auth_provider.fidl

The type of token returned.

NameValueDescription
ACCESS_TOKEN 0
ID_TOKEN 1

AuthStateSummary

Type: uint32

Defined in fuchsia.auth/common.fidl

A high level assessment of whether the human that owns a Fuchsia account is present and engaged.

Note this enum is currently defined to enable multi-user experimentation. Substantial work is required before any realistic use cases.

NameValueDescription
UNKNOWN 0
TEST_PRESENT 10000
TEST_ABSENT 10001

Status

Type: uint32

Defined in fuchsia.auth/token_manager.fidl

Specifies the success/failure status of TokenManager calls.

NameValueDescription
OK 0
AUTH_PROVIDER_SERVICE_UNAVAILABLE 1
AUTH_PROVIDER_SERVER_ERROR 2
INTERNAL_ERROR 3
INVALID_AUTH_CONTEXT 4
INVALID_REQUEST 5
USER_NOT_FOUND 6
IO_ERROR 7
UNKNOWN_ERROR 8
REAUTH_REQUIRED 9
USER_CANCELLED 10
NETWORK_ERROR 11