Directory Services & Federation (SAML, OIDC)

The Monday Trailbase Had 400 New Coworkers

The acquisition closed on a Friday. Alpenglow Outfitters, a national outdoor-gear retailer, bought Trailbase for its trail data and its community of hikers, and by Monday morning Dana had a new org chart and a request from Alpenglow corporate IT: 400 employees need access to the Trailbase AWS environment. Warehouse analysts want the trail-popularity data, the BI team wants dashboards, and a squad of Windows administrators is planning to move Alpenglow inventory servers into one of the Trailbase accounts.

Every one of those 400 people already has an identity. It lives in Alpenglow's on-premises Microsoft Active Directory (AD), the directory server their IT team has curated for fifteen years: user accounts, group memberships, password policy, MFA, and a joiner-mover-leaver process wired straight into HR.

Dana's post-Theo reflex is to create IAM users, but she does the math and stops. Four hundred IAM users would be copies of identities that already exist somewhere else, and copies drift. When Alpenglow offboards an employee, HR disables the AD account, and no ticket in the world guarantees that somebody also remembers the twin IAM user. Duplicated identity is standing access on a delay timer.

The fix is federation: configuring AWS to trust the system that already holds the identities. An external identity provider (IdP), the software that authenticates users and vouches for them, performs the sign-in, and AWS exchanges that proof for the temporary STS credentials you met in lesson 4. Nobody creates 400 users, and when Alpenglow disables an AD account, its AWS access dies with it.

Mara Clicks a Bookmark: The SAML Flow

Within two weeks the two IT teams wire up federation, and Mara gains access to the shared analytics account without anyone creating her a second identity. Watch exactly what happens when she signs in, because the exam tests this flow step by step.

She clicks a bookmark to Alpenglow's identity portal. The portal runs ADFS (Active Directory Federation Services), Microsoft's federation server that fronts AD, and it authenticates her against the directory with her ordinary corporate password and MFA prompt. AWS never sees that password.

ADFS then builds a SAML assertion: a digitally signed XML document stating who Mara is, which IAM roles she may assume, and how long her session may last. Her browser posts the assertion to the AWS sign-in endpoint, AWS validates the signature against the SAML provider registered in IAM, and STS answers an AssumeRoleWithSAML call with temporary credentials. Her console opens about two seconds after the click, and no long-lived credential exists anywhere in the chain.

The plumbing behind Mara's two seconds takes three moves on the AWS side. First, Trailbase registers Alpenglow's IdP in IAM by uploading its metadata document, the XML file that carries the IdP signing certificate:

# Create SAML provider with metadata from your IdP
aws iam create-saml-provider \
  --name ExampleOktaProvider \
  --saml-metadata-document file://metadata.xml

Second, the roles that federated users assume need a trust policy naming that provider as the trusted party. Read it as a sentence: anyone this provider vouches for may call sts:AssumeRoleWithSAML, provided the assertion was minted for the AWS sign-in endpoint. That is what the SAML:aud (audience) condition checks.

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

Third, the IdP is configured to state which roles each user may assume, by including a role attribute in every assertion. The attribute is https://aws.amazon.com/SAML/Attributes/Role, and its value pairs a role ARN with the provider ARN, for example arn:aws:iam::123456789012:role/FederatedRole,arn:aws:iam::123456789012:saml-provider/ExampleOktaProvider. Alpenglow maps AD groups to those role values, so day-to-day access management stays where it always lived: in the directory.

The Hikers Were Federating All Along

Midway through the integration project, Theo points out something nobody had framed this way: the Trailbase mobile app has been doing federation since launch. Hikers sign in with their Google accounts, and the app has never stored a password. The protocol is different, though, and the difference is one of the exam's favorite distinctions.

OpenID Connect (OIDC) is a modern authentication protocol built on OAuth 2.0, the authorization framework that lets one application grant another limited access. Where SAML speaks signed XML through a browser, OIDC issues an ID token in JWT format (JSON Web Token, a compact signed JSON credential built for mobile apps and APIs). The application then exchanges that token for AWS credentials through sts:AssumeRoleWithWebIdentity.

The rule of thumb Dana writes on the whiteboard: SAML is for workforces that live in an enterprise directory behind an IdP, and OIDC is for consumer applications, mobile clients, and machine workloads like EKS pods. Alpenglow employees enter through SAML; Trailbase hikers enter through OIDC.

A Million Hikers Cannot Share One Role

Signing hikers in was never the whole problem. After authentication, the app needs scoped AWS access: each hiker should upload photos to their own S3 prefix and touch nobody else's. Amazon Cognito is the service built for exactly this, and it comes in two halves that the exam loves to confuse.

For Trailbase, a user pool fronts the mobile app and handles the Google sign-in along with native email accounts:

aws cognito-idp create-user-pool \
  --pool-name MyAppUserPool \
  --policies "PasswordPolicy={MinimumLength=8,RequireUppercase=true,RequireLowercase=true,RequireNumbers=true}" \
  --auto-verified-attributes email \
  --mfa-configuration OPTIONAL

An identity pool then sits behind it, trading the user pool JWT for temporary credentials:

aws cognito-identity create-identity-pool \
  --identity-pool-name MyAppIdentityPool \
  --allow-unauthenticated-identities \
  --cognito-identity-providers \
    ProviderName=cognito-idp.us-east-1.amazonaws.com/us-east-1_abc123,ClientId=1234567890abcdef

The IAM role the identity pool hands out has its own trust policy, and the two conditions in it matter. The aud claim pins the token to this specific identity pool, and amr (authentication methods reference) restricts the role to authenticated users, keeping guests on a separate, weaker role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "cognito-identity.amazonaws.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "cognito-identity.amazonaws.com:aud": "us-east-1:12345678-1234-1234-1234-123456789012"
        },
        "ForAnyValue:StringLike": {
          "cognito-identity.amazonaws.com:amr": "authenticated"
        }
      }
    }
  ]
}

The Inventory Servers Need a Domain

Federation solves humans at keyboards. Alpenglow's Windows administrators arrive with a different problem: the inventory servers they are lifting into a Trailbase account expect to live in a domain. Windows workloads want domain join, group policy, Kerberos sign-in, and LDAP (Lightweight Directory Access Protocol, the query protocol directories speak). AWS Directory Service offers three ways to provide that, and choosing among them is a guaranteed exam scenario.

Trailbase deploys Managed Microsoft AD in the shared-services account and establishes a trust relationship with the Alpenglow forest: an agreement between two directories that lets users in one authenticate to resources in the other. The inventory servers join the cloud domain, and Alpenglow admins sign in to them with the on-premises identities they have held for years. No passwords were synchronized and no accounts were duplicated.

There were two roads not taken, and the exam expects you to know why each exists.

Standing up the chosen directory is two CLI calls away. The Managed Microsoft AD deployment spans two subnets because Multi-AZ is built in:

aws ds create-microsoft-ad \
  --name corp.example.com \
  --short-name CORP \
  --password 'ComplexPassword123!' \
  --edition Standard \
  --vpc-settings VpcId=vpc-12345678,SubnetIds=subnet-11111111,subnet-22222222

Had Trailbase gone the proxy route instead, an AD Connector needs the on-premises DNS servers and a service account to bind with:

aws ds connect-directory \
  --name corp.example.com \
  --short-name CORP \
  --password 'ServiceAccountPassword!' \
  --size Small \
  --connect-settings VpcId=vpc-12345678,SubnetIds=subnet-11111111,subnet-22222222,CustomerDnsIps=10.0.0.10,10.0.0.11,CustomerUserName=svc_adconnector

Trailbase and Alpenglow, Wired Together

Six months after the acquisition, every population enters through the door built for it. Workforce access runs through IAM Identity Center, which you configured in lesson 6: it now uses the Managed Microsoft AD as its identity source, and permission sets map Alpenglow AD groups onto roles across every account in the organization. Hikers enter through Cognito, trading Google sign-ins for credentials scoped to their own photos. The inventory servers live in the cloud domain, trusted by the on-premises forest.

Priya still audits through her cross-account role. When Alpenglow's external accounting firm needed similar access, Trailbase set up direct IAM SAML federation with the firm's own IdP instead, and the partners received temporary credentials without a single IAM user being created. Two mechanisms, one principle: temporary access for people whose identities live elsewhere.

Common Pitfalls

Quick Reference

# List directories
aws ds describe-directories

# Create Microsoft AD
aws ds create-microsoft-ad --name corp.example.com --password 'Password' --edition Standard --vpc-settings VpcId=vpc-xxx,SubnetIds=subnet-xxx

# Create trust relationship
aws ds create-trust --directory-id d-xxx --remote-domain-name onprem.example.com --trust-password 'TrustPassword' --trust-direction Two-Way

# Create AD Connector
aws ds connect-directory --name corp.example.com --password 'Password' --size Small --connect-settings VpcId=vpc-xxx,SubnetIds=subnet-xxx,CustomerDnsIps=10.0.0.10

# Delete directory
aws ds delete-directory --directory-id d-xxx

# Create User Pool
aws cognito-idp create-user-pool --pool-name MyPool

# Create User Pool Client
aws cognito-idp create-user-pool-client --user-pool-id us-east-1_xxx --client-name MyAppClient

# Create Identity Pool
aws cognito-identity create-identity-pool --identity-pool-name MyIdentityPool --allow-unauthenticated-identities

# List User Pools
aws cognito-idp list-user-pools --max-results 10

# Get Identity Pool roles
aws cognito-identity get-identity-pool-roles --identity-pool-id us-east-1:xxx

# Role attribute (required)
Name: https://aws.amazon.com/SAML/Attributes/Role
Value: arn:aws:iam::ACCOUNT:role/ROLE,arn:aws:iam::ACCOUNT:saml-provider/PROVIDER

# Session duration (optional)
Name: https://aws.amazon.com/SAML/Attributes/SessionDuration
Value: 3600 (seconds, max 43200)

# Role session name (optional but recommended)
Name: https://aws.amazon.com/SAML/Attributes/RoleSessionName
Value: user@example.com

Related Services

Further Reading

• AWS Directory Service Documentation
• Amazon Cognito Developer Guide
• IAM Identity Federation
• SAML 2.0 Federation with AWS
• Web Identity Federation