> ## Documentation Index
> Fetch the complete documentation index at: https://serval-hannah-docs-custom-access.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Role Access

Serval can be configured to give users time-bound access to specific AWS roles.

Roles must be configured for ingestion into Serval, and provided with a policy that allows the role to be assumed using an OIDC token which will be generated by your identity provider.

## Ingestion Configuration

Perform the following setup for *each* AWS account for which Serval will ingest roles and facilitate access.

<Accordion title="AWS Account Ingestion Role configuration" icon="sparkles">
  1. Follow [the guide](/sections/integrations/aws) to add give Serval access to an AWS role in your account.
  2. Once the role is created, navigate to permissions and select “Create inline policy”\\
       <img src="https://mintlify.s3.us-west-1.amazonaws.com/serval-hannah-docs-custom-access/images/aws/image(60).png" alt="Image(60) Pn" />
  3. Add the following permission policy. These permissions are required to be able to properly ingest all the data we require:

     ```javascript theme={null}
     {
       "Version": "2012-10-17",
       "Statement": [
         {
           "Effect": "Allow",
           "Action": [
             "iam:ListRoleTags",
             "iam:ListRoles",
             "iam:ListRolePolicies",
             "iam:ListAttachedRolePolicies",
             "iam:GetRolePolicy",
             "iam:GetPolicy",
             "iam:GetPolicyVersion",
             "iam:GetRole",
             "rds:DescribeDBInstances",
             "rds:DescribeDBClusters",
             "ec2:DescribeInstances",
             "eks:DescribeCluster",
             "eks:ListClusters"
           ],
           "Resource": "*"
         }
       ]
     }
     ```
</Accordion>

## Facilitating Access to Specific AWS Roles

<Accordion title="Create a new OIDC application" icon="sparkles">
  * The following steps are for creating a new OIDC application in Okta, but any OIDC provider can be used.
  * Visit the Okta Admin portal > Applications > Create App Integration
  * Ensure it is an OIDC web application:
  * Configure the correct URLs for sign-in redirect and logout. These should point to  [https://svflow-oidc.api.serval.com/oidc/auth/callback](https://svflow-oidc.api.serval.com/oidc/auth/callback) and [https://svflow-oidc.api.serval.com/oidc/auth/logout](https://svflow-oidc.api.serval.com/oidc/auth/logout) respectively.
  * Configure assignment
  * Once the application is saved, you will have a **Client ID** and **Client Secret** value
  * You will now need to add these values to Serval.
  * Navigate to the AWS application instance in the Serval UI.
  * Ensure that you have enabled "Access Management" functionality for the AWS application instance.
  * In "Access Management" settings, select "Configure" next to "OIDC Provider".
  * Add the values from Okta to Serval. For Okta, ensure that the OIDC issuer URL is `https://<your-okta-domain>.okta.com/oauth2`, as this is the correct Okta endpoint for OIDC authentication.
</Accordion>

<Accordion title="Add the OIDC application as an identity provider in AWS" icon="sparkles">
  * You will need to do this for *each* account which has roles you want accessible via Serval.
  * Visit IAM > Identity Providers.
  * Select “Add Provider” and configure the provider accordingly
  * The provider URL will be your OIDC host URL.
  * The audience will be the **Client ID** of the OIDC application created previously.
</Accordion>

<Accordion title="Configure AWS roles so that Serval can grant temporary access to them" icon="sparkles">
  * For each role / account that you wish Serval to ingest and facilitate access for, you will need to do the following.
  * Add a “serval” tag to the role. The key is “serval”, the value can be empty.
  * Attach any polices that you wish to be granted when the role is granted to a user.
  * Attach the following trust policy:

    ```json theme={null}
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Principal": {
                    "Federated": "arn:aws:iam::${ACCOUNT_ID}:oidc-provider/${IDP_ISSUER_URL}"
                },
                "Action": "sts:AssumeRoleWithWebIdentity",
                "Condition": {
                    "StringEquals": {
                        "${IDP_ISSUER_URL}:aud": "${SERVAL_OIDC_APP_CLIENT_ID}"
                    }
                }
            }
        ]
    }
    ```
  * The values are as follows:
    * `ACCOUNT_ID` — The ID of the current AWS account being configured.
    * `IDP_ISSUER_URL` — The URL of your IdP instance which was configured as an identity provider above.
    * `SERVAL_OIDC_APP_CLIENT_ID` — The **Client ID** of the application created in your IdP.
  * So for example, the policy may look like this:

    ```json theme={null}
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Principal": {
                    "Federated": "arn:aws:iam::879395235829:oidc-provider/your-domain.okta.com"
                },
                "Action": "sts:AssumeRoleWithWebIdentity",
                "Condition": {
                    "StringEquals": {
                        "your-domain.okta.com:aud": "0oakcaaw2r3Cm0ICB1d7"
                    }
                }
            }
        ]
    }
    ```
</Accordion>