docs: update aws and gitlab docs

docs/integrations/services/aws/index.md

@@ -9,14 +9,14 @@
 
 The following placeholders will be used:
 
--   `passbook.company` is the FQDN of the passbook install.
+- `passbook.company` is the FQDN of the passbook install.
 
 Create an application in passbook 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`
--   Audience: `urn:amazon:webservices`
--   Issuer: `passbook`
--   Binding: `Post`
+- ACS URL: `https://signin.aws.amazon.com/saml`
+- Audience: `urn:amazon:webservices`
+- Issuer: `passbook`
+- Binding: `Post`
 
 You can of course use a custom signing certificate, and adjust durations.
 
@@ -24,10 +24,49 @@ You can of course use a custom signing certificate, and adjust durations.
 
 Create a role with the permissions you desire, and note the ARN.
 
-AWS requires two custom PropertyMappings; `Role` and `RoleSessionName`. Create them as following:
+After you've created the Property Mappings below, add them to the Provider.
 
-![](./property-mapping-role.png)
+Create an application, assign policies, and assign this provider.
 
-![](./property-mapping-role-session-name.png)
+Export the metadata from passbook, and create an Identity Provider [here](https://console.aws.amazon.com/iam/home#/providers).
 
-Afterwards export the metadata from passbook, and create an 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/passbook"
+```
+
+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/passbook"
+```
+
+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/passbook",
+    "arn:aws:iam::123412341234:role/role_b,arn:aws:iam::123412341234:saml-provider/passbook",
+    "arn:aws:iam::123412341234:role/role_c,arn:aws:iam::123412341234:saml-provider/passbook",
+]
+```
+
+### 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
+```