Server Authentication

This feature requires sfp-pro with sfp-server

sfp-server provides centralized authentication management for teams. This page explains how to authenticate with sfp-server itself, which is separate from authenticating with Salesforce orgs.

Authentication Overview

sfp-server uses a two-layer authentication model:

┌─────────────────────────────────────────────────────────────────┐
│                    Authentication Layers                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Layer 1: Server Authentication                                │
│   ─────────────────────────────────                             │
│   You ───> sfp-server                                           │
│   Methods: OAuth (GitHub/SAML), Admin login, Impersonation      │
│   Result: Server access token (stored locally)                  │
│                                                                 │
│   Layer 2: Salesforce Authentication                            │
│   ──────────────────────────────────                            │
│   sfp-server ───> Salesforce Orgs                               │
│   Methods: Registered org credentials, JIT authentication       │
│   Result: Access to Salesforce APIs via server                  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Complete Authentication Flow

Here's the step-by-step flow when a user authenticates to sfp-server and accesses an environment:

┌─────────────────────────────────────────────────────────────────────────────┐
│                    Complete Authentication Flow                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   Step 1: CLI Login to sfp-server                                            │
│   ────────────────────────────────                                           │
│                                                                              │
│   $ sfp server auth login --email [email protected] --provider github         │
│                                                                              │
│   ┌──────────┐     ┌──────────────┐     ┌─────────────┐     ┌─────────────┐ │
│   │   CLI    │────>│ Local Server │────>│   Browser   │────>│   GitHub    │ │
│   │          │     │ (port 54329) │     │             │     │   OAuth     │ │
│   └──────────┘     └──────────────┘     └─────────────┘     └─────────────┘ │
│        │                  │                    │                    │        │
│        │                  │<───────────────────┴────────────────────┘        │
│        │                  │         OAuth callback with token                │
│        │<─────────────────┘                                                  │
│        │           Token stored in system keychain                           │
│        │                                                                     │
│   ✅ Token stored securely in OS keychain (via keytar)                       │
│                                                                              │
│   Step 2: Access Environment                                                 │
│   ──────────────────────────                                                 │
│                                                                              │
│   $ sfp server environment get --name UAT --repository myorg/app \           │
│       --auth-type accessToken --authenticate                                 │
│                                                                              │
│   ┌──────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐  │
│   │   CLI    │────>│  Keychain   │────>│ sfp-server  │────>│  Supabase   │  │
│   │          │     │ (get token) │     │   API       │     │  (decrypt)  │  │
│   └──────────┘     └─────────────┘     └─────────────┘     └─────────────┘  │
│        │                                     │                    │          │
│        │                                     │<───────────────────┘          │
│        │                                     │     Decrypted credentials     │
│        │<────────────────────────────────────┘                               │
│        │           Salesforce credentials returned                           │
│        │                                                                     │
│   ┌──────────┐     ┌─────────────┐                                          │
│   │   CLI    │────>│  Salesforce │  Local authentication created             │
│   │          │     │   CLI       │  (alias: "UAT")                           │
│   └──────────┘     └─────────────┘                                          │
│                                                                              │
│   ✅ Org authenticated locally - ready for sfp commands                      │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Step-by-Step Walkthrough

1. Initial Server Authentication

# First time: Login to sfp-server
sfp server auth login --email [email protected] --provider github

What happens:

CLI starts a local HTTP server on port 54329
Opens your browser to GitHub OAuth authorization page
You authorize the sfp application on GitHub
GitHub redirects back to localhost:54329/callback
CLI receives the OAuth token from GitHub via Supabase
Token is stored securely in your OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service)

2. Verify Authentication Status

# Check your current auth status
sfp server auth display

Output:

┌──────────────────────────────────────────────────────────────────┐
│                    Server Authentication Status                   │
├──────────────────────────────────────────────────────────────────┤
│ Email:      [email protected]                                     │
│ Status:     active                                               │
│ Auth Type:  oauth                                                │
│ Expires In: 23h 45m                                              │
│ Server:     https://sfp.mycompany.com                            │
└──────────────────────────────────────────────────────────────────┘

3. Access an Environment

# Get environment and authenticate to the Salesforce org
sfp server environment get \
  --name UAT \
  --repository myorg/salesforce-app \
  --auth-type accessToken \
  --authenticate

What happens:

CLI retrieves your server token from the OS keychain
Sends request to sfp-server API with your token
Server verifies your identity and role permissions
Server decrypts the stored Salesforce credentials
Returns credentials to CLI (accessToken or sfdxAuthUrl based on --auth-type)
CLI creates local Salesforce authentication with alias "UAT"

4. Use the Authenticated Org

# Now you can use sfp commands with the authenticated org
sfp install --targetorg UAT --artifactdir ./artifacts

# Or use sf commands
sf project deploy start --source-dir force-app --target-org UAT

Token Storage Details

sfp stores authentication tokens securely using the operating system's native credential storage:

Storage Location

Service Name

macOS

Keychain Access

sfp-pro

Windows

Credential Manager

sfp-pro

Linux

Secret Service (libsecret)

sfp-pro

The token key format is: supabase-token-{email}

Authentication Lifecycle

┌─────────────────────────────────────────────────────────────────-┐
│                    Token Lifecycle                               │
├─────────────────────────────────────────────────────────────────-┤
│                                                                  │
│   Login                   Active                                 │
│   ──────                  ──────                                 │
│                                                                  │
│   sfp server    ───>    Token valid                              │
│   auth login            for ~1 hour                              │
│        │                     │                                   │
│        │                     │                                   │
│        ▼                     ▼                                   │
│   ┌─────────┐          ┌─────────┐                               │
│   │ Keychain│          │Commands │                               │
│   │ stored  │          │ work    │                               │
│   └─────────┘          └─────────┘                               │
│                                                                  │
│   Expired                Clear                                   │
│   ───────                ─────                                   │
│                                                                  │
│   Token invalid  ───>   sfp server auth clear                    │
│   Must re-login         Removes all stored tokens                │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Server Authentication Methods

OAuth (GitHub)

The most common method for team members. Uses GitHub for identity verification.

sfp server auth login --provider github

This will:

Open a browser window to GitHub
Authenticate with your GitHub account
Store the server token locally

OAuth (SAML)

For organizations using SAML-based SSO:

sfp server auth login --provider saml --sso-domain mycompany.okta.com

For server administrators, username/password authentication:

sfp server auth login --admin --email [email protected]

You'll be prompted for the password, or provide it via file:

sfp server auth login --admin --email [email protected] --password-file ./password.txt

Impersonation (Advanced)

For administrative tasks requiring user impersonation. Requires the SUPABASE_JWT_SECRET environment variable:

export SUPABASE_JWT_SECRET=your-jwt-secret
sfp server auth login --impersonate --email [email protected]

Authentication Storage

Server credentials are stored locally and used for subsequent commands:

# View current auth status
sfp server auth display

# List stored credentials
sfp server auth list

# Clear stored credentials
sfp server auth clear

Token Location

Tokens are stored in the sfp configuration directory:

macOS/Linux: ~/.sfp/
Windows: %USERPROFILE%\.sfp\

Environment Variables

For CI/CD pipelines, use environment variables instead of interactive login:

# Server URL
export SFP_SERVER_URL=https://sfp.mycompany.com

# Server token (from service account or application token)
export SFP_SERVER_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

With these set, sfp commands automatically authenticate with the server:

# No manual login needed
sfp server environment list

Application Tokens

For CI/CD and automation, application tokens provide secure, non-interactive authentication.

Creating an Application Token

# Create a new application token
sfp server token create --name ci-pipeline --expiry 90d

Output:

Application Token Created:
Name: ci-pipeline
Token: sfp_at_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Expires: 2024-05-15

Store this token securely - it won't be shown again!

Using Application Tokens

# Set as environment variable
export SFP_SERVER_TOKEN=sfp_at_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Or pass directly
sfp server environment list --token sfp_at_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Managing Application Tokens

# List tokens
sfp server token list

# Revoke a token
sfp server token revoke --name ci-pipeline

Role-Based Access

Server authentication grants different capabilities based on user roles:

Role

Capabilities

Member

View environments, fetch orgs (no credentials)

Owner

Full access including credentials, org registration

Application

API access for automation

Credential Access

Only certain roles can retrieve Salesforce credentials:

# This works for owners and applications
sfp server environment get \
  --name uat \
  --repository myorg/myrepo \
  --auth-type accessToken \
  --authenticate

# Members can view environment info but not retrieve auth credentials

CI/CD Integration

GitHub Actions

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      SFP_SERVER_URL: ${{ secrets.SFP_SERVER_URL }}
      SFP_SERVER_TOKEN: ${{ secrets.SFP_SERVER_TOKEN }}
    steps:
      - name: Get Environment
        run: |
          sfp server environment get \
            --name production \
            --repository ${{ github.repository }} \
            --auth-type accessToken \
            --authenticate

      - name: Deploy
        run: |
          sfp install --targetorg production --artifactdir ./artifacts

Azure DevOps

variables:
  SFP_SERVER_URL: $(SFP_SERVER_URL)
  SFP_SERVER_TOKEN: $(SFP_SERVER_TOKEN)

steps:
  - script: |
      sfp server environment get \
        --name production \
        --repository $(Build.Repository.Name) \
        --auth-type accessToken \
        --authenticate
    displayName: 'Authenticate Environment'

Global Auth Mode

sfp-server can be configured for global authentication, routing users to their appropriate tenant:

sfp server auth login --global-auth

This is useful for multi-tenant deployments where a single authentication endpoint serves multiple organizations.

Session Management

Session Timeout

Server sessions have configurable timeouts. Re-authenticate when expired:

# Check if session is valid
sfp server auth display

# Re-authenticate if needed
sfp server auth login --provider github

Multiple Servers

If working with multiple sfp-server instances:

# Authenticate to different servers
SFP_SERVER_URL=https://dev.sfp.company.com sfp server auth login
SFP_SERVER_URL=https://prod.sfp.company.com sfp server auth login

Troubleshooting

"Authentication failed"

# Clear existing credentials and re-authenticate
sfp server auth clear
sfp server auth login --provider github

"Token expired"

# Re-authenticate
sfp server auth login

# Or create a new application token
sfp server token create --name new-token

"Unauthorized"

Verify your role has the required permissions
Check if the application token is still valid
Ensure SFP_SERVER_URL is correct

"Cannot connect to server"

# Verify server is running
sfp server health

# Check server URL
echo $SFP_SERVER_URL

Org Registration - Register Salesforce orgs with server
Environments - Environment management
Accessing Environments - Practical examples
Application Tokens - CLI reference

Last updated 2 months ago

Good afternoon

hashtagAuthentication Overview

hashtagComplete Authentication Flow

hashtagStep-by-Step Walkthrough

hashtag1. Initial Server Authentication

hashtag2. Verify Authentication Status

hashtag3. Access an Environment

hashtag4. Use the Authenticated Org

hashtagToken Storage Details

hashtagAuthentication Lifecycle

hashtagServer Authentication Methods

hashtagOAuth (GitHub)

hashtagOAuth (SAML)

hashtagAdmin Login

hashtagImpersonation (Advanced)

hashtagAuthentication Storage

hashtagToken Location

hashtagEnvironment Variables

hashtagApplication Tokens

hashtagCreating an Application Token

hashtagUsing Application Tokens

hashtagManaging Application Tokens

hashtagRole-Based Access

hashtagCredential Access

hashtagCI/CD Integration

hashtagGitHub Actions

hashtagAzure DevOps

hashtagGlobal Auth Mode

hashtagSession Management

hashtagSession Timeout

hashtagMultiple Servers

hashtagTroubleshooting

hashtag"Authentication failed"

hashtag"Token expired"

hashtag"Unauthorized"

hashtag"Cannot connect to server"

hashtagRelated Topics

Authentication Overview

Complete Authentication Flow

Step-by-Step Walkthrough

1. Initial Server Authentication

2. Verify Authentication Status

3. Access an Environment

4. Use the Authenticated Org

Token Storage Details

Authentication Lifecycle

Server Authentication Methods

OAuth (GitHub)

OAuth (SAML)

Admin Login

Impersonation (Advanced)

Authentication Storage

Token Location

Environment Variables

Application Tokens

Creating an Application Token

Using Application Tokens

Managing Application Tokens

Role-Based Access

Credential Access

CI/CD Integration

GitHub Actions

Azure DevOps

Global Auth Mode

Session Management

Session Timeout

Multiple Servers

Troubleshooting

"Authentication failed"

"Token expired"

"Unauthorized"

"Cannot connect to server"

Related Topics