Skip to main content
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.
  1. Follow the guide 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”
    AWS IAM permissions tab with Create inline policy button
  3. Add the following permission policy. These permissions are required to be able to properly ingest all the data we require: 
    {
  "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": "*"
    }
  ]
}

​
Facilitating Access to Specific AWS Roles

Any OIDC-compliant identity provider can be used. Select your provider below for specific instructions.
  1. Visit the Okta Admin portal and navigate to Applications → Create App Integration.
  2. Select OIDC - OpenID Connect as the sign-in method and Web Application as the application type.
  3. Configure the sign-in redirect URI to point to https://svflow-oidc.api.serval.com/oidc/auth/callback.
  4. Configure assignment to control which users can authenticate.
  5. Once the application is saved, note the Client ID and Client Secret.
  6. In Serval, navigate to the AWS application instance and open the Settings tab.
  7. Under OIDC Provider, click Configure.
  8. Enter the Client ID, Client Secret, and OIDC Issuer URL.
For Okta, the OIDC issuer URL should be https://<your-okta-domain>.okta.com (e.g. https://acme.okta.com).
Perform this step for each AWS account that has roles you want accessible via Serval.
  1. In the AWS Console, navigate to IAM → Identity Providers → Add Provider.
  2. Select OpenID Connect as the provider type.
  3. For Provider URL, enter your OIDC issuer URL:
    • Okta: https://<your-okta-domain>.okta.com
    • Google: https://accounts.google.com
  4. For Audience, enter the Client ID of the OIDC application you created in the previous step.
  5. Click Add provider.
Do not include a trailing slash in the provider URL. The URL must exactly match the iss claim in the OIDC tokens, otherwise AWS will reject them with an audience mismatch error.
For each IAM role you want users to be able to request access to through Serval:
  1. Tag the role — Add a tag with the key serval (the value can be empty). Serval only ingests roles with this tag during resource sync.
  2. Attach permission policies — Add any AWS policies that define what the role can do when assumed by a user.
  3. Update the trust policy — Replace or add the following statement to allow Serval to assume the role via OIDC:
{
    "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"
                }
            }
        }
    ]
}
Replace the placeholder values:
  • ACCOUNT_ID — The ID of the AWS account the role belongs to.
  • IDP_ISSUER_URL — The provider URL configured in the previous step (e.g. acme.okta.com or accounts.google.com). Do not include https://.
  • SERVAL_OIDC_APP_CLIENT_ID — The Client ID of the OIDC application.
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::123456789012:oidc-provider/acme.okta.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "acme.okta.com:aud": "0oakcaaw2r3Cm0ICB1d7"
                }
            }
        }
    ]
}
If you use multiple identity providers, you can add a statement for each one in the same trust policy. This allows users from different IdPs to assume the same role.

​
How AWS role sessions work

When a user is granted access to an AWS role through Serval, temporary credentials are issued via AWS STS (AssumeRoleWithWebIdentity). These credentials have a fixed expiration set at the time they are issued — AWS does not support revoking STS credentials once they have been created. Session duration is determined by the shorter of:
  • The role’s Maximum session duration setting in AWS (defaults to 1 hour, configurable up to 12 hours)
  • The remaining time on the user’s access request in Serval
If the access request duration exceeds the role’s max session duration, the user will need to initiate a new session through Serval periodically to get fresh credentials.
Ending access early does not revoke active AWS credentials. When access is ended early in Serval (via the “End Access Early” button), Serval will prevent the user from initiating any new AWS sessions. However, any AWS credentials that have already been issued will remain valid until their STS expiration. This is an AWS limitation — STS temporary credentials cannot be revoked once issued. To minimize the window of lingering access, consider setting a shorter Maximum session duration on your AWS roles.