public/lib/auth/fidl/token_manager.fidl

// Copyright 2017 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module auth;

import "lib/auth/fidl/auth_provider.fidl";

// Specifies the success/failure status.
enum Status {
  OK = 0,
  AUTH_PROVIDER_SERVICE_UNAVAILABLE,
  AUTH_PROVIDER_SERVER_ERROR,
  INTERNAL_ERROR,
  INVALID_AUTH_CONTEXT,
  INVALID_USER_ID,
  USER_NOT_FOUND,
  INTERNAL_CACHE_ERROR,
  UNKNOWN_ERROR = -1,
};

// User attributes returned to callers on authorizing a new user at any auth
// provider. These attributes are generated by calling into auth provider's
// user profile apis.
struct UserProfileInfo {
  // The name that is displayed on the device shell while logging in. Display
  // name is fetched from user profile attributes as configured by the user at
  // the given identity provider.
  string? display_name;

  // User's profile url that is used by the device shell while logging in.
  // Profile url is fetched from user profile attributes as configured by the
  // user at the given identity provider.
  string? url;

  // User's profile image url that is used by the device shell while logging in.
  // Profile image url is fetched from user profile attributes as configured by
  // the user at the given identity provider.
  string? image_url;
};

// Type of external OAuth identity providers. An identity provider authenticates
// and authorizes users for accessing their services.
//
// It also provides unique identifiers for users to interact with the system
// and may provide information about the user that is known to the provider.
enum AuthProviderType {
  // An identity provider that's used for development and testing.
  DEV,

  // Uses Google as the identity provider. Doing this requires a working
  // network connection and a web view.
  GOOGLE,
};

// Stores configuration parameters required to connect to available
// |AuthProvider|s. It is used by TokenManager to instantiate all auth providers
// during startup.
struct AuthProviderConfig {
  // Unique value to identify the external identity provider.
  AuthProviderType auth_provider_type;

  // Url of AuthProvider
  string? url;

  // Optional parameters specified during AuthProvider startup
  array<string>? params;
};

// TokenManagerFactory creates an OAuth Token Manager for a particular user and
// the specified auth providers as defined by |auth_provider.fidl|.
[ServiceName="auth::TokenManagerFactory"]
interface TokenManagerFactory {
  // Creates a Token Manager scoped for the specified user |user_id| and is
  // initialized with a list of supported |auth_providers| to mint tokens.
  // Unique |user_id| is used as the primary key in Token Manager's data store
  // and cache where all tokens are stored.
  //
  // TODO: AuthproviderConfig should support new custom auth providers added by
  // third party developers.
  //
  // TODO: Support multiple users for a single auth provider.
  GetTokenManager@0(string user_id,
      array<AuthProviderConfig> auth_provider_configs,
      TokenManager& token_manager);
};

// This interface provides oauth tokens for different auth providers.
//
// TokenManager interface will be typically used by upper layers such as device
// runner / user runner (specifically Authorize() and DeleteAllTokens()), and
// the remaining methods that mints short lived tokens will be used by Agents /
// Modules.
//
// TODO: In the future, this interface might be split in two in garnet to
// align with the requirements from the upper layers.
interface TokenManager {
  // The authorization server specified by |auth_provider_type| authenticates and
  // authorizes the given user to its backend services and resources. This
  // involves starting the OAuth handshake with the Identity Provider where user
  // grants consent to use their data by the Token Manager service. Consent flow
  // is displayed using web_view on top of the |auth_ui_context| view provided
  // by the caller.
  //
  // After user has been successfully provisioned, Auth Provider returns a
  // persistent credential to Fuchsia Token Manager service. Token Manager
  // stores this credential in its secure data store and is later used for
  // exchanging other short lived tokens. The long lived persistent credential
  // is stored on disk and persists across reboots.
  //
  // If the operation is successful, an OK status is returned along with user
  // profile information in |user_profile_info| such as user's email,
  // image_url, profile_url, first and last names as configured on the auth
  // provider backend systems.
  Authorize@0(AuthProviderType auth_provider_type,
      AuthenticationUIContext? auth_ui_context) =>
      (Status status, UserProfileInfo? user_profile_info);

  // Gets a downscoped access token from the specified |auth_provider_type| for
  // the given client app and scopes. Each client application is uniquely
  // identified by an OAuth client_id |app_client_id| pre-registered at Auth
  // Provider.
  //
  // Access token is returned from cache if not expired, otherwise user's
  // persistent credential is exchanged for an access token from the auth
  // provider backend server.
  GetAccessToken@1(AuthProviderType auth_provider_type, string? app_client_id,
      array<string>? app_scopes) => (Status status, string? access_token);

  // Gets a JWT Identity token from the specified |auth_provider_type| for the
  // given audience. The audience is the intended recipient of the id_token.
  //
  // Identity token is returned from cache if not expired, otherwise refreshed
  // from the auth provider backend server.
  GetIdToken@2(AuthProviderType auth_provider_type, string? audience) =>
      (Status status, string? id_token);

  // Gets the |FirebaseToken| for the given |firebase_api_key| from the specified
  // |auth_provider_type|. This api invokes firebase auth's VerifyAssertion
  // endpoint that takes an OAuth IdToken as the input.
  //
  // Firebase auth token is returned from cache if not expired, otherwise
  // refreshed from the auth provider backend server.
  GetFirebaseToken@3(AuthProviderType auth_provider_type, string firebase_api_key)
      => (Status status, FirebaseToken? firebase_token);

  // Deletes all long lived and short lived tokens generated for
  // |auth_provider_type| for the scoped user. This involves:
  //     - deleting persistent credentials stored locally on disk.
  //     - revoking credentials remotely at the auth provider.
  //     - deleting short lived tokens from the in-memory cache.
  DeleteAllTokens@4(AuthProviderType auth_provider_type) => (Status status);
};