Integrate with Amazon Web Services (Classic IAM)

Support level: authentik

What is AWS

AWS, or Amazon Web Services, is a comprehensive cloud computing platform. It provides a wide array of on-demand IT services like computing power, storage, and databases, allowing businesses to build and run applications, and manage infrastructure through the internet.

-- https://aws.amazon.com/what-is-aws

Preparation

The following placeholders are used in this guide:

• authentik.company is the FQDN of the authentik installation.
• <aws_account_ID> is your AWS account ID (e.g., 123456789012).
• <provider_name> is the name you will set for the SAML provider in AWS (e.g., authentik).

info

This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application.

Configuration methods

AWS Classic IAM can be integrated with authentik via SAML or OIDC. Below are the steps to configure each method.

SCIM Provisioning Limitation

SCIM Provisioning is only supported in conjunction with IAM Identity Center, not Classic IAM.

Classic IAM (SAML)

authentik configuration

To support the integration of AWS with authentik via the Classic IAM method, you need to create two property mappings, an application/provider pair, and application entitlements for the AWS roles that users can assume.

Create property mappings

1. Log in to authentik as an administrator and open the authentik Admin interface.

2. Navigate to Customization > Property Mappings, click Create, select SAML Provider Property Mappings, and click Next.

3. Configure the first mapping for the user's role assignment:

   • Name: provide a descriptive name (e.g., AWS Role Mapping)

   • SAML Attribute Name: https://aws.amazon.com/SAML/Attributes/Role

   • Friendly Name: Leave blank

   • Expression: Choose one of these options:

     For a static single role:

     return "arn:aws:iam::<aws_account_ID>:role/authentik-admin,arn:aws:iam::<aws_account_ID>:saml-provider/<provider_name>"

     For role assignment based on application entitlements (recommended):

     ACCOUNT_ID = "<aws_account_ID>"
     PROVIDER_NAME = "<provider_name>"
     roles = [
         entitlement.name
         for entitlement in request.user.app_entitlements(provider.application)
     ]
     
     return [
         f"arn:aws:iam::{ACCOUNT_ID}:role/{r},arn:aws:iam::{ACCOUNT_ID}:saml-provider/{PROVIDER_NAME}"
         for r in roles
     ]

     tip

     With the entitlement-based approach, create application entitlements with names like AWS:authentik-admin and AWS:authentik-read-only, then bind the appropriate users or groups to those entitlements. Create these entitlements after you create the application, as described later in this guide. Users receive the corresponding AWS roles when they access the AWS application.

     For multiple static roles:

     return [
         "arn:aws:iam::<aws_account_ID>:role/authentik-admin,arn:aws:iam::<aws_account_ID>:saml-provider/<provider_name>",
         "arn:aws:iam::<aws_account_ID>:role/authentik-read-only,arn:aws:iam::<aws_account_ID>:saml-provider/<provider_name>",
     ]

4. Click Finish to save. Then, repeat the process to create a mapping for the user's session name:

   • Name: provide a descriptive name (e.g., AWS Role Session Name)
   • SAML Attribute Name: https://aws.amazon.com/SAML/Attributes/RoleSessionName
   • Friendly Name: Leave blank
   • Expression: return user.username
   info

   This mapping determines how the user will be identified in AWS audit logs and the AWS console. The username will appear in the format <role_name>/<username> in AWS.

5. Click Finish.

Create an application and provider in authentik

1. Log in to authentik as an administrator and open the authentik Admin interface.

2. Navigate to Applications > Applications and click Create with Provider to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.)

   • Application: provide a descriptive name (e.g. AWS), an optional group for the type of application, the policy engine mode, and optional UI settings.
   • Choose a Provider type: select SAML Provider as the provider type.
   • Configure the Provider: provide a name (or accept the auto-provided name), and configure the following required settings:
     • Set the ACS URL to https://signin.aws.amazon.com/saml
     • Set the Issuer to urn:amazon:webservices
     • Set the Audience to urn:amazon:webservices
     • Set Service Provider Binding to Post
     • Under Advanced protocol settings, select an available Signing Certificate, ensure both Signing Assertions and Signing Responses are enabled, then add, under Property Mappings, both property mappings you created in the previous section.
     • Set NameID Property Mapping to authentik default SAML Mapping: Email.
   • Configure Bindings (optional): you can create a binding (policy, group, or user) to manage the listing and access to applications on a user's My applications page.

3. Click Submit to save the new application and provider.

NameID Format

AWS Classic IAM uses the email-formatted NameID. The default authentik SAML email mapping is automatically included and does not need to be added manually.

Create application entitlements for AWS roles

Use application entitlements to represent the AWS IAM roles this application should expose.

1. Open the AWS application that you just created in the authentik Admin interface.
2. Click the Application entitlements tab.
3. Create one entitlement for each AWS IAM role that users should be able to assume, such as authentik-admin or authentik-read-only.
4. Bind the appropriate users or groups to each entitlement.

tip

For this integration, the entitlement name should match the AWS IAM role name exactly. This keeps AWS-specific authorization scoped to the AWS application instead of relying on global group names such as AWS:authentik-admin.

Download metadata file

1. Log into authentik as an administrator and open the authentik Admin interface.
2. Navigate to Applications > Providers and click on the name of the newly created AWS provider.
3. Under Related objects > Metadata, click Download. This metadata file will be required in the next section.

AWS configuration

Create a SAML identity provider in AWS

1. Log in to the AWS Management Console as an administrator that has permissions to create IAM roles and identity providers.
2. Navigate to IAM > Identity providers.
3. Then, click Add provider and configure the following:
   • Provider type: Select SAML
   • Provider name: Enter a name (e.g., authentik). This must match the <provider_name> placeholder used in your property mappings.
   • Metadata document: Click Choose file and upload the metadata file you downloaded from authentik.
4. Click Add provider.

You will be redirected to the Identity providers home page.

Create IAM roles for SAML federation

For each role that users can assume via SAML (for example, authentik-admin or authentik-read-only), you need to create a corresponding IAM role in AWS. The role names must match the entitlement names that you created in authentik.

1. Still in the IAM console, navigate to Access management > Roles.
2. Click Create role.
3. Under Trusted entity type, click SAML 2.0 federation.
4. Under SAML 2.0–based provider, select the provider you created (e.g., authentik).
5. Under Access to be allowed, select depending on your needs:
   • Allow programmatic and AWS Management Console access
   • Allow programmatic access only
6. Under Sign-in endpoint type, choose based on your needs:
   • Regional endpoint: Region-specific sign-in URLs.
   • Non-Regional endpoint: Non-Regional sign-in URLs.
7. Click Next.
8. Select one or more policies that define the permissions for this role (e.g., AdministratorAccess, ReadOnlyAccess, or custom policies).
9. Click Next.
10. Set the Role name to match the entitlement name in authentik (e.g., authentik-admin). This name must exactly match the entitlement name.
11. Optionally add a description and tags.
12. Click Create role.

Update the role's trust policy

AWS automatically creates a trust policy for SAML federation, but it includes a unique session-specific ACS URL that needs to be updated to the generic signin URL.

1. Navigate back to IAM > Roles and click on the role you just created.

2. Go to the Trust relationships tab and click Edit trust policy.

3. You will see a policy similar to this:

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

4. Update the SAML:aud value from the session-specific URL to the generic signin URL:

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

   info

   The key change is replacing https://signin.aws.amazon.com/saml/acs/AAAAAA with https://signin.aws.amazon.com/saml. This allows any user authenticated through authentik to assume this role, regardless of their session.

5. Click Update policy.

Repeat the role creation process for each role that you want to make available to your users.

Test the integration

1. Log in to authentik and visit the Application library.
2. Click on the AWS application.
3. You should be redirected to AWS and logged in. Check the top-right corner of the AWS console to verify your identity is displayed in the format <role_name>/<username> (e.g., authentik-admin/dominic).

Classic IAM (OIDC)

Prerequisites

• An AWS account with permissions to create IAM roles and identity providers

AWS OIDC limitations

AWS does not support direct OIDC login for the AWS Management Console.

OIDC in AWS is mainly used for federated access to AWS resources and programmatic access, such as:

• Machine-to-machine authentication (CI/CD pipelines, automated scripts, etc.)
• Web applications requesting temporary AWS credentials via OIDC tokens
• Service account integrations in Kubernetes clusters (like EKS OIDC provider)

authentik configuration

To support the integration of AWS with authentik using OIDC, you need to create an application/provider pair in authentik.

Create an application and provider in authentik

1. Log in to authentik as an administrator and open the authentik Admin interface.

2. Navigate to Applications > Applications and click Create with Provider to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.)

   • Application: provide a descriptive name (e.g., AWS-OIDC), an optional group for the type of application, the policy engine mode, and optional UI settings.
   • Choose a Provider type: Select OAuth2/OpenID Provider as the provider type.
   • Configure the Provider: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations.
     • Note the Client ID and slug values because they will be required later.
     • Set a Strict redirect URI to match the AWS resource that you want to access via OIDC.
     • Select any available signing key.
     • Under Advanced protocol settings > Selected Scopes, add authentik default OAuth Mapping: OpenID 'entitlements'.
   • Configure Bindings (optional): you can create a binding (policy, group, or user) to manage the listing and access to applications on a user's My applications page.

3. Click Submit to save the new application and provider.

AWS configuration

1. Log in to the AWS Management Console as an administrator that has permissions to create IAM roles and identity providers.
2. Open the IAM Console and in the left sidebar under Access Management, click Identity providers.
3. Click Add provider and configure the following fields:
   • Provider type: OpenID Connect
   • Provider URL: https://authentik.company/application/o/<application-slug>/
   • Audience: set to the Client ID from authentik
4. Click Add provider
5. On the Identity providers page, click on the name of the provider that you just added.
6. Click Assign role and either create a new role or select an existing role. This will determine the AWS permissions of any user authenticated via OIDC.

Resources

• AWS Docs - Create a SAML identity provider in IAM
• AWS Docs - Create an OpenID Connect (OIDC) identity provider in IAM