From c702b0fd078018380d8eff81d928fcef08387055 Mon Sep 17 00:00:00 2001 From: 4d62 Date: Fri, 5 Jul 2024 15:40:41 -0400 Subject: [PATCH] website/integrations: aws: cleanup (#10355) * website/integrations: aws: cleanup Signed-off-by: 4d62 * p * add info thing Signed-off-by: 4d62 * aaaaaaaaaaaaaaaaaaaaaaaaaaaaa * i think this will work copied ::::: from other page Signed-off-by: 4d62 * final lint * Update website/integrations/services/aws/index.md Co-authored-by: Jens L. Signed-off-by: 4d62 --------- Signed-off-by: 4d62 Co-authored-by: 4d62 Co-authored-by: Jens L. --- website/integrations/services/aws/index.md | 108 ++++++++++----------- 1 file changed, 53 insertions(+), 55 deletions(-) diff --git a/website/integrations/services/aws/index.md b/website/integrations/services/aws/index.md index dd8b429d31..16b4bfc338 100644 --- a/website/integrations/services/aws/index.md +++ b/website/integrations/services/aws/index.md @@ -12,37 +12,36 @@ title: 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. +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 +## Method 1: Classic IAM -## Preparation +### 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` +- **ACS URL**: `https://signin.aws.amazon.com/saml` +- **Issuer**: `authentik` +- **Binding**: `Post` +- **Audience**: `urn:amazon:webservices` -You can of course use a custom signing certificate, and adjust durations. +You can use a custom signing certificate and adjust durations as needed. -## AWS +### AWS Create a role with the permissions you desire, and note the ARN. -After you've created the Property Mappings below, add them to the Provider. +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 an Identity Provider [here](https://console.aws.amazon.com/iam/home#/providers). +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" +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 @@ -71,7 +70,7 @@ return [ 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". +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 @@ -79,70 +78,69 @@ To use the user's username, use this snippet return user.username ``` -# Method 2: IAM Identity Center +## Method 2: IAM Identity Center -## Preparation +### 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 +### 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. +- 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. +- 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_ +- 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_ +- 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 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_. -- Take note of the _AWS access portal sign-in URL_ (this is especially important if you changed it from the default). +- 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_ +- 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**. -## Caveats and Troubleshooting +:::::info -- Users need to already exist in AWS in order to use them through authentik. AWS will throw an error if it doesn't recognise the user. -- In case you're stuck, you can see the SSO logs in Amazon CloudTrail -> Event History. Look for `ExtenalIdPDirectoryLogin` - -Note: +- 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). +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. -In order to do so, take the following steps in your AWS Identity Center: +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 will give you an _SCIM Endpoint_ and a _Access Token_. Take note of these values. +- 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_ +- 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_ +- 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: @@ -154,12 +152,12 @@ return { } ``` -- 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_ +- 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_ +- 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. +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.