AWS SAML Integration Guide - SplitSecure Docs

Prerequisites

Access to the AWS Management Console with permissions to manage IAM identity providers and roles (iam:CreateSAMLProvider, iam:CreateRole, iam:AttachRolePolicy)
A SplitSecure Identity Provider created and approved
A separate browser or browser profile with SplitSecure configured (for testing)

AWS IAM Configuration#

1 Download SplitSecure Metadata#

Before configuring AWS, download the SAML metadata from SplitSecure:

In SplitSecure, go to Secure Accounts → SAML2 Identity Providers
Click Details on the desired identity provider
Click Download Metadata to save the XML file

2 Create a SAML Identity Provider in IAM#

Sign in to the AWS Management Console
In the navigation pane, choose Identity providers
Click Add provider
Configure the provider:

Field	Value
Provider type	SAML
Provider name	(e.g., SplitSecure IdP)
Metadata document	Upload the XML file downloaded from SplitSecure

Click Add provider

3 Create an IAM Role for SAML Federation#

You can either:

(If you are still in your Identity Provider’s page) at the top right of the page, click Assign role
In the IAM console navigation pane, choose Roles. Then at the top right of the page, click Create role

Note

You can also use existing roles if they already have the appropriate trust policy.

Fill the form like so:

Field	Value
Trusted entity type	SAML 2.0 federation
SAML 2.0–based provider	Select the provider you created (e.g., “SplitSecure”)
Access to be allowed	Allow programmatic and AWS Management Console access
Sign-in endpoint type	Non-Regional endpoint
Sign-in URLs to include unique identifiers	With unique identifiers

Add permissions#

Permissions — Configure permissions in AWS for SAML federated principals

Select the permissions policies for federated users (e.g., AdministratorAccess, ReadOnlyAccess, PowerUserAccess)
Click Next

Name, review, and create#

Enter a Role name (e.g., SplitSecure-SAML-Role)
(Optional) Enter a description
Click Create Role
Note the Role ARN for SplitSecure configuration (e.g., arn:aws:iam::<account-id>:role/SplitSecure-SAML-Role)

Note

In the Trust relationships tab you can validate that the role uses the right IdP:

{
   "Version": "2012-10-17",
   "Statement": [
       {
           "Effect": "Allow",
           "Principal": {
               "Federated": "arn:aws:iam::<account-id>:saml-provider/SplitSecure"
           },
           "Action": "sts:AssumeRoleWithSAML",
           "Condition": {
               "StringEquals": {
                   "SAML:aud": "https://signin.aws.amazon.com/saml/acs/SAMLSPAA1AA1AA1111AA1A"
               }
           }
       }
   ]
}

By clicking Edit trust policy you can use the Edit statement sidebar in order to edit access levels, principals, condition and more

Terraform Configuration (Alternative)#

If you manage your AWS infrastructure with Terraform, you can use the following configuration instead of the console steps above.

1 Create the SAML Provider and Role#

Place the SplitSecure metadata XML file (downloaded in the previous section) alongside your Terraform configuration, e.g. as splitsecure-idp-metadata.xml.

# SAML Identity Provider — trusts SplitSecure's signing certificate
resource "aws_iam_saml_provider" "splitsecure" {
  name                   = "SplitSecure"
  saml_metadata_document = file("${path.module}/splitsecure-idp-metadata.xml")
}

# IAM Role assumable via SAML federation
resource "aws_iam_role" "splitsecure_saml" {
  name = "SplitSecure-SAML-Role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Principal = {
          Federated = aws_iam_saml_provider.splitsecure.arn
        }
        Action = "sts:AssumeRoleWithSAML"
        Condition = {
          StringEquals = {
            "SAML:aud" = var.splitsecure_saml_acs_url
          }
        }
      }
    ]
  })
}

# Attach permissions — adjust to your needs
resource "aws_iam_role_policy_attachment" "splitsecure_saml" {
  role       = aws_iam_role.splitsecure_saml.name
  policy_arn = "arn:aws:iam::aws:policy/ReadOnlyAccess"
}

variable "splitsecure_saml_acs_url" {
  description = "ACS URL with unique identifier, found in the IAM SAML provider details after creation"
  type        = string
  # e.g. "https://signin.aws.amazon.com/saml/acs/SAMLSPKV6810N69SHRSTL5"
}

Note

After creating the SAML provider, find the ACS URL in the AWS Console → IAM → Identity providers → your provider. It looks like https://signin.aws.amazon.com/saml/acs/SAMLSP<unique-id>. Use this value for splitsecure_saml_acs_url.

2 Apply and Note the Outputs#

terraform apply

After applying, note the provider ARN and role ARN for SplitSecure configuration:

terraform output -raw splitsecure_saml_provider_arn
terraform output -raw splitsecure_saml_role_arn

Add the corresponding outputs to your configuration:

output "splitsecure_saml_provider_arn" {
  value = aws_iam_saml_provider.splitsecure.arn
}

output "splitsecure_saml_role_arn" {
  value = aws_iam_role.splitsecure_saml.arn
}

3 Multiple Roles (Optional)#

To expose multiple roles with different permission levels through the same IdP, add more role resources:

variable "splitsecure_roles" {
  description = "Roles assumable via SplitSecure SAML federation"
  type = map(object({
    policy_arns = list(string)
  }))
  default = {
    readonly = {
      policy_arns = ["arn:aws:iam::aws:policy/ReadOnlyAccess"]
    }
    admin = {
      policy_arns = ["arn:aws:iam::aws:policy/AdministratorAccess"]
    }
  }
}

resource "aws_iam_role" "splitsecure" {
  for_each = var.splitsecure_roles
  name     = "SplitSecure-${each.key}"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Principal = {
          Federated = aws_iam_saml_provider.splitsecure.arn
        }
        Action = "sts:AssumeRoleWithSAML"
        Condition = {
          StringEquals = {
            "SAML:aud" = var.splitsecure_saml_acs_url
          }
        }
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "splitsecure" {
  for_each = {
    for pair in flatten([
      for role_key, role in var.splitsecure_roles : [
        for policy_arn in role.policy_arns : {
          key        = "${role_key}-${basename(policy_arn)}"
          role_name  = aws_iam_role.splitsecure[role_key].name
          policy_arn = policy_arn
        }
      ]
    ]) : pair.key => pair
  }

  role       = each.value.role_name
  policy_arn = each.value.policy_arn
}

4 Cross-Account Roles (Optional)#

To allow SplitSecure federation into roles in other AWS accounts, create the role in the target account while referencing the SAML provider from the identity account:

variable "splitsecure_saml_provider_arn" {
  description = "ARN of the SplitSecure SAML provider in the identity account"
  type        = string
  # e.g. "arn:aws:iam::123456789012:saml-provider/SplitSecure"
}

resource "aws_iam_role" "splitsecure_cross_account" {
  name = "SplitSecure-CrossAccount"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Principal = {
          Federated = var.splitsecure_saml_provider_arn
        }
        Action = "sts:AssumeRoleWithSAML"
        Condition = {
          StringEquals = {
            "SAML:aud" = var.splitsecure_saml_acs_url
          }
        }
      }
    ]
  })
}

Note

The SAML provider only needs to exist in one account (the identity account). Target accounts reference it by ARN in their trust policies.

SplitSecure Configuration#

1 Register the AWS Account in SplitSecure#

In SplitSecure, navigate to Secure Accounts → Create Account → AWS
Enter a name for your account
Select the Identity Provider whose metadata you uploaded to AWS
Enter the sign-in URL and the IAM Identity Provider ARN (found in the AWS Console under IAM → Identity providers → your provider)
(Optional) In the default Role ARN field you can put the ARN found in the console at IAM → Roles → Your Role in the top corner

arn:aws:iam::111111111111:role/MyRole

Click Create Account

Test Authentication#

Tip

Use a separate browser or browser profile with SplitSecure configured to test without affecting your current session.

1 Test IdP-Initiated Sign-In#

In SplitSecure, navigate to Secure Accounts
Locate your AWS account and click Authenticate
Choose your role, session name and session duration
Click Request Access
Complete the authentication flow

If authentication is successful, you will be redirected to the AWS Management Console with the selected role.

Troubleshooting#

Issue	Possible Cause	Solution
Response signature invalid	Certificate mismatch	Re-download metadata from SplitSecure and update the IAM provider
Not authorized to perform sts:AssumeRoleWithSAML	Trust policy misconfigured	Verify the Principal ARN matches your SAML provider exactly
Invalid SAML response	Metadata parsing error	Ensure metadata is UTF-8 encoded without BOM
RoleSessionName is required	Missing SAML attribute	Configure SplitSecure to send the RoleSessionName attribute
User redirected to wrong account	Multiple AWS accounts	Verify the correct Role ARN is configured in SplitSecure
Access denied after successful auth	Insufficient role permissions	Review and update the IAM role’s permissions policy
Session expires too quickly	Default session duration	Add SessionDuration attribute (up to 43200 seconds)
SAML assertion audience mismatch	Wrong ACS URL	Ensure SAML:aud matches the full ACS URL from your IAM SAML provider details

External Resources#

External Identity Providers — Managing identity sources in IAM Identity Center
Connect to an External Identity Provider — Step-by-step IdP connection guide
SAML 2.0 Federation — IAM SAML federation setup