### Install Alohomora CLI

Source: https://context7.com/viasat/alohomora/llms.txt

Installs the Alohomora CLI tool from PyPI. The optional '[fido2]' extra enables support for WebAuthn/FIDO2 hardware security keys.

```bash
pip install alohomora

pip install alohomora[fido2]
```

--------------------------------

### Alohomora Configuration File Example

Source: https://context7.com/viasat/alohomora/llms.txt

Shows the structure of the ~/.alohomora configuration file, including default settings, named profiles for different environments, and account mapping for role selection.

```ini
# Basic configuration
[default]
idp-url = https://sso.example.com/idp/profile/SAML2/Unsolicited/SSO?providerId=urn:amazon:webservices
username = myuser
auth-method = push
aws-profile = saml

# Profile with automatic role selection
[production]
idp-url = https://sso.example.com/idp/profile/SAML2/Unsolicited/SSO?providerId=urn:amazon:webservices
username = myuser
auth-method = push
account = 123456789012
role-name = sso-admins
aws-profile = prod

# GovCloud profile
[govcloud]
idp-url = https://sso.example.com/idp/profile/SAML2/Unsolicited/SSO?providerId=urn:amazon:webservices
username = myuser
auth-method = push
aws-partition = aws-us-gov
account = 987654321098
role-name = govcloud-admin

# Map account IDs to friendly names for role selection prompts
[account_map]
123456789012 = Dev Account
210987654321 = Prod Account
345678901234 = Staging Account
```

--------------------------------

### Alohomora CLI Usage Examples

Source: https://context7.com/viasat/alohomora/llms.txt

Demonstrates various command-line options for the Alohomora CLI, including specifying username, IdP URL, AWS profile, session duration, role selection, MFA methods, and debug logging.

```bash
# Basic usage - prompts for password and MFA
alohomora

# Specify username and IdP URL directly
alohomora --username myuser --idp-url "https://sso.example.com/idp/profile/SAML2/Unsolicited/SSO?providerId=urn:amazon:webservices"

# Use a specific AWS profile for saving credentials
alohomora --aws-profile production

# Set session duration (supports h/m/s suffixes, default 1h, max 12h)
alohomora --duration 4h

# Auto-select account and role without prompts
alohomora --account 123456789012 --role-name sso-admins

# Specify Duo MFA method (push, call, or passcode)
alohomora --auth-method push

# Select specific Duo device
alohomora --auth-device "iPhone"

# Use AWS GovCloud partition
alohomora --aws-partition aws-us-gov

# Use a named alohomora configuration profile
alohomora --alohomora-profile production

# Enable debug logging
alohomora --debug

# Check version
alohomora --version
```

--------------------------------

### Alohomora CLI Usage

Source: https://context7.com/viasat/alohomora/llms.txt

Examples of how to use the Alohomora command-line interface for various authentication scenarios.

```APIDOC
## Alohomora CLI Usage

### Description
Examples of how to use the Alohomora command-line interface for various authentication scenarios, including specifying usernames, IdP URLs, AWS profiles, session durations, MFA methods, and debug logging.

### Command
alohomora

### Examples

Basic usage (prompts for password and MFA):
```bash
alohomora
```

Specify username and IdP URL:
```bash
alohomora --username myuser --idp-url "https://sso.example.com/idp/profile/SAML2/Unsolicited/SSO?providerId=urn:amazon:webservices"
```

Use a specific AWS profile:
```bash
alohomora --aws-profile production
```

Set session duration (e.g., 4 hours):
```bash
alohomora --duration 4h
```

Auto-select account and role:
```bash
alohomora --account 123456789012 --role-name sso-admins
```

Specify Duo MFA method (push, call, or passcode):
```bash
alohomora --auth-method push
```

Select specific Duo device:
```bash
alohomora --auth-device "iPhone"
```

Use AWS GovCloud partition:
```bash
alohomora --aws-partition aws-us-gov
```

Use a named alohomora configuration profile:
```bash
alohomora --alohomora-profile production
```

Enable debug logging:
```bash
alohomora --debug
```

Check version:
```bash
alohomora --version
```
```

--------------------------------

### Python API: Get AWS Credentials

Source: https://context7.com/viasat/alohomora/llms.txt

Uses the alohomora.keys.get() function to obtain temporary AWS credentials by assuming an IAM role with a SAML assertion. Requires role ARN, principal ARN, assertion, and session duration.

```python
import alohomora.keys

# Get temporary AWS credentials from a SAML assertion
# Parameters:
#   role_arn: The ARN of the IAM role to assume
#   principal_arn: The ARN of the SAML provider
#   assertion: Base64-encoded SAML assertion from IdP
#   duration: Session duration in seconds (900-43200)

role_arn = "arn:aws:iam::123456789012:role/sso-admins"
principal_arn = "arn:aws:iam::123456789012:saml-provider/sso"
assertion = "<base64-encoded-saml-assertion>"
duration = 3600  # 1 hour

token = alohomora.keys.get(role_arn, principal_arn, assertion, duration)

# token contains:
# {
#     'Credentials': {
#         'AccessKeyId': 'ASIA...',
#         'SecretAccessKey': '...',
#         'SessionToken': '...',
#         'Expiration': datetime(...)
#     },
#     'AssumedRoleUser': {...},
#     'Subject': '...',
#     ...
# }
print(f"Access Key: {token['Credentials']['AccessKeyId']}")
```

--------------------------------

### Alohomora Configuration File

Source: https://context7.com/viasat/alohomora/llms.txt

Details on the structure and usage of the `~/.alohomora` configuration file for persistent settings and profiles.

```APIDOC
## Alohomora Configuration File (`~/.alohomora`)

### Description
Configuration file to store persistent settings and define multiple profiles for different AWS accounts or environments. Supports various parameters to customize authentication and credential saving.

### File Path
`~/.alohomora`

### Format
INI file format

### Example Configuration

Basic configuration:
```ini
[default]
idp-url = https://sso.example.com/idp/profile/SAML2/Unsolicited/SSO?providerId=urn:amazon:webservices
username = myuser
auth-method = push
aws-profile = saml
```

Profile with automatic role selection:
```ini
[production]
idp-url = https://sso.example.com/idp/profile/SAML2/Unsolicited/SSO?providerId=urn:amazon:webservices
username = myuser
auth-method = push
account = 123456789012
role-name = sso-admins
aws-profile = prod
```

GovCloud profile:
```ini
[govcloud]
idp-url = https://sso.example.com/idp/profile/SAML2/Unsolicited/SSO?providerId=urn:amazon:webservices
username = myuser
auth-method = push
aws-partition = aws-us-gov
account = 987654321098
role-name = govcloud-admin
```

Map account IDs to friendly names for role selection prompts:
```ini
[account_map]
123456789012 = Dev Account
210987654321 = Prod Account
345678901234 = Staging Account
```

### Available Settings
- `idp-url`: The URL of the Identity Provider.
- `username`: The username for authentication.
- `auth-method`: The preferred Duo MFA method (e.g., `push`, `call`, `passcode`).
- `aws-profile`: The name of the AWS profile to save credentials under.
- `account`: The AWS account ID.
- `role-name`: The IAM role name to assume.
- `aws-partition`: The AWS partition to use (e.g., `aws`, `aws-cn`, `aws-us-gov`).
- `duration`: Session duration (e.g., `1h`, `30m`).
- `auth-device`: Specific Duo device to use.
- `debug`: Enable debug logging (true/false).
```

--------------------------------

### Configure AWS Partition Settings

Source: https://github.com/viasat/alohomora/blob/master/README.md

Manually specify the AWS partition (e.g., commercial or GovCloud) when using a single IdP for multiple environments. This can be set in the configuration file or via the CLI.

```ini
[default]
aws-partition = aws

[awsgov]
aws-partition = aws-us-gov
```

```bash
alohomora --aws-partition aws-us-gov
```

--------------------------------

### Python API: alohomora.keys.save()

Source: https://context7.com/viasat/alohomora/llms.txt

Function to save obtained AWS credentials to the `~/.aws/credentials` file under a specified profile.

```APIDOC
## Python API: `alohomora.keys.save()`

### Description
Saves the temporary AWS credentials obtained from `alohomora.keys.get()` (or any similar STS `AssumeRoleWithSAML` response) into the standard AWS credentials file (`~/.aws/credentials`). This allows seamless usage of the AWS CLI and SDKs with the saved profile.

### Method Signature
```python
alohomora.keys.save(token: dict, profile: str = 'default')
```

### Parameters
- **token** (dict) - Required - The dictionary containing AWS temporary credentials, typically the output from `alohomora.keys.get()` or a similar STS call. Must contain a `Credentials` key with `AccessKeyId`, `SecretAccessKey`, and `SessionToken`.
- **profile** (string) - Optional - The name of the AWS CLI profile under which to save the credentials. Defaults to `'default'`.

### Request Example
```python
import alohomora.keys

# Assume 'token' is the dictionary returned by alohomora.keys.get()
token = {
    'Credentials': {
        'AccessKeyId': 'ASIAXXXXXXXXXXX',
        'SecretAccessKey': 'secretkey123',
        'SessionToken': 'sessiontoken...',
        'Expiration': '2023-10-27T10:00:00Z'
    },
    'AssumedRoleUser': {
        'AssumedRoleId': 'AROAXXXXXXXX:myuser',
        'Arn': 'arn:aws:sts::123456789012:assumed-role/sso-admins/myuser'
    }
}

# Save credentials to the 'saml' profile
alohomora.keys.save(token, profile='saml')

# Save credentials to a custom 'production' profile
alohomora.keys.save(token, profile='production')

# After saving, you can use these profiles with the AWS CLI:
# aws --profile saml s3 ls
# aws --profile production ec2 describe-instances
```

### File Modification
This function modifies the `~/.aws/credentials` file. If the specified profile already exists, its contents will be overwritten with the new credentials.
```

--------------------------------

### Utility Functions for Time and Role Formatting

Source: https://context7.com/viasat/alohomora/llms.txt

Provides helper functions to convert duration strings into seconds and format AWS role ARNs for human-readable display using account mappings.

```python
from alohomora.main import to_seconds, format_role

# Convert duration strings to seconds
print(to_seconds("1h"))

# Format role ARN with account names
account_map = {"123456789012": "Dev Account"}
role_arn = "arn:aws:iam::123456789012:role/sso-admins"
formatted = format_role(role_arn, account_map)
print(formatted)
```

--------------------------------

### Python API: alohomora.keys.get()

Source: https://context7.com/viasat/alohomora/llms.txt

Function to obtain temporary AWS credentials from a SAML assertion using AWS STS AssumeRoleWithSAML.

```APIDOC
## Python API: `alohomora.keys.get()`

### Description
Obtains temporary AWS credentials by calling the AWS Security Token Service (STS) `AssumeRoleWithSAML` API. This function takes a SAML assertion obtained from an Identity Provider (IdP) and returns temporary credentials for a specified IAM role.

### Method Signature
```python
alohomora.keys.get(role_arn: str, principal_arn: str, assertion: str, duration: int = 3600) -> dict
```

### Parameters
- **role_arn** (string) - Required - The Amazon Resource Name (ARN) of the IAM role to assume.
- **principal_arn** (string) - Required - The ARN of the SAML provider configured in AWS IAM.
- **assertion** (string) - Required - The Base64-encoded SAML assertion string received from the Identity Provider.
- **duration** (integer) - Optional - The desired duration of the temporary session in seconds. Defaults to 3600 seconds (1 hour). Maximum allowed is 43200 seconds (12 hours).

### Request Example
```python
import alohomora.keys

role_arn = "arn:aws:iam::123456789012:role/sso-admins"
principal_arn = "arn:aws:iam::123456789012:saml-provider/sso"
assertion = "<base64-encoded-saml-assertion>"
duration = 3600  # 1 hour

token = alohomora.keys.get(role_arn, principal_arn, assertion, duration)

print(f"Access Key ID: {token['Credentials']['AccessKeyId']}")
print(f"Session Token: {token['Credentials']['SessionToken']}")
print(f"Expiration: {token['Credentials']['Expiration']}")
```

### Response Example (Success)
```json
{
    "Credentials": {
        "AccessKeyId": "ASIA...",
        "SecretAccessKey": "...",
        "SessionToken": "...",
        "Expiration": "2023-10-27T10:00:00Z"
    },
    "AssumedRoleUser": {
        "AssumedRoleId": "AROA...:myuser",
        "Arn": "arn:aws:sts::123456789012:assumed-role/sso-admins/myuser"
    },
    "Subject": "myuser",
    "Provider": "sso.example.com",
    "PackedPolicySize": 456,
    "ResponseMetadata": {
        "RequestId": "example-request-id"
    }
}
```
```

--------------------------------

### Configure AWS Account Mapping

Source: https://github.com/viasat/alohomora/blob/master/README.md

Map numeric AWS account IDs to human-readable friendly names within the Alohomora configuration file. This improves readability when selecting roles from a list.

```ini
[account_map]
123456789012 = Dev Account
210987654321 = Prod Account
```

--------------------------------

### Authenticate with Duo MFA and Retrieve AWS Credentials

Source: https://context7.com/viasat/alohomora/llms.txt

Demonstrates the use of DuoRequestsProvider to perform two-factor authentication and obtain temporary AWS credentials. It handles both single-factor and multi-factor login flows.

```python
import alohomora.req
import getpass
import alohomora.saml
import alohomora.keys

idp_url = "https://sso.example.com/idp/profile/SAML2/Unsolicited/SSO?providerId=urn:amazon:webservices"
auth_method = "push"

provider = alohomora.req.DuoRequestsProvider(idp_url, auth_method)
(success, response) = provider.login_one_factor("myuser", getpass.getpass)

if not success:
    (success, assertion) = provider.login_two_factor(response, None)
else:
    assertion = response

if success:
    roles = alohomora.saml.get_roles(assertion)
    role_arn, principal_arn = roles[0].split(',')
    token = alohomora.keys.get(role_arn, principal_arn, assertion, 3600)
    alohomora.keys.save(token, profile='saml')
```

--------------------------------

### Set Automatic Role Selection

Source: https://github.com/viasat/alohomora/blob/master/README.md

Configure Alohomora to automatically select a specific AWS account and role upon authentication. This is defined within the [default] section of the configuration file.

```ini
[default]
idp-url = https://sso.example.com/idp/profile/SAML2/Unsolicited/SSO?providerId=urn:amazon:webservices
auth-method = push
account = 112233445566
role-name = sso-admins
```

--------------------------------

### Python API: Save AWS Credentials

Source: https://context7.com/viasat/alohomora/llms.txt

Utilizes the alohomora.keys.save() function to persist temporary AWS credentials to the standard AWS credentials file (~/.aws/credentials) under a specified profile name.

```python
import alohomora.keys

# Save credentials to ~/.aws/credentials under a named profile
# Parameters:
#   token: The response from STS AssumeRoleWithSAML (from keys.get())
#   profile: AWS CLI profile name to save credentials under

token = {
    'Credentials': {
        'AccessKeyId': 'ASIAXXXXXXXXXXX',
        'SecretAccessKey': 'secretkey123',
        'SessionToken': 'sessiontoken...',
    }
}

# Save to 'saml' profile (default)
alohomora.keys.save(token, profile='saml')

# Save to custom profile
alohomora.keys.save(token, profile='production')

# After saving, use with AWS CLI:
# aws --profile production s3 ls
# aws --profile production ec2 describe-instances
```

--------------------------------

### Parse SAML Assertion for AWS IAM Roles

Source: https://context7.com/viasat/alohomora/llms.txt

Extracts available AWS IAM roles from a base64-encoded SAML assertion. This function returns a list of strings containing role and principal ARNs.

```python
import alohomora.saml

assertion = "<base64-encoded-saml-assertion>"
roles = alohomora.saml.get_roles(assertion)

for role in roles:
    role_arn, principal_arn = role.split(',')
    account_id = role_arn.split(':')[4]
    role_name = role_arn.split('/')[-1]
    print(f"Account {account_id}: {role_name}")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.