Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 70 ยท Identity and access management

SAML, Web Identity and Federation with IAM

Understand AWS identity federation: the SAML 2.0 sign-in flow, trust with an identity provider, role mapping, web identity and OIDC, IAM Identity Center and Cognito identity pools.

A company with 500 employees already has a place where people sign in: Microsoft Entra ID, Okta, Google Workspace, an internal directory. Creating 500 separate IAM users, each with its own password and access keys, would mean two sets of accounts, two offboarding processes and a lot of forgotten credentials.

Federation avoids this. AWS trusts your existing identity system. People sign in there, and the system tells AWS who they are. AWS then gives them temporary credentials for an IAM role. No IAM user is created, and when the person leaves the company and is disabled in the directory, their AWS access ends too.

This lesson explains the three main flavors: SAML 2.0 for company users, web identity / OIDC for users of apps and for machines such as CI pipelines, and Cognito identity pools for app users. It also shows the modern default for workforce access, IAM Identity Center.

Federation needs a real identity provider and AWS account, so it cannot run on this site. The JSON, XML and CLI snippets are real and read-only. The Python programs are stand-ins that check an assertion the way AWS does, in simplified form.

The vocabulary

  • Identity provider (IdP): the system that authenticates users and vouches for them. Examples: Okta, Entra ID, ADFS, Google.
  • Service provider (SP): the application that trusts the IdP. Here the SP is AWS.
  • Assertion: the signed statement the IdP sends, saying "this is [email protected], she belongs to these groups".
  • Trust: configured in advance by exchanging the IdP's public certificate and metadata with AWS, so AWS can verify signatures.
  • Role: the set of permissions the federated user receives. See IAM policies.

The SAML 2.0 flow

SAML (Security Assertion Markup Language) is an XML standard for single sign-on. The usual sequence is "IdP-initiated": the user starts at the company's portal.

sequenceDiagram
    participant U as Alice (browser)
    participant I as Identity provider
    participant S as AWS sign-in
    participant T as AWS STS
    U->>I: 1. Log in to the company portal (MFA)
    I-->>U: 2. Signed SAML assertion (XML)
    U->>S: 3. POST assertion to signin.aws.amazon.com/saml
    S->>T: 4. AssumeRoleWithSAML
    T-->>S: 5. Temporary credentials
    S-->>U: 6. Redirect to the AWS console

Alice never has an AWS password. Her IdP login produces an assertion, and STS exchanges it for temporary credentials.

What is inside the assertion matters most. Besides the user's identity, AWS expects these attributes:

  • https://aws.amazon.com/SAML/Attributes/Role: one or more pairs of role ARN,IdP ARN that the user may assume.
  • https://aws.amazon.com/SAML/Attributes/RoleSessionName: a name, usually the email address, that shows up in CloudTrail so you can tell who did what.
  • Optionally SessionDuration (up to 12 hours) and session tags.

Setting it up in AWS

There are two IAM objects.

1. A SAML identity provider. You download the metadata XML from your IdP and upload it. This tells AWS the IdP's name, sign-in endpoint and signing certificate (read-only):

Terminal
aws iam create-saml-provider \
  --name CorpIdP \
  --saml-metadata-document file://idp-metadata.xml

2. One or more roles with a trust policy that lets that provider assume them, if the assertion's audience is the AWS sign-in endpoint:

JSON
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Federated": "arn:aws:iam::123456789012:saml-provider/CorpIdP" },
    "Action": "sts:AssumeRoleWithSAML",
    "Condition": {
      "StringEquals": { "SAML:aud": "https://signin.aws.amazon.com/saml" }
    }
  }]
}

Finally, you configure the IdP with AWS as an application, and map your groups to roles: members of aws-admins get the Admin role, members of aws-readonly get ReadOnly. A person in several groups sees a role picker after signing in.

The trust policy is a resource policy on the role, so evaluation follows the normal rules: the role's permission policy decides what the federated user can do, and a permission boundary or SCP can narrow it further.

What AWS checks

When STS receives the assertion it verifies, among other things:

  1. The XML signature was made by the certificate in your uploaded metadata.
  2. The audience is https://signin.aws.amazon.com/saml.
  3. The assertion has not expired (NotBefore and NotOnOrAfter), and the recipient is correct.
  4. The role requested appears in the assertion's Role attribute and its trust policy allows this provider.

The stand-in below checks the last three on a Python dictionary. It cannot verify real XML signatures, so the signature is a simple flag.

Python Validating a SAML assertion

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Mapping groups to roles

Role mapping is the design decision you spend time on. The IdP keeps the groups, and AWS keeps the roles. A short rule works: one group per role per account, named so that the pairing is obvious.

Python From IdP groups to AWS roles

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

When Carol changes departments, only the IdP changes. When Alice is deactivated there, her next sign-in fails, and her current session expires within the session duration.

For people, AWS recommends IAM Identity Center (the successor to AWS SSO) over wiring SAML into each account yourself. It sits in your AWS Organization, connects to your IdP (or has its own user directory), and lets you assign permission sets to users and groups across many accounts. Users sign in at one portal, pick an account and role, and use the console or the CLI (aws sso login) with short-lived credentials. Under the hood it is federation too, only managed centrally. Choose raw IAM SAML providers when you have a single account, special requirements, or a tool that needs a direct SAML trust.

Web identity and OIDC

OpenID Connect (OIDC) is a newer standard built on OAuth 2.0 and JSON. Instead of an XML assertion, the IdP issues a signed JSON Web Token (JWT). IAM can trust an OIDC provider (Google, Login with Amazon, GitHub, your own) and a caller exchanges its token with sts:AssumeRoleWithWebIdentity for temporary credentials.

You already met this idea twice: GitHub Actions deploys to AWS without stored access keys by presenting its OIDC token (see the containers CI/CD project), and Kubernetes pods get roles through IRSA, as in EKS. A trust policy for GitHub looks like this (read-only):

JSON
{
  "Effect": "Allow",
  "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com" },
  "Action": "sts:AssumeRoleWithWebIdentity",
  "Condition": {
    "StringEquals": { "token.actions.githubusercontent.com:aud": "sts.amazonaws.com" },
    "StringLike": { "token.actions.githubusercontent.com:sub": "repo:my-org/my-repo:ref:refs/heads/main" }
  }
}

The sub condition is crucial: without it, any repository on GitHub could assume your role.

Cognito: federation for app users

If your customers sign in to your own mobile app or website, use Amazon Cognito, which has two parts:

  • A user pool is a user directory with sign-up, sign-in, MFA and social or SAML/OIDC login. It issues JWTs, which API Gateway can validate (see API Gateway).
  • An identity pool (federated identities) exchanges a login from a user pool, a social provider or even a guest session for temporary AWS credentials, scoped by IAM roles for authenticated and unauthenticated users. A mobile app can then upload straight to its user's S3 folder without any server in between.

SAML or OIDC?

SAML 2.0 OIDC / OAuth 2.0
Token XML assertion JSON Web Token
Typical use Enterprise single sign-on to web apps and the AWS console Modern apps, APIs, mobile, CI systems
AWS call AssumeRoleWithSAML AssumeRoleWithWebIdentity
Age 2005, very common in companies 2014, simpler for developers

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What do federated users receive when AWS accepts a valid SAML assertion?

    STS exchanges the assertion for short-lived credentials for a role. No IAM user is created.
  2. 2. Which API call is used for SAML federation?

    AssumeRoleWithSAML accepts the signed assertion and returns temporary credentials. For OIDC tokens the call is AssumeRoleWithWebIdentity.
  3. 3. What must the trust policy of a role for SAML federation name as the Principal?

    The Federated principal is the ARN of the SAML provider you created from your IdP's metadata.
  4. 4. Why is the sub condition important in a GitHub Actions OIDC trust policy?

    Without a sub condition, tokens issued to any repository could pass the trust policy.
  5. 5. What does a Cognito identity pool provide?

    User pools authenticate users and issue tokens. Identity pools exchange those logins for AWS credentials.

Summary

  • Federation lets AWS trust an existing identity provider, so people use one set of credentials and AWS issues temporary role credentials.
  • In SAML, the IdP signs an assertion, the browser posts it to the AWS sign-in endpoint, and STS runs AssumeRoleWithSAML. You create a SAML provider from IdP metadata and roles that trust it.
  • Map IdP groups to roles, and use the role session name for traceability.
  • IAM Identity Center is the recommended way to manage workforce access across accounts.
  • OIDC uses JWTs with AssumeRoleWithWebIdentity, and is how CI systems and Kubernetes pods get credentials. Always restrict the subject.
  • Cognito user pools authenticate app users, and identity pools exchange logins for AWS credentials.

Next: IAM Best Practices