Skip to Content
How-to guidesConnect AWS with SSO

Connect AWS with SSO

Sign in with your company AWS login, pick an account and a role, and your agents can run the aws tool right away. You paste no keys. Marshal keeps the keys fresh for as long as your AWS sign-in lasts, so spaces keep working for hours and days without you.

Before you start

Ask your AWS admin for two values:

  • SSO start URL: the address of your AWS access portal, for example https://acme.awsapps.com/start.
  • SSO region: the AWS region where IAM Identity Center is set up, for example us-east-1.

The aws package must be installed from the Marketplace. If an admin has already entered the start URL and region in the organization settings, Marshal fills them in for you and you only click Continue.

Steps

  1. In the left rail, open Connections.

  2. On the AWS card, click Connect. If you already have an AWS connection, the button says Add another.

  3. In the Connect AWS dialog, pick the Sign in with AWS SSO tab. The connection takes four steps, shown at the top of the dialog: AWS sign-in, Approve in AWS, Account and role and Review. One step is open at a time, and Back takes you to the previous one.

  4. AWS sign-in. Enter the SSO start URL and SSO region. If your admin set them, they are filled in and marked Set by your admin.

  5. If an Owner field is shown, choose who owns the connection. The default is you. Pick a team to share it with that team’s spaces.

  6. Click Continue. Marshal shows a short code.

  7. Approve in AWS. Click Open AWS sign-in, or click Copy code and open the AWS page yourself. Check that AWS shows the same code, then approve. Use your normal company login. Marshal moves to the next step by itself once you approve.

  8. Account and role. Pick the account and the role. If you have many accounts, type in the search box to find one by name or account ID. When you have only one account, or an account has only one role, Marshal picks it for you. Click Continue.

  9. Review. Marshal shows who signed in: the AWS user, the Account and the Role. For a connection owned by a team, also select This is the AWS user, account and role I expect.

  10. Optional: change Connection name. This is how you pick the connection later in a manifest.

  11. Click Save.

You have 10 minutes to approve the code. If it runs out, click Sign in again to get a new one. Nothing is saved until you click Save.

The start URL is the address of your AWS access portal, in any of the forms IAM Identity Center shows:

  • https://acme.awsapps.com/start
  • https://ssoins-1234567890abcdef.portal.us-east-1.app.aws
  • https://ssoins-1234567890abcdef.us-east-1.portal.amazonaws.com

For the two ssoins- forms, the region in the address must match the SSO region.

From the CLI

You can make the same connection from a terminal:

marshal credentials add --type aws.sso

Marshal asks for the start URL and the region, shows the code, and opens the AWS page in your browser. After you approve, pick the account and the role, check who signed in, and the connection is saved. To run it from a script, pass every answer as a flag:

marshal credentials add --type aws.sso \
  --field start_url=https://acme.awsapps.com/start --field region=us-east-1 \
  --account 123456789012 --role ReadOnly --name "AWS prod" --yes

See marshal credentials add for every flag.

What you should see

  • The AWS row under Your connections shows a green status dot and the AWS user, account and role.
  • In a new space, aws sts get-caller-identity shows the account and role you picked.
  • A space that runs for many hours keeps working. Marshal renews the keys before they expire.

Who owns the connection

You own the connection by default, and only you and the people you share it with can use it. A team-owned connection works for that team’s spaces under the same rules as any other shared credential. Every member of the team acts as the AWS user who signed in.

A deputy or a scheduled run uses the connection as its own owner, so that owner must be allowed to use it.

How long it lasts

A connection lasts as long as the AWS sign-in session. Your AWS admin sets that length in IAM Identity Center. The longest a connection lasts is 90 days, whatever the session length.

When the end is 7 days away or less, the Connections and Home pages show the end date. You also get one inbox message a day until you sign in again.

When the sign-in ends

When the AWS session ends, Marshal can no longer renew keys, and you see it in four places:

  • The connection shows Needs sign in on Connections and on Home.
  • You get a message in your inbox.
  • A new space that needs the connection is refused with a Sign in to AWS message.
  • In a running space, an aws call fails with a message that names the connection and its owner.

Keys that Marshal already gave out keep working until they expire, which is about an hour.

To fix it:

  1. Open Connections and find the AWS row marked Needs sign in.
  2. Click Reconnect.
  3. Approve the code on the AWS page, then confirm and click Save.

Reconnecting updates the same connection. Spaces that are running pick up the new sign-in on their next aws call, with no restart. If a different AWS user, account or role signs in, Marshal shows the current and the new values side by side, and you select This is the AWS user, account and role I expect. to confirm the change.

A short AWS outage does not change the connection. Marshal shows Needs sign in only when AWS says the sign-in has ended.

What your cell must reach

Your Marshal cell connects out over HTTPS to three AWS addresses for your SSO region:

  • oidc.<region>.amazonaws.com for the sign-in and renewals
  • portal.sso.<region>.amazonaws.com for the list of accounts and roles, and for role keys
  • sts.<region>.amazonaws.com for the name of the AWS user who signed in

Direct access or the standard proxy settings both work. If the cell cannot reach AWS, the dialog tells you.

Keys and session tokens still work

The Access key + secret and Temporary session token (STS) methods stay on the same dialog and work as before. Existing connections made with them need no change.

Block key printing

The aws package includes an optional guardrail that blocks aws configure export-credentials, the command that prints the keys. Turn it on in the tool guardrails of your manifest, like the other aws guardrails.

Connect GitHubSet package settings