• Documentation
  • Pricing
© 2026 Serverless, Inc. All rights reserved.

Framework

  • Overview
  • Documentation
  • Plugins360
  • Pricing

Learn

  • Blog
  • GuidesUpdated
  • Examples240
  • Courses

Resources

  • Support
  • Security
  • Trust Center
  • Status

Community

  • Slack
  • GitHub47k
  • Forum
  • Meetups

Company

  • About
  • Careers
  • Contact
  • Partners

Legal

  • Terms of Service
  • Privacy Policy
  • Trademark
  • DMCA
Serverless Framework Logo

Serverless Framework

Intro
SetupUpgrading To V4ConceptsTutorialAWS CredentialsLicense Keys
DeployingPackagingBuildingTestingDev ModeServicesFunctions
OverviewHTTP (API Gateway v2)REST (API Gateway v1)ActiveMQApplication Load BalancerAlexa SkillAlexa Smart HomeCloudWatch EventCloudWatch LogCloudFrontCognito User PoolEventBridge EventIoTIoT Fleet ProvisioningKafkaKinesis & DynamoDBMSKRabbitMQS3ScheduleSNSSQSWebsocket
LayersManaged InstancesWeb Apps (Lambda Web Functions)Sandboxes (Lambda MicroVMs)MCP ServersAlertsVersion PruningDomainsIAM Function PermissionsParameters
OverviewSelf-reference serverless.ymlServerless CoreEnvironment VariablesCLI OptionsExternal YAML/JSON FilesJavascript propertiesGitDoppler
OverviewS3 ObjectsSSM Parameter Store & Secrets ManagerCloudFormation Stack Outputs
OverviewVaultTerraform State Output
ResourcesComposing ServicesDeployment BucketStateAgent SkillsPython support
OverviewRuntimeGatewayMemoryBrowserCode InterpreterDev Mode
API Gateway Proxy
OverviewGeneral ConfigurationAuthenticationAPI KeysData SourcesResolversPipeline FunctionsSubstitutionsCachingDelta SyncCustom DomainWAFCLI Commands
Deploying SAM/CFN TemplatesWorkflow Tips
OverviewCreating PluginsCLI OutputCustom CommandsCustom VariablesExtending the Configuration schemaExtending and overriding configuration
OverviewDashboardAxiom
Overviewagent docsagent inspectagent setupagent skills installagent skills list / readdeploydeploy functiondeploy listdevdiffinfoinvokeinvoke localloginlogin awslogin aws ssologsmetricspackageplugin installplugin uninstallprintprunereconcileremoverollbackrollback functionusage
OverviewConcepts
OverviewMetricsTracesTroubleshoot
OverviewNode.jsPython
OutputsProviders
OverviewBranch DeploymentsPreview DeploymentsCustom ScriptsTestingPrivate PackagesNotificationsMono ReposDeploy in your own CI/CDBest PracticesTroubleshootingFAQ
OverviewSetupToolsAWS Integration
Serverless.yml Reference
Examples and TutorialsConfiguration Validation
  1. CLI Reference
  2. Login AWS Sso

serverless login aws sso

serverless login aws sso signs you in to AWS IAM Identity Center (AWS SSO) in the browser for an SSO profile that is already in ~/.aws/config, and caches the token where the AWS CLI and SDKs read it, as aws sso login does. Use it when your organization gives you AWS access through IAM Identity Center; use serverless login aws to sign in with AWS Console credentials instead, and serverless login for the Serverless Framework Dashboard.

serverless login aws sso --aws-profile my-dev

The command needs a terminal and a browser on the same machine, and works inside or outside a service directory. It doesn't need a Dashboard sign-in.

Options

serverless login aws sso accepts these options:

OptionAliasValueDefaultRequiredDescription
--aws-profilestringdefaultNoAWS profile whose SSO settings to read.
--sso-sessionstringThe profile's sso_sessionNo[sso-session] section to sign in to; takes precedence over the profile's setting.

The command also accepts --verbose, --debug and --help (-h).

SSO configuration that serverless login aws sso reads

serverless login aws sso reads ~/.aws/config, or the file AWS_CONFIG_FILE names, and doesn't change it. Create the configuration once with the AWS CLI:

aws configure sso

That command writes an [sso-session] section and a profile that uses it:

[sso-session my-company]
sso_start_url = https://my-company.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access

[profile my-dev]
sso_session = my-company
sso_account_id = 123456789012
sso_role_name = DeveloperAccess
region = us-west-2

From the [sso-session] section the command reads sso_start_url, sso_region and sso_registration_scopes (comma-separated, default sso:account:access). The AWS SDK then uses the profile's sso_account_id and sso_role_name to get credentials for a deploy.

A profile in the legacy format, without an [sso-session] section, works too; the command reads sso_start_url and sso_region from the profile and uses the sso:account:access scope:

[profile my-dev]
sso_start_url = https://my-company.awsapps.com/start
sso_region = us-east-1
sso_account_id = 123456789012
sso_role_name = DeveloperAccess
region = us-west-2

Files serverless login aws sso writes

The command writes two files in ~/.aws/sso/cache/, both readable only by your user and named as the AWS CLI names them:

  • The client registration: the OIDC client the command registers with IAM Identity Center. Later runs reuse it until it expires.
  • The token: the SSO access token, its expiry and the refresh token.

The AWS CLI and SDKs read the same cache, so a token from aws sso login works for the Framework and a token from serverless login aws sso works for the AWS CLI, until it expires. The command doesn't write ~/.aws/config, ~/.aws/credentials or the Framework's ~/.serverlessrc.

Use the profile with the Framework

Select the SSO profile as any other profile: with --aws-profile, provider.profile in serverless.yml, or AWS_PROFILE. See which credentials a deploy uses.

serverless deploy --aws-profile my-dev

When the token expires, commands stop with an error that names serverless login aws sso; run it again. Re-running the command at any time is safe: it replaces the cached token.

Errors from serverless login aws sso

  • The `login aws sso` command requires an interactive environment (TTY) to authenticate.: the command ran without a terminal (CI, a pipe, an AI agent). Run it in a terminal.
  • No SSO configuration found. Please run 'aws configure sso' first to set up SSO for profile "...". (or for session "..." when an SSO session is used): the profile has no sso_session or sso_start_url, or the [sso-session] section has no sso_start_url. Run aws configure sso, or pass the right --aws-profile or --sso-session.
  • Missing sso_region in SSO configuration. Please run 'aws configure sso' to complete setup.: add sso_region to the [sso-session] section or the legacy profile.
  • Login timed out. Please try again.: the browser sign-in wasn't completed within 5 minutes.

Output of serverless login aws sso

The command opens the IAM Identity Center authorization page in your default browser (with --verbose it also prints the URL; if the browser can't be opened, it prints the URL to copy). On success it prints:

✔ Successfully logged in to AWS SSO (session: my-company).

Examples

Sign in for the default profile

serverless login aws sso

Sign in to a named SSO session

serverless login aws sso --sso-session my-company

Related commands

  • serverless login aws signs in with AWS Console credentials.
  • serverless login signs in to the Serverless Framework Dashboard.
  • Configuring IAM Identity Center authentication with the AWS CLI explains the SSO settings.
Edit this page
Prev login awsNextlogs

Contents

  • serverless login aws sso
  • Options
  • SSO configuration that serverless login aws sso reads
  • Files serverless login aws sso writes
  • Use the profile with the Framework
  • Errors from serverless login aws sso
  • Output of serverless login aws sso
  • Examples
  • Sign in for the default profile
  • Sign in to a named SSO session
  • Related commands

Related

GuidesPluginsExamplesSlack CommunitySupport