# p0 aws role assume

### Overview

Assume an AWS IAM role through Okta SAML federation and obtain temporary AWS credentials.

* Request just-in-time access to an AWS role (enabled by default).
* Authenticate via Okta SAML to obtain temporary AWS credentials.
* Output shell export commands for `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN`.
* Use command substitution to set credentials in your current shell session.
* Credentials are cached locally for one hour to avoid repeated authentication.

### Prerequisites

* **Logged-in user**: Run `p0 login <org>` first.
* **AWS account configured**: P0 must be installed on the target AWS account with federated identity provider (Okta SAML) login.
* **Okta directory integration**: Your organization must have an [Okta directory integration](/integrations/directory-integrations/okta.md) installed.
* **Role assignment**: Okta must assign the requested role to your user.

{% hint style="info" %}
This command is only available for AWS accounts configured with **federated identity provider** login via Okta SAML. The CLI automatically detects your account type and shows either `p0 aws role` (for Okta SAML federation) or `p0 aws permission-set` (for AWS Identity Center) based on your configuration. Run `p0 aws --help` to see which subcommands are available for your account.
{% endhint %}

### Syntax

```
p0 aws [options] role assume <role> [--request | --no-request]
```

### Arguments

| Argument | Type   | Required | Description                 |
| -------- | ------ | -------- | --------------------------- |
| `<role>` | string | Yes      | AWS IAM role name to assume |

### Options

| Option            | Type    | Default | Description                                                    |
| ----------------- | ------- | ------- | -------------------------------------------------------------- |
| `--account <id>`  | string  | -       | AWS account ID or alias. Required if P0 runs on many accounts. |
| `--reason <text>` | string  | -       | Justification for audit and approver context                   |
| `--request`       | boolean | `true`  | Create a P0 access request before assuming the role            |
| `--no-request`    | boolean | -       | Skip the access request (use existing access)                  |
| `--debug`         | boolean | `false` | Print debug information                                        |

{% hint style="info" %}
You can set `P0_AWS_ACCOUNT` environment variable instead of using `--account` for every command.
{% endhint %}

### Output

The command outputs shell export commands for AWS credentials:

```bash
export AWS_ACCESS_KEY_ID=ASIA...
export AWS_SECRET_ACCESS_KEY=...
export AWS_SESSION_TOKEN=...
export AWS_SECURITY_TOKEN=...
```

When run in an interactive terminal, the output includes usage instructions. When piped or used in scripts, only the export commands are printed.

### Examples

#### Assume a role with automatic access request

```bash
$(p0 aws role assume MyAdminRole --account 123456789012 --reason "Deploy hotfix")
```

Uses command substitution to set AWS credentials in your current shell.

#### Assume a role without creating a new request

```bash
$(p0 aws role assume MyReadOnlyRole --no-request)
```

Skip the P0 request if you already have active access to the role.

#### View credentials without setting them

```bash
p0 aws role assume MyRole --account 123456789012
```

Prints the export commands without executing them. Copy and paste to set credentials manually.

#### Use with AWS CLI

```bash
$(p0 aws role assume MyRole --account 123456789012)
aws s3 ls
```

After assuming the role, run AWS CLI commands with the provisioned credentials.

### How it works

1. **P0 authentication**: Validates your P0 session (prompts for login if expired).
2. **Access request** (if `--request`): Creates a P0 access request and waits up to 5 minutes for approval and provisioning.
3. **Okta token exchange**: Exchanges your OIDC tokens for an Okta Web SSO token.
4. **SAML assertion**: Retrieves a SAML assertion from Okta containing your role assignments.
5. **AWS STS**: Calls AWS `AssumeRoleWithSAML` to obtain temporary credentials.
6. **Credential output**: Prints shell export commands for the AWS credentials.

{% hint style="info" %}
Credentials are valid for 1 hour. The command caches credentials locally to avoid repeated authentication within that period.
{% endhint %}

### Error messages

| Error                                                    | Cause                                                                  | Solution                                                                                                                 |
| -------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `Account {label} is not configured for Okta SAML login.` | AWS account uses Identity Center (IDC) instead of Okta SAML federation | This account requires `p0 aws permission-set assume`. Re-run `p0 aws --help` to see available commands for your account. |
| `Role {role} not available. Available roles: ...`        | Role not assigned to your user in Okta                                 | Contact your administrator to assign the role, or request access first                                                   |
| `P0 is not installed on any AWS account`                 | No AWS accounts configured in P0                                       | Ask your P0 administrator to install the AWS integration                                                                 |
| `P0 is not installed on AWS account {account}`           | Specified account not found                                            | Verify the account ID or alias                                                                                           |
| `Please select a unique AWS account with --account`      | Multiple accounts configured                                           | Specify which account with `--account`                                                                                   |
| `Your Okta session has expired.`                         | Okta tokens expired                                                    | Log out of Okta in your browser and run the command again                                                                |
| `Your request was denied`                                | P0 access request denied by approver                                   | Contact your approver or request with a different reason                                                                 |
| `Your request did not complete within 5 minutes.`        | Request approval timed out                                             | Check your notification channel for approval status                                                                      |

### Related commands

* [p0 request](/p0-cli/p0-commands-and-usage/p0-request.md) - Request access without assuming the role
* [p0 login](/p0-cli/p0-commands-and-usage/p0-login.md) - Authenticate with P0
* [p0 ls](/p0-cli/p0-commands-and-usage/p0-ls.md) - List available roles and resources

### Related documentation

* [AWS integration](/integrations/resource-integrations/aws.md) - Configure P0 for AWS
* [Okta directory integration](/integrations/directory-integrations/okta.md) - Set up Okta federation
* [Requesting AWS access](/integrations/resource-integrations/aws/requesting-access.md) - Request types for AWS


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.p0.dev/p0-cli/p0-commands-and-usage/p0-aws-role-assume.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.