New command group: nextflow auth

[ewels]

This PR introduces a complete authentication system for Seqera Platform with multiple subcommands for managing authentication credentials and configuration.

CleanShot.2025-09-21.at.00.32.54.mp4

Features

New nextflow auth command with subcommands:

• nextflow auth login - Authenticate with Seqera Platform using OAuth2/PKCE flow
• nextflow auth logout - Remove authentication credentials and clear configuration
• nextflow auth status - Show current authentication status and user information
• nextflow auth config - Display current authentication configuration

Auth0 Device Flow Authentication

• Implements Auth0 device flow for secure authentication without requiring a local server
• User-friendly flow: displays a code and opens browser to Auth0 verification URL
• Automatic polling to detect when user completes authentication
• Supports multiple Seqera environments (production, staging, development)
• Personal Access Token (PAT) fallback for enterprise/custom deployments

Usage Examples

# Authenticate with Seqera Cloud (production)
nextflow auth login

# Authenticate with custom endpoint
nextflow auth login -u https://my-enterprise-seqera.com/api

# Check authentication status
nextflow auth status

# View current configuration
nextflow auth config

# Logout and clear credentials
nextflow auth logout

Technical Implementation

Core Components

• CmdAuth: Main command handler with OAuth2 flow implementation
• ColorUtil: ANSI color utility for enhanced terminal output
• Comprehensive test suite: 36 tests covering all functionality

Authentication Flow

1. Prompts for API endpoint (defaults to Seqera Cloud production)
2. For Seqera Cloud: initiates Auth0 device flow
3. Displays user code and opens browser to verification URL
4. Polls Auth0 token endpoint until user completes authentication
5. For enterprise: prompts for Personal Access Token
6. Validates credentials and fetches user information
7. Handles workspace/organization selection
8. Updates Nextflow configuration with new credentials

---

Note

Introduces a new nextflow auth CLI with OAuth2 (Auth0) and PAT flows via nf-tower plugin, adds ANSI color utility, integrates into launcher, and includes comprehensive tests.

• CLI:
  • Add CmdAuth command group with subcommands: login, logout, config, status.
  • Integrate auth into Launcher command registry.
  • Add ColorUtil for ANSI-colored terminal output.
• nf-tower Plugin:
  • Implement io.seqera.tower.plugin.cli.AuthCommandImpl (extension of CmdAuth.AuthCommand).
    • Auth0 device flow (Cloud) and PAT entry (Enterprise), token generation/deletion, config read/write, workspace selection, and status display.
  • Register new extension point and bump nextflowVersion to 25.08.0-edge in plugins/nf-tower/build.gradle.
• Tests:
  • Add tests for CmdAuth, ColorUtil, and AuthCommandImpl.
• Misc:
  • Update author email in nextflow/trace/ReportObserver.groovy.

^{Written by Cursor Bugbot for commit 00b4590. This will update automatically on new commits. Configure here.}

[netlify]

✅ Deploy Preview for nextflow-docs-staging canceled.

Name	Link
🔨 Latest commit	238e387
🔍 Latest deploy log	https://app.netlify.com/projects/nextflow-docs-staging/deploys/68e7ab474482990008538faa

[pditommaso]

Let's start refactoring this as nf-seqera plugin (in the plugins directory, same as nf-tower)

[jorgee]

I get confused a bit on how -url is managed.
In usage examples, it seems the -url is used to support login for enterprise, but inside the code it is also used to decide to use cloud dev, stage or prod.
To manage it, the code has a couple of maps with the api and Auth0 URLs, and Auth0 client Id for all environments hardcoded in the code. There is also a complex sequence to check if the URL is from platform (cloud) or enterprise and if it is enterprise then uses PAT instead of Auth0.

I think it is better to simplify it by -url is for enterprise with PAT and no url is for cloud. Moreover, instead of hardcoding all environments, keep just the production values as default and allow to test in other environments using env variables. In fact, we already have the TOWER_API_ENDPOINT, we just would need to add the ones for auth endpoint and client id.

What do you think about it?

[ewels]

@jorgee I think that we still need the logic to detect the 3 prod / stage / dev URLs for cloud - it's needed to trigger the logic to try the Auth0 flow rather than just booting people to use a PAT.

If we have that logic in the code, then I don't really see a reason to not also include the key and auth0 URL personally, it's only a handful of extra lines of code. And it'd be a swap for env vars. Given that I don't envision ever needing to test with any other auth0 URLs I'm not really sure it'd be any simpler..?

[pditommaso]

If i'm not wrong seqera_auth take over both TOWER_ACCESS_TOKEN and standard config level tower.accessToken, which is against usual config pattern in which local config override global config.

Considering this happens silently it can be very confusing.

[ewels]

@pditommaso I'm not sure I understand? This PR uses standard config, there's nothing bespoke here:

• Creates ~/.nextflow/seqera_auth.config
• Adds includeConfig 'seqera_auth.config' to ~/.nextflow/config

Nextflow then loads tower.accessToken exactly as normal. No change to how env vars are used, or Nextflow config is parsed.

Example seqera_auth.config file:

// Seqera Platform configuration
tower {
    accessToken = 'eyJ........'
    endpoint = 'https://api.cloud.stage-seqera.io'
    enabled = true
    workspaceId = '123456789012345'  // org / workspace [Full name of workspace]
}

[pditommaso]

I was missing this!

Adds includeConfig 'seqera_auth.config' to ~/.nextflow/config

[ewels]

@pditommaso thanks for the review - I believe that I have addressed all of your comments now.

I have leaned heavily into using PlatformHelper to fetch config attributes wherever they are used, so this acts as the single source of truth now.

There are two exceptions to this:

• The auth stats table also grabs config manually so that it can show where things are defined (third table column says either nextflow config or env var $TOWER_xx - useful for debugging)
• Several commands warn if an env var is found, as the recommended method is to use the Nextflow config and having both could result in confusing behaviour. These warnings grab the env var in order to tell if it's defined or not, but don't actually use its value.

Hope that makes sense and my edits are ok! 🙌🏻

[pditommaso]

Made a few comments. it would also be nice reduce the number of colors (ma

[ewels]

it would also be nice reduce the number of colors (ma

Not sure if you tested again after my changes, but I did make a start on toning the colours down a bit in 84c3584 already.

Main thing is that on my terminal, cyan is very similar to the default colour. You have the default terminal to bright green though, so the two look very different. I switched many instances of cyan out so it should look a bit better already.

I can do more to further reduce use of colour if you like. Note that NO_COLOR and the usual ANSI flags should work to totally remove colour if you want.

[pditommaso]

ok, i'll check again the colours. Do you mind to change the base branch to a non-master for a last cleanup round?

[ewels]

Changed the PR target to a new nextflow-auth branch 👍🏻 (you should also be able to push directly to my fork to keep on this PR if you want).

Saw you merged the TOWER_AUTH_DOMAIN suggestion - should probably also comparable for TOWER_AUTH_ID and document both.