8 Authenticating Application Users

Application users (app users) are the people or systems that sign in to your app and call Oracle Backend for Firebase services through the SDKs or REST APIs. This chapter explains what an app user is, how sign-in works, and how tokens and user state behave so you can design predictable Auth flows.

Happy path: Enable a sign-in method in the Console, call the SDK sign-in method in your app, and listen for Auth state changes to keep your UI in sync. For a basic example, see Getting started with authentication.

Authentication answers two questions for every request:

1. Who is the caller?
2. Is the caller signed in?

Oracle Backend for Firebase uses authentication tokens to identify the signed-in user and to keep requests tied to that user across SDK calls.

• App Users
  
• Basic Properties
  
• Sign-In Methods
  
• Authentication Flow
  
• Current User and Auth Listeners
  
• Application User Self-service
  
• Email Verification and Password Reset
  
• Auth Tokens
  
• Managing Application Users
  

8.1 App Users

An app user represents a user account that has signed up for an app in your project. Apps in the same project share a single Auth user database, so a user can sign in to multiple apps in that project with the same account.

8.2 Basic Properties

Each registered user has a fixed set of properties stored in the Auth service:

• Unique user ID
• Display name
• Email address (also the username)
• Sign-in method used during registration (for example, email/password, Google, Facebook)
• Account creation time

You cannot add arbitrary properties to the user object itself. Store app-specific data in your database and reference it by user ID.

8.3 Sign-In Methods

Oracle Backend for Firebase supports multiple sign-in methods, so you can match your app’s needs and your users’ identity provider:

• Email/password (BASIC)
• LDAP
• Social identity providers (Google, Facebook, GitHub)
• Enterprise identity providers OpenID Connect, Security Assertion Markup Language, and Oracle IAM Domains (OIDC, SAML, and Oracle IAM Domains)

Oracle Backend for Firebase integrates federated identity flows. It does not manage the identity provider login UI, so your app redirects to the provider for sign-in and returns with credentials.

For details on BASIC and LDAP, see Authentication methods: BASIC and LDAP.

8.4 Authentication Flow

This is the end-to-end flow that Oracle Backend for Firebase manages when a user signs in, providing insight into the behind-the-scenes process.

1. The user signs in through the SDK using a supported method.
2. Oracle Backend for Firebase validates the credentials.
3. The service issues an access token and a refresh token.
4. The SDK stores the tokens and attaches the access token to requests. You do not need to manage tokens directly unless you are calling the REST APIs.
5. When the access token expires, the SDK uses the refresh token to get a new access token.
6. When the user signs out, the SDK clears local state and the refresh token is invalidated.

8.5 Current User and Auth Listeners

When a user signs in, the SDK sets the current user and keeps that state based on your SDK configuration. You can keep Auth state in memory, local storage, or IndexedDB. Client SDKs provide Auth listener callbacks so your app can respond to changes in Auth state.

Listeners are notified when:

• A user signs in.
• A user signs out.
• The current user’s access token is refreshed automatically or through a forced refresh.

8.6 Application User Self-service

The client SDKs give you simple, user-facing actions you can surface in your app:

• Update profile fields such as displayName.
• Reset password.
• Verify email address.

Use these methods to build self-service flows inside your app, such as a profile page or account settings screen. It keeps users in control of their accounts and reduces the need for manual admin support.

8.7 Email Verification and Password Reset

Email verification and password reset help you build a smoother onboarding and recovery experience. These features are available for BASIC and LDAP users and require SMTP configuration.

• SMTP Configuration
  
• Email Verification
  
• Password Reset
  

8.7.1 SMTP Configuration

Before you turn the email verification and password reset features on, make sure you have access to an SMTP server. Oracle Backend for Firebase connects to your SMTP server to send emails; it does not provide one. Gather the SMTP host, port, sender email address, and credentials so you can enter them in the Console. If you do not have an SMTP server, use your organization’s mail service or a third-party SMTP provider.

Configure the SMTP server in the Console:

1. Open Authentication in the Console.
2. Enter the SMTP host, port, sender email, and credentials.
3. Save the configuration.

8.7.2 Email Verification

Email verification confirms that the user’s email address is valid. This helps you detect typos and prevents users from signing up with addresses they do not control.

How it works:

• After sign-up, Oracle Backend for Firebase generates a verification code.
• The user receives an email with a verification link.
• When the link is used, email_verified becomes true. The account remains active regardless of the verification status.

8.7.3 Password Reset

Password reset lets users recover access when they forget their password, so you do not need to handle manual resets.

How it works:

• The user requests a reset.
• Oracle Backend for Firebase generates a reset code.
• The user receives an email with a reset link.
• The user submits the code and a new password.
• The password is updated securely.

Password reset is not supported for social login users. It is supported for IDCS users.

8.8 Auth Tokens

Oracle Backend for Firebase issues tokens when users sign in, and the SDKs attach the right token to each request for you. You usually do not need to handle tokens directly unless you are calling the REST APIs or troubleshooting a sign-in issue.

You can encounter these token types:

• Oracle Backend for Firebase Auth token: The token returned after successful app-user sign-in. The scope indicates which services are allowed, such as database, auth, and storage.
• Oracle IDCS token: When Oracle Backend for Firebase uses Oracle IDCS for authentication, the SDK exchanges a valid IDCS access token for an Oracle Backend for Firebase Auth token so database and storage services can recognize the user.
• Snapshot token: A short-lived token used to establish an authenticated websocket connection for onSnapshot.

• Auth Token Example
  
• Auth Token Fields
  

8.8.1 Auth Token Example

{
  "user_displayname": "Scott Scott",
  "user_id": "68AB1C234D9FA873E083F283695E41B0",
  "email_verified": "true",
  "creation_time": "2024-07-20T10:25:36.789123Z",
  "claim": null,
  "idp_type": "BASE",
  "sub": "[e-mail]",
  "iss": "baas_onprem#68AB1C2DE7C3D871E083F283695E54A2",
  "iat": 1721462736,
  "exp": 1721466337,
  "idp_name": "UserNamePassword",
  "scope": "database auth storage",
  "aud": "68AB1C2A90EF1872E083F283695E51D3",
  "uid": "68AB1C234D9FA873E083F283695E41B0",
  "token": {
    "email": "[e-mail]",
    "email_verified": "true",
    "sub": "[e-mail]",
    "name": "Scott Scott"
  }
}

8.8.2 Auth Token Fields

• user_displayname: User display name shown in apps or UIs.
• user_id and uid: Unique user identifier.
• email_verified: Whether the email address is verified.
• creation_time: Timestamp when the account was created.
• idp_type: Identity provider type, such as BASE, LDAP, or IDCS.
• idp_name: Human-readable provider name, such as UserNamePassword, google, or facebook.
• sub: Subject identifier, often the user’s email.
• iss: Token issuer.
• iat: Issued-at timestamp (Unix epoch).
• exp: Expiration timestamp (Unix epoch).
• scope: Services the token allows, such as database.
• aud: Audience identifier.
• token: Nested object containing email, subject, and name.

8.9 Managing Application Users

Use the Console to view users and inspect provider and verification status. This is useful when you are testing sign-in flows or supporting users. If you need to disable or delete users, do so from the Console.