website/integrations-all: convert authentik configuration to wizard (#13144)
* init * 6 more * tana... * quick reformat * welp only time for one change * wip * wip * wip * wip * wip * wip * wip * wip * Revert "wip" This reverts commit e71f0d22e3f093350e8d12eaad5e5c0f9d38253c. * wip * wip * wip * wip * wip * wip * wip * wip * wip * a
This commit is contained in:
Dominic R
@ -1,163 +0,0 @@
|
||||
---
|
||||
title: Integrate with Amazon Web Services
|
||||
sidebar_label: Amazon Web Services
|
||||
support_level: authentik
|
||||
---
|
||||
|
||||
## What is AWS
|
||||
|
||||
> Amazon Web Services (AWS) is the world’s most comprehensive and broadly adopted cloud, with more than 200 fully featured services available from data centers globally. Millions of customers—including the fastest-growing startups, largest enterprises, and leading government agencies—are using AWS to lower costs, increase security, become more agile, and innovate faster.
|
||||
>
|
||||
> -- https://www.aboutamazon.com/what-we-do/amazon-web-services
|
||||
|
||||
## Select your method
|
||||
|
||||
There are two ways to perform the integration: the classic IAM SAML way, or the 'newer' IAM Identity Center way. This all depends on your preference and needs.
|
||||
|
||||
## Method 1: Classic IAM
|
||||
|
||||
### Preparation
|
||||
|
||||
Create an application in authentik and note the slug, as this will be used later. Create a SAML provider with the following parameters:
|
||||
|
||||
- **ACS URL**: `https://signin.aws.amazon.com/saml`
|
||||
- **Issuer**: `authentik`
|
||||
- **Binding**: `Post`
|
||||
- **Audience**: `urn:amazon:webservices`
|
||||
|
||||
You can use a custom signing certificate and adjust durations as needed.
|
||||
|
||||
### AWS
|
||||
|
||||
Create a role with the permissions you desire, and note the ARN.
|
||||
|
||||
After configuring the Property Mappings, add them to the SAML Provider in AWS.
|
||||
|
||||
Create an application, assign policies, and assign this provider.
|
||||
|
||||
Export the metadata from authentik and create a new Identity Provider [here](https://console.aws.amazon.com/iam/home#/providers).
|
||||
|
||||
#### Role Mapping
|
||||
|
||||
The Role mapping specifies the AWS ARN(s) of the identity provider, and the role the user should assume ([see](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html#saml_role-attribute)).
|
||||
|
||||
This Mapping needs to have the SAML Name field set to `https://aws.amazon.com/SAML/Attributes/Role`.
|
||||
|
||||
As expression, you can return a static ARN like so
|
||||
|
||||
```python
|
||||
return "arn:aws:iam::123412341234:role/saml_role,arn:aws:iam::123412341234:saml-provider/authentik"
|
||||
```
|
||||
|
||||
Or, if you want to assign AWS Roles based on Group membership, you can add a custom attribute to the Groups, for example "aws_role", and use this snippet below. Groups are sorted by name and later groups overwrite earlier groups' attributes.
|
||||
|
||||
```python
|
||||
role_name = user.group_attributes().get("aws_role", "")
|
||||
return f"arn:aws:iam::123412341234:role/{role_name},arn:aws:iam::123412341234:saml-provider/authentik"
|
||||
```
|
||||
|
||||
If you want to allow a user to choose from multiple roles, use this snippet
|
||||
|
||||
```python
|
||||
return [
|
||||
"arn:aws:iam::123412341234:role/role_a,arn:aws:iam::123412341234:saml-provider/authentik",
|
||||
"arn:aws:iam::123412341234:role/role_b,arn:aws:iam::123412341234:saml-provider/authentik",
|
||||
"arn:aws:iam::123412341234:role/role_c,arn:aws:iam::123412341234:saml-provider/authentik",
|
||||
]
|
||||
```
|
||||
|
||||
### RoleSessionName Mapping
|
||||
|
||||
The RoleSessionMapping specifies what identifier will be shown at the top of the Management Console ([see](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html#saml_role-session-attribute)).
|
||||
|
||||
This mapping needs to have the SAML Name field set to `https://aws.amazon.com/SAML/Attributes/RoleSessionName`.
|
||||
|
||||
To use the user's username, use this snippet
|
||||
|
||||
```python
|
||||
return user.username
|
||||
```
|
||||
|
||||
## Method 2: IAM Identity Center
|
||||
|
||||
### Preparation
|
||||
|
||||
- A certificate to sign SAML assertions is required. You can use authentik's default certificate, or provide/generate one yourself.
|
||||
- You may pre-create an AWS application.
|
||||
|
||||
### How to integrate with AWS
|
||||
|
||||
In AWS:
|
||||
|
||||
- In AWS, navigate to: **IAM Identity Center -> Settings -> Identity Source (tab)**
|
||||
- On the right side, click **Actions** -> **Change identity source**
|
||||
- Select **External Identity Provider**
|
||||
- Under **Service Provider metadata** download the metadata file.
|
||||
|
||||
Now go to your authentik instance, and perform the following steps.
|
||||
|
||||
- Under **Providers**, create a new **SAML Provider from metadata**. Give it a name, and upload the metadata file AWS gave you.
|
||||
- Click **Next**. Give it a name, and close the file.
|
||||
- If you haven't done so yet, create an application for AWS and connect the provider to it.
|
||||
- Navigate to the provider you've just created, and then select **Edit**
|
||||
- Copy the **Issuer URL** to the **Audience** field.
|
||||
- Under **Advanced Protocol Settings** set a **Signing Certificate**
|
||||
- Save and Close.
|
||||
- Under **Related Objects**, download the **Metadata file** and the **Signing Certificate**
|
||||
|
||||
Now go back to your AWS instance
|
||||
|
||||
- Under **Identity provider metadata**, upload both the **Metadata** file and **Signing Certificate** that authentik gave you.
|
||||
- Click **Next**.
|
||||
- In your settings pane, under the tab **Identity Source**, click **Actions** -> **Manage Authentication**.
|
||||
- Note the AWS access portal sign-in URL (especially if you have customized it).
|
||||
|
||||
Now go back to your authentik instance.
|
||||
|
||||
- Navigate to the Application that you created for AWS and click **Edit**.
|
||||
- Under **UI Settings** make sure the **Start URL** matches the **AWS access portal sign-in URL**.
|
||||
|
||||
:::::info
|
||||
|
||||
- Ensure users already exist in AWS for authentication through authentik. AWS will throw an error if the user is unrecognized.
|
||||
- In case you're stuck, you can see the SSO logs in Amazon CloudTrail -> Event History. Look for `ExtenalIdPDirectoryLogin`.
|
||||
:::::
|
||||
|
||||
## Optional: Automated provisioning with SCIM
|
||||
|
||||
Some people may opt to use the automatic provisioning feature called SCIM (System for Cross-domain Identity Management).
|
||||
SCIM allows you to synchronize (part of) your directory to AWS's IAM, saving you the hassle of having to create users by hand.
|
||||
To do so, take the following steps in your AWS Identity Center:
|
||||
|
||||
- In your **Settings** pane, locate the **Automatic Provisioning** information box. Click **Enable**.
|
||||
- AWS provides an SCIM Endpoint and an Access Token. Note these values.
|
||||
|
||||
Go back to your authentik instance
|
||||
|
||||
- Navigate to **Providers** -> **Create**
|
||||
- Select **SCIM Provider**
|
||||
- Give it a name, under **URL** enter the **SCIM Endpoint**, and then under **Token** enter the **Access Token** AWS provided you with.
|
||||
- Optionally, change the user filtering settings to your liking. Click **Finish**
|
||||
|
||||
- Go to **Customization -> Property Mappings**
|
||||
- Click **Create -> SCIM Mapping**
|
||||
- Make sure to give the mapping a name that's lexically lower than `authentik default`, for example `AWS SCIM User mapping`
|
||||
- As the expression, enter:
|
||||
|
||||
```python
|
||||
# This expression strips the default mapping from its 'photos' attribute,
|
||||
# which is a forbidden property in AWS IAM.
|
||||
return {
|
||||
"photos": None,
|
||||
}
|
||||
```
|
||||
|
||||
- Click **Save**. Navigate back to your SCIM provider, click **Edit**
|
||||
- Under **User Property Mappings** select the default mapping and the mapping that you just created.
|
||||
- Click **Update**
|
||||
|
||||
- Navigate to your application, click **Edit**.
|
||||
- Under **Backchannel providers** add the SCIM provider that you created.
|
||||
- Click **Update**
|
||||
|
||||
The SCIM provider syncs automatically whenever you create/update/remove users, groups, or group membership. You can manually sync by going to your SCIM provider and clicking **Run sync again**. After the SCIM provider has synced, you should see the users and groups in your AWS IAM center.
|
||||
206
website/integrations/services/aws/index.mdx
Normal file
206
website/integrations/services/aws/index.mdx
Normal file
@ -0,0 +1,206 @@
|
||||
---
|
||||
title: Integrate with Amazon Web Services
|
||||
sidebar_label: Amazon Web Services
|
||||
support_level: authentik
|
||||
---
|
||||
|
||||
## What is AWS
|
||||
|
||||
> Amazon Web Services (AWS) is the world's most comprehensive and broadly adopted cloud, with more than 200 fully featured services available from data centers globally. Millions of customers—including the fastest-growing startups, largest enterprises, and leading government agencies—are using AWS to lower costs, increase security, become more agile, and innovate faster.
|
||||
>
|
||||
> -- https://www.aboutamazon.com/what-we-do/amazon-web-services
|
||||
|
||||
## Preparation
|
||||
|
||||
The following placeholders are used in this guide:
|
||||
|
||||
- `authentik.company` is the FQDN of the authentik installation.
|
||||
- `123412341234` is your AWS account ID.
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="iam" label="Classic IAM" default>
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- An AWS account with permissions to create IAM roles and identity providers
|
||||
- An authentik instance with admin access
|
||||
|
||||
### authentik configuration
|
||||
|
||||
To support the integration of AWS with authentik using the classic IAM method, you need to create an application/provider pair and property mappings in authentik.
|
||||
|
||||
#### Create property mappings
|
||||
|
||||
1. Log in to authentik as an admin, and open the authentik Admin interface.
|
||||
2. Navigate to **Customization** > **Property Mappings** and click **Create**. Create two **SAML Provider Property Mapping**s with the following settings:
|
||||
|
||||
- **Role Mapping:**
|
||||
|
||||
- **Name**: Choose a descriptive name
|
||||
- **SAML Attribute Name**: <kbd>https://aws.amazon.com/SAML/Attributes/Role</kbd>
|
||||
- **Friendly Name**: Leave blank
|
||||
- **Expression**: Choose one of these options:
|
||||
|
||||
For a static role:
|
||||
|
||||
```python
|
||||
return "arn:aws:iam::123412341234:role/saml_role,arn:aws:iam::123412341234:saml-provider/authentik"
|
||||
```
|
||||
|
||||
For role assignment based on group membership:
|
||||
|
||||
```python
|
||||
role_name = user.group_attributes().get("aws_role", "")
|
||||
return f"arn:aws:iam::123412341234:role/{role_name},arn:aws:iam::123412341234:saml-provider/authentik"
|
||||
```
|
||||
|
||||
For multiple role choices:
|
||||
|
||||
```python
|
||||
return [
|
||||
"arn:aws:iam::123412341234:role/role_a,arn:aws:iam::123412341234:saml-provider/authentik",
|
||||
"arn:aws:iam::123412341234:role/role_b,arn:aws:iam::123412341234:saml-provider/authentik",
|
||||
"arn:aws:iam::123412341234:role/role_c,arn:aws:iam::123412341234:saml-provider/authentik",
|
||||
]
|
||||
```
|
||||
|
||||
- **Session Name Mapping:**
|
||||
- **Name**: Choose a descriptive name
|
||||
- **SAML Attribute Name**: <kbd>https://aws.amazon.com/SAML/Attributes/RoleSessionName</kbd>
|
||||
- **Friendly Name**: Leave blank
|
||||
- **Expression**: <kbd>return user.username</kbd>
|
||||
|
||||
#### Create an application and provider in authentik
|
||||
|
||||
1. Log in to authentik as an admin, 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 create only an application, without a provider, by clicking **Create**.)
|
||||
|
||||
- **Application**: provide a descriptive name (e.g. "AWS"), an optional group for the type of application, the policy engine mode, and optional UI settings. The **slug** will be used in URLs and should match the `aws-slug` placeholder defined earlier.
|
||||
- **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 <kbd>https://signin.aws.amazon.com/saml</kbd>
|
||||
- Set the **Audience** to <kbd>urn:amazon:webservices</kbd>
|
||||
- Under **Advanced protocol settings**, add both property mappings you created in the previous section
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (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.
|
||||
4. Download the **Metadata file** from the provider's page.
|
||||
|
||||
### AWS configuration
|
||||
|
||||
1. Log in to the AWS Management Console as an administrator
|
||||
2. Create an IAM role with the desired permissions and note the ARN
|
||||
3. Navigate to [IAM Identity Providers](https://console.aws.amazon.com/iam/home#/providers)
|
||||
4. Click **Create Provider** and configure:
|
||||
- Select **SAML** as the provider type
|
||||
- Upload the metadata file from authentik
|
||||
5. Add the property mappings to the SAML Provider
|
||||
6. Create an application and assign the appropriate policies
|
||||
7. Connect the provider to your application
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="identity-center" label="IAM Identity Center">
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- An AWS account with IAM Identity Center enabled
|
||||
- An authentik instance with admin access
|
||||
- A certificate for signing SAML assertions (you can use authentik's default or provide your own)
|
||||
|
||||
### authentik configuration
|
||||
|
||||
To support the integration of AWS with authentik using IAM Identity Center, you need to create an application/provider pair in authentik.
|
||||
|
||||
#### Create an application and provider in authentik
|
||||
|
||||
1. Log in to authentik as an admin, 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 create only an application, without a provider, by clicking **Create**.)
|
||||
|
||||
- **Application**: provide a descriptive name (e.g. "AWS Identity Center"), an optional group for the type of application, the policy engine mode, and optional UI settings. The **slug** will be used in URLs and should match the `aws-slug` placeholder defined earlier.
|
||||
- **Choose a Provider type**: select **SAML Provider from metadata** as the provider type.
|
||||
- **Configure the Provider**: provide a name (or accept the auto-provided name), and configure the following required settings:
|
||||
- Upload the metadata file from AWS (obtained in AWS Configuration steps)
|
||||
- Copy the **Issuer URL** to the **Audience** field
|
||||
- Under **Advanced Protocol Settings**, set your **Signing Certificate**
|
||||
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (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.
|
||||
4. Under **Related Objects**, download both:
|
||||
- The **Metadata file**
|
||||
- The **Signing Certificate**
|
||||
|
||||
### AWS configuration
|
||||
|
||||
1. Navigate to **IAM Identity Center -> Settings -> Identity Source**
|
||||
2. Click **Actions -> Change identity source**
|
||||
3. Select **External Identity Provider**
|
||||
4. Download the **Service Provider metadata** file
|
||||
5. Upload authentik's metadata file and signing certificate
|
||||
6. Under **Actions -> Manage Authentication**, note the AWS access portal sign-in URL
|
||||
7. Update your authentik application's **Start URL** to match the AWS portal URL.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="scim" label="SCIM Provisioning (Optional)">
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Completed either Classic IAM or IAM Identity Center setup
|
||||
- AWS Identity Center enabled with admin access
|
||||
- authentik instance with admin access
|
||||
|
||||
### authentik configuration
|
||||
|
||||
To support the integration of AWS with authentik using SCIM, you need to create a SCIM provider and custom mapping in authentik.
|
||||
|
||||
#### Create property mappings
|
||||
|
||||
1. Log in to authentik as an admin, and open the authentik Admin interface.
|
||||
2. Navigate to **Customization** > **Property Mappings** and click **Create**. Create a **SCIM Mapping** with the following settings:
|
||||
- **Name**: Choose a name lexically lower than `authentik default` (e.g. `AWS SCIM User mapping`)
|
||||
- **Expression**:
|
||||
```python
|
||||
# This expression strips the default mapping from its 'photos' attribute,
|
||||
# which is a forbidden property in AWS IAM.
|
||||
return {
|
||||
"photos": None,
|
||||
}
|
||||
```
|
||||
|
||||
#### Create a SCIM provider in authentik
|
||||
|
||||
1. Log in to authentik as an admin, and open the authentik Admin interface.
|
||||
2. Navigate to **Providers** > **Providers** and click **Create**.
|
||||
3. Select **SCIM Provider** as the provider type.
|
||||
4. Configure the provider with the following settings:
|
||||
- Set a descriptive name
|
||||
- Set **URL** to the AWS SCIM Endpoint
|
||||
- Set **Token** to the AWS Access Token
|
||||
- Configure user filtering as needed
|
||||
5. Under **User Property Mappings**, add:
|
||||
- The default mapping
|
||||
- Your custom mapping
|
||||
6. Add the SCIM provider to your AWS application's **Backchannel providers**
|
||||
|
||||
### AWS configuration
|
||||
|
||||
1. In AWS Identity Center **Settings**, locate the **Automatic Provisioning** information box
|
||||
2. Click **Enable**
|
||||
3. Note the provided **SCIM Endpoint** and **Access Token**
|
||||
|
||||
The SCIM provider will automatically sync when users, groups, or memberships change. You can manually sync from the provider page.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [AWS IAM SAML Documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html)
|
||||
- [AWS IAM Identity Center Documentation](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html)
|
||||
- [AWS SCIM Documentation](https://docs.aws.amazon.com/singlesignon/latest/userguide/scim-profile.html)
|
||||
Reference in New Issue
Block a user