Using AWS IAM Identity Center and SAML to federate identities with your applications
Tags: iam, aws, awsidentitycenter, awssso
Published: 2023-12-11 15:14:15

---
title: Using AWS IAM Identity Center and SAML to federate identities with your applications
published: true
date: 2023-12-04 16:30:00 UTC
tags: IAM, AWS, AWSIdentityCenter, AWSSSO
canonical_url: https://imandrea.me/blog/saml-iam-ic/
---

Getting started with Identity and Access Management (a.k.a. **IAM**) can be frustrating, especially if we are going to start from scratch and we need to deal with identity federation and some enigmatic protocols such as SAML, OAuth, OIDC, etcetera. This is the first post of a series dedicated to AWS IAM Identity Center (**IAM IC**, for short) and related integrations.


## IAM Identity Center, in a nutshell

If you have to manage different accounts in AWS with a centralized fashion, you should definitely have a look at
[_AWS Organizations_](https://aws.amazon.com/it/organizations/). In this case,
you'll probably soon need to manage **workforce identities** and **access policies** in one central place. That's the moment when IAM Identity Center comes into play. IAM Identity Center, formerly known as _AWS SSO_, is the
recommended AWS solution oriented to the management of this scenario. For customer IAM (_CIAM_), however, you'd probably better rely on AWS Cognito (check [this talk](https://www.youtube.com/watch?v=qrQzUzDyjks) out for more about IAM IC).

IAM IC does have tons of features. First of all, as mentioned, you can use it as an identity source (i.e., where you manage users and groups). If you already have an external identity source such as Active Directory, you can simply bind
it to IAM IC.

### Federating identities for custom applications with SAML

What about **custom applications**? The good news is that we can leverage IAM IC for this purpose as well. In the next part of the post, we are going to play with an example where a custom Node.js application acts as the **Service Provider** (_SP_), using IAM IC as the **Identity Provider** (_IdP_), in a SAML-based scenario. In other words, **workforce users that can log in to AWS IC can SSO into our Node app**.

## Setting up IAM Identity Center (IdP)

This example assumes that we have already enabled IAM Identity Center in the management account of an organization with some users in it. If you need help with those very first steps, you can watch [this video walkthrough](https://www.youtube.com/watch?v=_KhrGFV_Npw). It's really well done!

Now, we need to go to **IAM Identity Center** > **Applications** and click on the "**Add application**" button. Then, a 2-step wizard begins.

### IdP Wizard - Step 1

In the first step, we'll be asked to select the application type. Select "**I have an application that I want to setup**". Then, scroll down and select **SAML 2.0** as the **application type**.

### IdP Wizard - Step 2

The second step is dedicated to the setting of the **SAML trust relationship** between IAM IC (again, the _IdP_), and our Node application (our _SP_). We are going to deal with this information:

- IAM IC metadata (IdP)
- IAM IC certificate (IdP)
- Node application metadata (SP)

If the SP application supports metadata import, download the **IAM Identity Center SAML metadata file** (XML). Otherwise, for this demo purposes, just copy
the **IAM Identity Center sign-in URL**, because we'll need it later. Make sure to download the **IAM Identity Center Certificate**.

![IdP metadata](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/egx6ck6yiay2ti7bwdof.png)

Now, you are expected to tell IAM IC the **metadata of our app**, namely the SP metadata:

- the **Application ACS URL**: the callback URL used by our app to process responses from IAM IC:
  - set to `http://localhost:3000/login/callback` (note that you do not need to make your app directly reachable by IAM IC)
  - this maps to the `AssertionConsumerServiceURL` attribute in the SAML Request
- the **Application SAML audience**: a predefined string to set in the trust process, and it needs to match on the IdP and the SP side:
  - set to `http://localhost:3000/myDemoSAMLAudience`
  - this value maps to the `Issuer` element in the SAML Request.

![SP Metadata](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/u9541vssakihqhesv4n6.png)

### Assigning users

We now need to **assign IAM IC users to our App**. Go to IAM **Identity Center** > **Applications** > **Your app name**, and then assign users and groups to our app in order to let them log in to it. For users of this demo, we should define:

- Username
- Email address
- First name
- Last name
- Display name

### Mapping attributes

Finally, we define how IdP attributes map to the SP counterpart. Go again to **IAM Identity Center** > **Applications** > **Your app name**. This time click
on the "**Actions**" button, and then on **Edit attribute mappings**. We set the mapping as follows:

| User attribute in the application | Maps to this string value or user attribute in IAM Identity Center | Format       |
| --------------------------------- | ------------------------------------------------------------------ | ------------ |
| Subject                           | ${user:email}                                                      | emailAddress |
| preferredUsername                 | ${user:preferredUsername}                                          | unspecified  |
| subject                           | ${user:subject}                                                    | unspecified  |
| givenName                         | ${user:givenName}                                                  | unspecified  |
| familyName                        | ${user:familyName}                                                 | unspecified  |
| Foo                               | This is just text                                                  | unspecified  |
| name                              | ${user:name}                                                       | unspecified  |
| email                             | ${user:email}                                                      | unspecified  |
| AD_GUID                           | ${user:AD_GUID}                                                    | unspecified  |

and we are done!

## Setting up our application (SP)

Now it's time to run our application. Clone [this repo](https://github.com/floatingpurr/sso-iam-ic), and set env variables in the `.env` file as follows:

```sh
# .env

IDP_ENTRYPOINT='IAM Identity Center sign-in URL (get it from  IAM IC metadata)'
IDP_AUDIENCE='http://localhost:3000/myDemoSAMLAudience'
SESSION_SECRET='mySessionSecretKey'
```

Then, rename the certificate provisioned by IAM IC into `cert.pem`, then copy it into the repo directory `cert`.

Finally, run `npm install && npm start`.

## Federation and SSO in action

Now, open up the URL http://localhost:3000 into your browser. You should be redirected to the IAM IC log-in page.

![IAM IC login page](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/anbijc9n3sezqzzi7i86.png)

Fill in the login form with a valid username and a password, and you are logged
in! You should land on the welcome page of our Node app echoing some user and
SAML details from the SAML response.

![SP SAML echo page](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1n25gka07litpfhcvdln.png)

The SAML trust that we have just configured allows the IAM IC user to log in to our Node app. This is a very brief example of SSO via SAML, backed by AWS IAM Identity Center.

## Other References and Credits

The main idea of this blog post comes from [this video](https://www.youtube.com/watch?v=lsDv5cjIaVY). Here, I updated the Node app, and I used the latest version of IAM IC.

Cheers!

^..^