If your team manages more than one AWS account, you already know the pain of juggling separate logins for each one. Single Sign-On (SSO) through Keycloak solves this. Your team logs in once and gets access to every AWS account they're authorized for, without a separate password for each.

This guide sets up SSO for one new AWS account. You don't build the configuration from scratch — you import a ready-made client JSON, replace one placeholder, then create a role and assign it to whoever needs access.

For a sense of what this looks like at production scale, this case study on a multi-brand Keycloak SSO rollout covers a similar setup built for an energy sector customer platform.

If you'd rather hand the whole thing off, Perfsys's Keycloak SSO service covers the full setup, deployment, custom auth flows, MFA, and the runbooks your team needs to operate it afterward.

Throughout, the examples use a fictional account labelled ExampleCorp_Staging with AWS account ID 123456789012.

Step 1: Import the Client

This is the client JSON. Everything in it is already correct except one placeholder.

{
  "clientId": "Amazon_Perfsys_SSO_NAME",
  "protocol": "saml",
  "enabled": true,
  "baseUrl": "/realms/{realm}/protocol/saml/clients/amazon-aws-NAME",
  "redirectUris": ["https://signin.aws.amazon.com/saml"],
  "alwaysDisplayInConsole": true,
  "fullScopeAllowed": false,
  "attributes": {
    "saml_name_id_format": "transient",
    "saml_idp_initiated_sso_url_name": "amazon-aws-NAME",
    "saml_assertion_consumer_url_post": "https://signin.aws.amazon.com/saml",
    "saml.force.post.binding": "true",
    "saml.authnstatement": "true",
    "saml.assertion.signature": "true",
    "saml.server.signature": "true",
    "saml.client.signature": "false",
    "saml.encrypt": "false"
  },
  "protocolMappers": [
    {
      "name": "Session Name",
      "protocol": "saml",
      "protocolMapper": "saml-user-property-mapper",
      "config": {
        "user.attribute": "username",
        "attribute.name": "https://aws.amazon.com/SAML/Attributes/RoleSessionName",
        "attribute.nameformat": "Basic"
      }
    },
    {
      "name": "Session Duration",
      "protocol": "saml",
      "protocolMapper": "saml-hardcode-attribute-mapper",
      "config": {
        "attribute.value": "28800",
        "attribute.name": "https://aws.amazon.com/SAML/Attributes/SessionDuration",
        "attribute.nameformat": "Basic"
      }
    },
    {
      "name": "Session Role",
      "protocol": "saml",
      "protocolMapper": "saml-role-list-mapper",
      "config": {
        "single": "true",
        "attribute.name": "https://aws.amazon.com/SAML/Attributes/Role",
        "attribute.nameformat": "Basic"
      }
    }
  ],
  "defaultClientScopes": [],
  "optionalClientScopes": []
}

Fields to update

Replace NAME with a short label for the account, and {realm} with your realm. Nothing else changes per account — the AWS account ID does not appear here at all, only in Step 2.

Two traps in that table. Underscores are not allowed in the SSO URL name, so ExampleCorp_Staging becomes ExampleCorp-Staging. And baseUrl repeats the SSO URL name — Keycloak keeps no link between the two, so if they disagree the client still works via its real URL while the account-console tile points at a dead path.

Import it

1. Keycloak admin console → your realm → Clients → Import client.

   

2. Browse, pick your file, then Save. Keycloak previews the JSON and fills in the Client ID and Type from it.

   

[!NOTE] This screen shows Encrypt assertions: On, but the form renders that toggle from its own defaults rather than from your file. saml.encrypt is false in the JSON, and false is what gets saved.

Verify three things

The import does the work, but confirm it landed. All three are on the client's Settings tab except the last.

Name ID format is transient. Under SAML capabilities.

The SSO URL name and redirect URI are right. Under Access settings. Also confirm Always display in UI is on, at the top of the same tab — without it the client never appears at /realms/{realm}/account/applications, and the user you just granted access to reports they cannot see the account.

The role_list client scope is gone. Open the Client scopes tab. It should list only <client>-dedicated. The JSON sets defaultClientScopes: [], but Keycloak attaches role_list to SAML clients anyway, so check rather than assume. If it is there, click Remove on that row.

role_list is worth understanding, because it produces a failure that points nowhere near Keycloak. The scope carries its own role mapper emitting the attribute Role. Your client's Session Role mapper emits https://aws.amazon.com/SAML/Attributes/Role, which is the name AWS looks for. Keycloak runs exactly one role mapper per login and keeps the first it finds, so which one wins is luck. When role_list wins, AWS finds no role attribute and answers Your request included an invalid SAML response — the same message it uses for a bad signature.

[!WARNING] Remove the scope from the client. Never edit the mapper inside the role_list scope, because that scope is shared with every other SAML client in the realm.

Step 2: Create the Role

The role name is where the AWS account ID finally appears. One Keycloak role encodes two ARNs, comma-separated, no space.

1. Open the client → Roles tab → Create role.

2. Enter the role name:

arn:aws:iam::{ACCOUNT_ID}:role/{ROLE_NAME},arn:aws:iam::{ACCOUNT_ID}:saml-provider/SAML-Perfsys

For the example account that gives:

arn:aws:iam::123456789012:role/Keycloak-AdministratorAccess,arn:aws:iam::123456789012:saml-provider/SAML-Perfsys

1. Add a description naming the account, then Save.

The whole string is a single role name. The comma joining the two ARNs takes no space after it. This is the field people get wrong most often.

{ROLE_NAME} is the IAM role in the target account: Keycloak-AdministratorAccess for admin, Federated-ReadOnly for read-only. SAML-Perfsys is the IAM SAML provider — do not derive it from your client name. The CloudFormation stack hardcodes it, so it is SAML-Perfsys in every account regardless of what you called the client.

Both privilege levels go on the same client. A second access level does not need a second Keycloak client. Session Role has single: "true", so every role the user holds becomes another value of one Role attribute — exactly what AWS needs to render its role picker at login. One client per AWS account, one role per privilege level.

Step 3: Assign the Role

1. Users → the person → Role mapping tab → Assign role.

2. Change the filter dropdown from Filter by realm roles to Filter by clients.

3. Search the account ID or client name, tick the role, Assign.

Step 2 is not optional. Client roles are invisible in the default realm-roles view, so skipping the dropdown shows an empty list and looks like the role was never created. The client badge on the left is also how you tell two accounts apart when the ARNs are truncated.

For a whole team, use Groups → the group → Role mapping, same filter change. Check the membership first: every member gets that AWS access.

Test it:

https://{keycloak-host}/realms/{realm}/protocol/saml/clients/amazon-aws-ExampleCorp-Staging

Troubleshooting

The two AWS error strings rule out different halves of the system. Read which one you got before investigating.

"Your request included an invalid SAML response" — AWS could not validate the assertion, or found no role attribute in it. Check the role_list scope first; it is the cheap cause and takes one look at the Client scopes tab. Only then look at the IAM SAML provider in the target account.

"Not authorized to perform sts:AssumeRoleWithSAML" — the assertion validated, then failed at the trust boundary. A signature problem would have given the other error, so Keycloak is almost certainly fine. Look at the role's trust policy, the account ID, and MaxSessionDuration against the 28800 the Session Duration mapper requests.

Only one role in the picker is usually not a bug. A role must be assigned to the user or their group, not merely defined on the client. Defining Federated-ReadOnly does not put it in anyone's assertion.

Why This Matters for Your Team

Every field ties back to something concrete. The Client ID and SSO URL name identify which AWS account you're connecting to. The Name ID format controls how Keycloak identifies the user to AWS on each login. The role's ARN string is what actually grants access, and it has to match the target account's IAM setup exactly, account ID and role name included.

Get these three steps right and your team gets centralized access to every AWS account they manage. No shared passwords, no separate logins to track. When someone leaves, offboarding is a single step instead of a checklist you hope nobody forgets.

https://perfsys.com/