# 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](https://docs.p0.dev/integrations/directory-integrations/okta) 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](https://docs.p0.dev/p0-cli/p0-commands-and-usage/p0-request) - Request access without assuming the role
* [p0 login](https://docs.p0.dev/p0-cli/p0-commands-and-usage/p0-login) - Authenticate with P0
* [p0 ls](https://docs.p0.dev/p0-cli/p0-commands-and-usage/p0-ls) - List available roles and resources

### Related documentation

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