idp2aws 0.2.0__py3-none-any.whl

idp2aws/__init__.py

@@ -0,0 +1,3 @@
+"""Package for getting short-lived AWS keys by signing in to an IdP in a browser."""
+
+__version__ = "0.2.0"

idp2aws/aws.py

@@ -0,0 +1,205 @@
+"""Module for swapping a SAML response for AWS keys, and storing them."""
+
+import configparser
+import io
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from urllib.parse import urlencode
+from urllib.request import urlopen
+
+import boto3
+from botocore import UNSIGNED
+from botocore.config import Config
+
+from idp2aws.files import write_file
+from idp2aws.saml import Assertion, Role
+
+FEDERATION_URL = "https://signin.aws.amazon.com/federation"
+# Keys this close to expiry count as expired, so a command started with them
+# does not fail halfway through.
+EXPIRY_MARGIN = timedelta(minutes=5)
+
+
+@dataclass
+class Credentials:
+    """Short-lived AWS keys.
+
+    :param access_key_id: The ``ASIA...`` key id.
+    :param secret_access_key: The secret key.
+    :param session_token: The session token that goes with the keys.
+    :param expiration: When the keys stop working.
+    """
+
+    access_key_id: str
+    secret_access_key: str
+    session_token: str
+    expiration: datetime
+
+    @property
+    def is_expired(self) -> bool:
+        """Tell whether the keys have stopped working, or soon will.
+
+        :return: ``True`` from ``EXPIRY_MARGIN`` before the expiry time.
+        """
+        return datetime.now(timezone.utc) >= self.expiration - EXPIRY_MARGIN
+
+    def as_env(self) -> dict[str, str]:
+        """Get the keys as the environment variables AWS tools read.
+
+        :return: Variable names and values.
+        """
+        return {
+            "AWS_ACCESS_KEY_ID": self.access_key_id,
+            "AWS_SECRET_ACCESS_KEY": self.secret_access_key,
+            "AWS_SESSION_TOKEN": self.session_token,
+        }
+
+    def as_json(self) -> str:
+        """Get the keys as JSON in the shape ``credential_process`` expects.
+
+        :return: The JSON text.
+        """
+        return json.dumps({
+            "Version": 1,
+            "AccessKeyId": self.access_key_id,
+            "SecretAccessKey": self.secret_access_key,
+            "SessionToken": self.session_token,
+            "Expiration": self.expiration.isoformat(),
+        })
+
+
+def get_sts_region(destination: str | None) -> str:
+    """Choose the region for the STS call from where the response is going.
+
+    :param destination: AWS sign-in address from the SAML response. Its
+        domain tells us the partition: commercial, GovCloud or China.
+    :return: A region in that partition.
+    """
+    if destination and "amazonaws-us-gov" in destination:
+        return "us-gov-west-1"
+    if destination and "amazonaws.cn" in destination:
+        return "cn-north-1"
+    return "us-east-1"
+
+
+def assume_role(
+    role: Role, assertion: Assertion, duration_secs: int, region: str
+) -> Credentials:
+    """Ask AWS STS for keys in exchange for the SAML response.
+
+    The call needs no AWS keys, so the request is not signed.
+
+    :param role: Role to assume.
+    :param assertion: SAML response that lists the role.
+    :param duration_secs: How long the keys should last.
+    :param region: Region of the STS endpoint.
+    :return: The new keys.
+    :raises botocore.exceptions.ClientError: If STS refuses.
+    """
+    unsigned = Config(signature_version=UNSIGNED)
+    sts = boto3.client("sts", region_name=region, config=unsigned)
+    response = sts.assume_role_with_saml(
+        RoleArn=role.role_arn,
+        PrincipalArn=role.principal_arn,
+        SAMLAssertion=assertion.raw,
+        DurationSeconds=duration_secs,
+    )
+    keys = response["Credentials"]
+    return Credentials(
+        access_key_id=keys["AccessKeyId"],
+        secret_access_key=keys["SecretAccessKey"],
+        session_token=keys["SessionToken"],
+        expiration=keys["Expiration"],
+    )
+
+
+def get_credentials_file() -> Path:
+    """Find the AWS credentials file, honouring ``AWS_SHARED_CREDENTIALS_FILE``.
+
+    :return: Path to the file. It may not exist yet.
+    """
+    default = Path.home() / ".aws" / "credentials"
+    return Path(os.environ.get("AWS_SHARED_CREDENTIALS_FILE", default))
+
+
+def load_credentials(profile: str, expiration: datetime) -> Credentials | None:
+    """Read keys saved to a profile earlier.
+
+    :param profile: Profile in the AWS credentials file.
+    :param expiration: When the keys expire. The file does not say.
+    :return: The keys, or ``None`` if the profile is missing or incomplete.
+    """
+    parser = _read_ini(get_credentials_file())
+    if profile not in parser:
+        return None
+    section = parser[profile]
+    try:
+        return Credentials(
+            access_key_id=section["aws_access_key_id"],
+            secret_access_key=section["aws_secret_access_key"],
+            session_token=section["aws_session_token"],
+            expiration=expiration,
+        )
+    except KeyError:
+        return None
+
+
+def save_credentials(profile: str, credentials: Credentials) -> None:
+    """Write keys to a profile in the AWS credentials file.
+
+    Other profiles are kept. Comments in the file are not, because
+    ``configparser`` drops them. Only you can read the file afterwards.
+
+    :param profile: Profile to write. Anything already in it is replaced.
+    :param credentials: Keys to write.
+    """
+    path = get_credentials_file()
+    parser = _read_ini(path)
+    parser[profile] = {
+        "aws_access_key_id": credentials.access_key_id,
+        "aws_secret_access_key": credentials.secret_access_key,
+        "aws_session_token": credentials.session_token,
+    }
+    text = io.StringIO()
+    parser.write(text)
+    write_file(path, text.getvalue(), mode=0o600)
+
+
+def get_console_url(credentials: Credentials) -> str:
+    """Build a link that opens the AWS console with these keys.
+
+    Only works in the commercial AWS partition.
+
+    :param credentials: Keys to sign in with.
+    :return: A one-time sign-in link, valid for 15 minutes.
+    :raises OSError: If the AWS sign-in service cannot be reached.
+    """
+    session = json.dumps({
+        "sessionId": credentials.access_key_id,
+        "sessionKey": credentials.secret_access_key,
+        "sessionToken": credentials.session_token,
+    })
+    query = urlencode({"Action": "getSigninToken", "Session": session})
+    with urlopen(f"{FEDERATION_URL}?{query}", timeout=10) as response:
+        token = json.load(response)["SigninToken"]
+    query = urlencode({
+        "Action": "login",
+        "Issuer": "idp2aws",
+        "Destination": "https://console.aws.amazon.com/",
+        "SigninToken": token,
+    })
+    return f"{FEDERATION_URL}?{query}"
+
+
+def _read_ini(path: Path) -> configparser.ConfigParser:
+    """Read an INI file, treating ``%`` as plain text.
+
+    :param path: File to read. A missing file gives an empty parser.
+    :return: The parsed file.
+    """
+    parser = configparser.ConfigParser(interpolation=None)
+    parser.read(path)
+    return parser

idp2aws/browser.py

@@ -0,0 +1,183 @@
+"""Module for signing in with a real browser and catching the SAML response.
+
+The browser opens the start URL of your IdP. You sign in as usual, with any
+kind of 2-Step Verification. Then the IdP posts the SAML response to the AWS
+sign-in page. Two things can happen next:
+
+* You have more than one role and no role is chosen yet. We let the post go
+  to AWS, and AWS shows its role page, with the accounts sorted by name. When
+  you click *Sign In*, the page posts the SAML response again, with the role
+  that you picked. We stop this second post.
+* In all other cases, we stop the first post.
+
+The browser profile stays between runs. While your IdP session is active,
+the window opens and closes without input from you.
+"""
+
+import re
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from urllib.parse import parse_qs
+
+from playwright.sync_api import BrowserContext, Request, Route, sync_playwright
+from playwright.sync_api import Error as PlaywrightError
+
+from idp2aws import saml
+from idp2aws.settings import HOME
+
+PROFILE_DIR = HOME / "browser-profile"
+AWS_SAML_URL = re.compile(
+    r"^https://([a-z0-9-]+\.)?signin\."
+    r"(aws\.amazon\.com|amazonaws-us-gov\.com|amazonaws\.cn)/saml/?(\?.*)?$"
+)
+# Playwright starts Chrome with these by default. They make Chrome keep the
+# cookies in the browser profile with a fixed key, instead of a key from the
+# macOS Keychain or the Linux keyring.
+WEAK_COOKIE_KEY_ARGS = ["--use-mock-keychain", "--password-store=basic"]
+SORT_ACCOUNTS_SCRIPT = """
+if (location.pathname === "/saml" && location.hostname.includes("signin.")) {
+  document.addEventListener("DOMContentLoaded", () => {
+    const fieldset = document.querySelector("#saml_form fieldset");
+    if (!fieldset) return;
+    const name = (account) =>
+      (account.querySelector(".saml-account-name")?.textContent ?? "")
+        .replace("Account:", "").trim();
+    const accounts = [...fieldset.querySelectorAll(":scope > div.saml-account")];
+    accounts.sort((a, b) => name(a).localeCompare(name(b)));
+    fieldset.append(...accounts);
+  });
+}
+"""
+
+
+class LoginError(Exception):
+    """Raise when the browser login ends without a SAML response."""
+
+
+@dataclass
+class BrowserLogin:
+    """What the browser login produced.
+
+    :param saml_response: The base64 ``SAMLResponse`` value.
+    :param picked_role_arn: Role picked on the AWS page, or ``None`` if the
+        page was not shown.
+    """
+
+    saml_response: str
+    picked_role_arn: str | None
+
+
+def log_in(
+    start_url: str,
+    browser: str = "chrome",
+    role_arn: str | None = None,
+    timeout_secs: int = 300,
+) -> BrowserLogin:
+    """Open a browser at the IdP and wait for the login to reach AWS.
+
+    :param start_url: Start URL of your IdP for AWS.
+    :param browser: ``chrome`` or ``msedge`` for your installed Chrome or
+        Edge, or ``chromium`` for the one from ``playwright install chromium``.
+    :param role_arn: Role already chosen. If set, the AWS role page is skipped.
+    :param timeout_secs: How long to wait for you to finish.
+    :return: The SAML response, and the role if you picked one.
+    :raises LoginError: If the window is closed or the time runs out.
+    """
+    result = []
+
+    def catch(route: Route, request: Request) -> None:
+        if request.method != "POST":
+            route.fallback()
+            return
+        form = parse_qs(request.post_data or "")
+        saml_response = form.get("SAMLResponse", [""])[0]
+        picked = form.get("roleIndex", [None])[0]
+        if not (picked or role_arn) and _has_several_roles(saml_response):
+            route.fallback()  # Let AWS show its role page.
+            return
+        result.append(BrowserLogin(saml_response, picked))
+        route.abort()
+
+    with sync_playwright() as playwright:
+        try:
+            context = playwright.chromium.launch_persistent_context(
+                PROFILE_DIR,
+                channel=None if browser == "chromium" else browser,
+                headless=False,
+                # Playwright turns the sandbox off by default, and Chrome then
+                # warns about the "--no-sandbox" flag.
+                chromium_sandbox=True,
+                # "--enable-automation" shows the "controlled by automated test
+                # software" bar, which can make Google say the browser "may not
+                # be secure".
+                ignore_default_args=["--enable-automation", *WEAK_COOKIE_KEY_ARGS],
+            )
+        except PlaywrightError as error:
+            raise LoginError(_explain_launch_error(error, browser)) from None
+        try:
+            context.add_init_script(SORT_ACCOUNTS_SCRIPT)
+            context.route(AWS_SAML_URL, catch)
+            page = context.pages[0] if context.pages else context.new_page()
+            page.goto(start_url)
+            _wait_until(lambda: bool(result), context, timeout_secs)
+        finally:
+            context.close()
+
+    return result[0]
+
+
+def _explain_launch_error(error: PlaywrightError, browser: str) -> str:
+    """Turn a browser start-up error into a message that says what to do.
+
+    :param error: Error from Playwright.
+    :param browser: The browser that failed to start.
+    :return: A short message for the user.
+    """
+    message = str(error)
+    if "ProcessSingleton" in message:
+        return (
+            "Another idp2aws login is using the browser profile. "
+            "Finish or close it, then try again."
+        )
+    if "is not found" in message or "Executable doesn't exist" in message:
+        return f"Cannot find {browser}. Install it, or set a different browser."
+    return f"Cannot start {browser}: {message.splitlines()[0]}"
+
+
+def _has_several_roles(saml_response: str) -> bool:
+    """Tell whether the SAML response offers more than one role.
+
+    :param saml_response: The base64 ``SAMLResponse`` value.
+    :return: ``False`` if it lists one role or cannot be read. The caller
+        reports an unreadable response.
+    """
+    try:
+        return len(saml.parse(saml_response).roles) > 1
+    except saml.SAMLError:
+        return False
+
+
+def _wait_until(
+    is_done: Callable[[], bool], context: BrowserContext, timeout_secs: int
+) -> None:
+    """Let the browser run until ``is_done`` returns ``True``.
+
+    Playwright only handles browser events while we call into it, so we wait
+    in short steps on the page instead of sleeping.
+
+    :param is_done: Check that ends the wait.
+    :param context: The open browser.
+    :param timeout_secs: How long to wait.
+    :raises LoginError: If the window is closed or the time runs out.
+    """
+    deadline = time.monotonic() + timeout_secs
+    while not is_done():
+        if not context.pages:
+            raise LoginError("The browser window was closed before the login finished.")
+        if time.monotonic() > deadline:
+            raise LoginError(f"The login did not finish within {timeout_secs} seconds.")
+        try:
+            context.pages[0].wait_for_timeout(250)
+        except PlaywrightError:
+            pass  # The page closed during the wait. The next loop checks again.

idp2aws/cli.py

@@ -0,0 +1,256 @@
+"""Module for the ``idp2aws`` command line.
+
+Messages for you go to stderr, so stdout stays clean for ``login --json``.
+"""
+
+import os
+import webbrowser
+from typing import Annotated, NoReturn
+
+import typer
+from botocore.exceptions import ClientError
+
+from idp2aws import __version__, aws, browser, saml, settings
+
+app = typer.Typer(
+    help="Get short-lived AWS keys. You sign in to your IdP in a browser.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+ProfileArgument = Annotated[
+    str, typer.Argument(help="AWS profile for the keys, for example dev.")
+]
+
+
+def show_version(is_wanted: bool) -> None:
+    """Print the idp2aws version and stop, for ``--version``.
+
+    :param is_wanted: ``True`` when ``--version`` was given.
+    :raises typer.Exit: After printing the version.
+    """
+    if is_wanted:
+        typer.echo(f"idp2aws {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    _version: Annotated[
+        bool,
+        typer.Option(
+            "--version", callback=show_version, is_eager=True, help="Show the version."
+        ),
+    ] = False,
+) -> None:
+    """Get short-lived AWS keys. You sign in to your IdP in a browser."""
+
+
+@app.command()
+def setup(
+    start_url: Annotated[str, typer.Argument(help="Start URL of your IdP for AWS.")],
+    browser_name: Annotated[
+        settings.Browser, typer.Option("--browser")
+    ] = settings.Browser.CHROME,
+    session_hours: Annotated[
+        int,
+        typer.Option(
+            "--hours",
+            min=1,
+            max=settings.MAX_SESSION_HOURS,
+            help="How long AWS keys last.",
+        ),
+    ] = 1,
+) -> None:
+    """Create the config file with settings shared by every profile."""
+    try:
+        shared = settings.Settings(start_url, browser_name.value, session_hours)
+        settings.create_config(shared)
+    except settings.SettingsError as error:
+        fail(str(error))
+    say(f"Created {settings.CONFIG_FILE}. Next: idp2aws login <profile>")
+
+
+@app.command()
+def login(
+    profile: ProfileArgument,
+    pick: Annotated[
+        bool,
+        typer.Option("--pick", help="Show the AWS role page and pick a different role."),
+    ] = False,
+    as_json: Annotated[
+        bool,
+        typer.Option("--json", help="Print the keys for credential_process."),
+    ] = False,
+) -> None:
+    """Sign in and save AWS keys to a profile in ~/.aws/credentials.
+
+    The first login for a profile shows the AWS role page. The role you pick
+    is used again next time.
+    """
+    credentials = get_credentials(profile, pick)
+    if as_json:
+        typer.echo(credentials.as_json())
+        return
+    expires = credentials.expiration.astimezone()
+    say(f"Keys for profile {profile!r} work until {expires:%H:%M on %d %b}.")
+
+
+@app.command()
+def run(
+    profile: ProfileArgument,
+    command: Annotated[
+        list[str], typer.Argument(help="The command to run. Put it after --.")
+    ],
+) -> None:
+    """Run a command with the profile's AWS keys in its environment.
+
+    Example: idp2aws run dev -- aws s3 ls
+    """
+    credentials = get_credentials(profile)
+    env = {key: value for key, value in os.environ.items() if key != "AWS_PROFILE"}
+    try:
+        os.execvpe(command[0], command, env | credentials.as_env())
+    except FileNotFoundError:
+        fail(f"Command not found: {command[0]}")
+    except OSError as error:
+        fail(f"Cannot run {command[0]}: {error.strerror}")
+
+
+@app.command()
+def console(profile: ProfileArgument) -> None:
+    """Open the AWS console for the profile in your web browser."""
+    credentials = get_credentials(profile)
+    role_arn = settings.load_profiles()[profile].role_arn
+    if not role_arn.startswith("arn:aws:"):
+        fail("The console link only works for commercial AWS, not GovCloud or China.")
+    try:
+        webbrowser.open(aws.get_console_url(credentials))
+    except OSError as error:
+        fail(f"Cannot reach the AWS sign-in service: {error}")
+
+
+@app.command()
+def profiles() -> None:
+    """List your profiles, their roles and when their keys expire."""
+    try:
+        configured = settings.configured_profiles()
+    except settings.SettingsError as error:
+        fail(str(error))
+    saved = settings.load_profiles()
+    for name in sorted(set(configured) | set(saved)):
+        if name not in saved:
+            typer.echo(f"{name:<20} not logged in yet")
+            continue
+        expires = saved[name].expires.astimezone()
+        typer.echo(f"{name:<20} {saved[name].role_arn}  until {expires:%H:%M on %d %b}")
+
+
+def get_credentials(profile: str, pick: bool = False) -> aws.Credentials:
+    """Get working keys for a profile, signing in only if the saved ones expired.
+
+    The role comes from the profile's ``role_arn`` setting, then from your
+    last pick. With neither, or with ``pick``, the AWS role page is shown.
+
+    :param profile: AWS profile to save the keys to.
+    :param pick: Sign in again and show the AWS role page.
+    :return: Keys that have not expired.
+    """
+    try:
+        config = settings.load_settings(profile)
+    except settings.SettingsError as error:
+        fail(str(error))
+    saved = settings.load_profiles().get(profile)
+    if saved and not pick:
+        credentials = aws.load_credentials(profile, saved.expires)
+        if credentials and not credentials.is_expired:
+            return credentials
+
+    role_arn = config.role_arn or (saved.role_arn if saved else None)
+    if pick:
+        role_arn = None
+    if role_arn and role_arn == config.role_arn:
+        fix = f"Change role_arn for {profile} in {settings.CONFIG_FILE}."
+    else:
+        fix = "Log in again with --pick."
+    say(f"Opening the browser to sign in for {profile}...")
+    try:
+        login_result = browser.log_in(config.start_url, config.browser, role_arn)
+        assertion = saml.parse(login_result.saml_response)
+        role = choose_role(assertion, login_result.picked_role_arn or role_arn, fix)
+        say(f"Using role {role.role_arn}")
+        credentials = aws.assume_role(
+            role,
+            assertion,
+            config.session_hours * 3600,
+            aws.get_sts_region(assertion.destination),
+        )
+    except (browser.LoginError, saml.SAMLError) as error:
+        fail(str(error))
+    except ClientError as error:
+        fail(explain_sts_error(error))
+
+    aws.save_credentials(profile, credentials)
+    remembered = settings.Profile(profile, role.role_arn, credentials.expiration)
+    settings.save_profile(remembered)
+    return credentials
+
+
+def choose_role(
+    assertion: saml.Assertion, role_arn: str | None, fix: str = ""
+) -> saml.Role:
+    """Find the role to use in the SAML response.
+
+    :param assertion: The SAML response.
+    :param role_arn: Role picked on the AWS page, set in the config file or
+        remembered. If ``None``, the response must list exactly one role.
+    :param fix: What to do if ``role_arn`` is not in the response. It depends
+        on where the role came from.
+    :return: The matching role.
+    """
+    roles = assertion.roles
+    if not roles:
+        fail("The SAML response lists no AWS roles for you. Ask your IdP admin.")
+    if role_arn is None:
+        if len(roles) > 1:
+            fail("You did not pick a role. Try again and click Sign In on the AWS page.")
+        return roles[0]
+    role = next((role for role in roles if role.role_arn == role_arn), None)
+    if role is None:
+        fail(f"You can no longer use {role_arn}. {fix}".strip())
+    return role
+
+
+def explain_sts_error(error: ClientError) -> str:
+    """Turn an STS error into a message that says what to do about it.
+
+    :param error: Error raised by ``AssumeRoleWithSAML``.
+    :return: The STS message, with a hint when we know the usual fix.
+    """
+    message = error.response["Error"]["Message"]
+    if "DurationSeconds" in message:
+        return (
+            f"{message}\nMake session_hours smaller, or ask an AWS admin to increase "
+            "the maximum session duration of the role."
+        )
+    if "expired" in message.lower() or "NotOnOrAfter" in message:
+        return f"{message}\nYour computer clock may be wrong. Fix it and try again."
+    return message
+
+
+def say(message: str) -> None:
+    """Print a message for the user on stderr.
+
+    :param message: Text to print.
+    """
+    typer.echo(message, err=True)
+
+
+def fail(message: str) -> NoReturn:
+    """Print an error and exit with status 1.
+
+    :param message: What went wrong and, if known, what to do.
+    :raises typer.Exit: Always.
+    """
+    say(f"Error: {message}")
+    raise typer.Exit(1)

idp2aws/files.py

@@ -0,0 +1,30 @@
+"""Module for writing files so that readers never see half a file."""
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def write_file(path: Path, text: str, mode: int = 0o644) -> None:
+    """Replace a file in one step.
+
+    The text goes to a temporary file in the same folder first, then that file
+    replaces the target. If two runs write at the same time, the file holds
+    one of the two versions, never a mix. The target always gets ``mode``.
+
+    :param path: File to write. If it is a symlink, the file it points to is
+        replaced.
+    :param text: Full new content of the file.
+    :param mode: Permissions of the new file.
+    """
+    path = path.resolve()
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    handle, temp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.")
+    try:
+        with os.fdopen(handle, "w", encoding="utf-8") as file:
+            file.write(text)
+        os.chmod(temp_name, mode)
+        os.replace(temp_name, path)
+    except BaseException:
+        os.unlink(temp_name)
+        raise

idp2aws/saml.py

@@ -0,0 +1,87 @@
+"""Module for reading the parts of a SAML response that AWS cares about.
+
+The IdP signs the response and AWS STS checks the signature, so here we
+only read it: the roles you may use, and the AWS address it is meant for.
+"""
+
+import base64
+import binascii
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+
+ROLE_ATTRIBUTE = "https://aws.amazon.com/SAML/Attributes/Role"
+ARN = re.compile(r"arn:[\w-]+:iam::\d{12}:[^,\s]+")
+
+
+class SAMLError(Exception):
+    """Raise when a SAML response or one of its roles cannot be read."""
+
+
+@dataclass(frozen=True)
+class Role:
+    """An AWS role listed in the SAML response.
+
+    :param role_arn: The IAM role you may use.
+    :param principal_arn: The IAM SAML provider that trusts your IdP.
+    """
+
+    role_arn: str
+    principal_arn: str
+
+
+@dataclass
+class Assertion:
+    """A SAML response with the parts we need read out.
+
+    :param raw: The base64 text exactly as the IdP sent it. STS wants this.
+    :param roles: Roles you may use, in the order the IdP listed them.
+    :param destination: AWS sign-in address the response is meant for.
+    """
+
+    raw: str
+    roles: list[Role]
+    destination: str | None
+
+
+def parse(saml_response: str) -> Assertion:
+    """Read a base64 SAML response.
+
+    :param saml_response: The ``SAMLResponse`` form value.
+    :return: The roles and destination in the response.
+    :raises SAMLError: If it is not base64 XML, or a role cannot be read.
+    """
+    try:
+        root = ET.fromstring(base64.b64decode(saml_response))
+    except (binascii.Error, ET.ParseError) as error:
+        raise SAMLError(f"The SAML response is not base64 XML: {error}") from None
+
+    roles = []
+    for attribute in root.iterfind(".//{*}Attribute"):
+        if attribute.get("Name") == ROLE_ATTRIBUTE:
+            roles += [parse_role(value.text or "") for value in attribute]
+
+    destination = root.get("Destination")
+    if destination is None:
+        confirmation = root.find(".//{*}SubjectConfirmationData")
+        destination = confirmation.get("Recipient") if confirmation is not None else None
+
+    return Assertion(raw=saml_response, roles=roles, destination=destination)
+
+
+def parse_role(value: str) -> Role:
+    """Split one role value into its two ARNs.
+
+    The value should be ``<role ARN>,<provider ARN>``, but some IdPs swap
+    them, so we tell them apart by what they contain.
+
+    :param value: Text of one ``AttributeValue`` in the role attribute.
+    :return: The role and its SAML provider.
+    :raises SAMLError: If the value does not hold exactly those two ARNs.
+    """
+    arns = ARN.findall(value)
+    role = next((arn for arn in arns if ":role/" in arn), None)
+    principal = next((arn for arn in arns if ":saml-provider/" in arn), None)
+    if len(arns) != 2 or role is None or principal is None:
+        raise SAMLError(f"Cannot read this role value: {value!r}")
+    return Role(role_arn=role, principal_arn=principal)

idp2aws/settings.py

@@ -0,0 +1,202 @@
+"""Module for the config file and the profiles idp2aws remembers.
+
+Both files live in ``~/.idp2aws``, or in ``$IDP2AWS_HOME`` if it is set.
+
+``config.toml`` is yours to edit. Settings at the top apply to every
+profile, and a ``[profiles.<name>]`` table overrides them for one profile::
+
+    start_url = "https://accounts.google.com/o/saml2/initsso?idpid=X&spid=Y"
+    session_hours = 1
+
+    [profiles.prod]
+    role_arn = "arn:aws:iam::123456789012:role/Developer"
+    session_hours = 4
+
+``profiles.json`` is written by idp2aws: the role you last picked for each
+profile, and when its keys expire.
+"""
+
+import json
+import os
+import tomllib
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+
+from idp2aws.files import write_file
+
+HOME = Path(os.environ.get("IDP2AWS_HOME", Path.home() / ".idp2aws"))
+CONFIG_FILE = HOME / "config.toml"
+PROFILES_FILE = HOME / "profiles.json"
+MAX_SESSION_HOURS = 12
+
+CONFIG_TEMPLATE = """\
+# Settings for every profile.
+start_url = {start_url}
+browser = "{browser}"
+session_hours = {session_hours}
+
+# Settings for one profile go in its own table and win over the ones above.
+# [profiles.prod]
+# role_arn = "arn:aws:iam::123456789012:role/Developer"
+# session_hours = 4
+"""
+
+
+class SettingsError(Exception):
+    """Raise when the config file is missing, cannot be read or has a bad value."""
+
+
+class Browser(str, Enum):
+    """Browsers idp2aws can open."""
+
+    CHROME = "chrome"
+    CHROMIUM = "chromium"
+    MSEDGE = "msedge"
+
+
+@dataclass
+class Settings:
+    """Settings for one login, after profile overrides are applied.
+
+    :param start_url: Start URL of your IdP for AWS.
+    :param browser: ``chrome`` or ``msedge`` for your installed Chrome or Edge,
+        or ``chromium`` for the one Playwright downloads.
+    :param session_hours: How long the AWS keys last.
+    :param role_arn: Role to use without showing the AWS role page.
+    """
+
+    start_url: str
+    browser: str = "chrome"
+    session_hours: int = 1
+    role_arn: str | None = None
+
+    def __post_init__(self) -> None:
+        """Check the values, because the config file is edited by hand.
+
+        :raises SettingsError: If a value has the wrong type or is out of range.
+        """
+        url = self.start_url
+        if not isinstance(url, str) or not url.startswith("https://"):
+            raise SettingsError(f"start_url must be an https:// URL, not {url!r}.")
+        choices = [browser.value for browser in Browser]
+        if self.browser not in choices:
+            raise SettingsError(
+                f"browser must be one of {', '.join(choices)}, not {self.browser!r}."
+            )
+        hours = self.session_hours
+        is_whole = isinstance(hours, int) and not isinstance(hours, bool)
+        if not is_whole or not 1 <= hours <= MAX_SESSION_HOURS:
+            raise SettingsError(
+                f"session_hours must be a whole number from 1 to {MAX_SESSION_HOURS},"
+                f" not {hours!r}."
+            )
+        if self.role_arn is not None and not isinstance(self.role_arn, str):
+            raise SettingsError(f"role_arn must be text, not {self.role_arn!r}.")
+
+
+@dataclass
+class Profile:
+    """An AWS profile that idp2aws has saved keys to.
+
+    :param name: Profile name in the AWS credentials file.
+    :param role_arn: Role the keys belong to. The next login uses it again.
+    :param expires: When the keys stop working.
+    """
+
+    name: str
+    role_arn: str
+    expires: datetime
+
+
+def load_settings(profile: str, path: Path = CONFIG_FILE) -> Settings:
+    """Read the settings for one profile from the config file.
+
+    :param profile: Profile whose table, if any, overrides the shared settings.
+    :param path: Config file to read.
+    :return: The shared settings with the profile's overrides applied.
+    :raises SettingsError: If the file is missing, is not valid TOML, or has
+        an unknown or missing key.
+    """
+    config = _read_config(path)
+    overrides = config.pop("profiles", {}).get(profile, {})
+    try:
+        return Settings(**config | overrides)
+    except TypeError as error:
+        message = f"{path} has an unknown or missing setting: {error}"
+        raise SettingsError(message) from None
+    except SettingsError as error:
+        raise SettingsError(f"{path}: {error}") from None
+
+
+def configured_profiles(path: Path = CONFIG_FILE) -> list[str]:
+    """List the profiles that have a table in the config file.
+
+    :param path: Config file to read.
+    :return: Profile names, sorted.
+    :raises SettingsError: If the file is missing or is not valid TOML.
+    """
+    return sorted(_read_config(path).get("profiles", {}))
+
+
+def create_config(settings: Settings, path: Path = CONFIG_FILE) -> None:
+    """Write a new config file with the shared settings.
+
+    :param settings: Shared settings to write.
+    :param path: Config file to create.
+    :raises SettingsError: If the file already exists.
+    """
+    if path.exists():
+        raise SettingsError(f"{path} already exists. To change it, edit the file.")
+    write_file(path, CONFIG_TEMPLATE.format(
+        start_url=json.dumps(settings.start_url),
+        browser=settings.browser,
+        session_hours=settings.session_hours,
+    ))
+
+
+def load_profiles(path: Path = PROFILES_FILE) -> dict[str, Profile]:
+    """Read the profiles idp2aws has saved keys to.
+
+    :param path: Profiles file to read.
+    :return: Profiles by name. Empty if there are none yet.
+    """
+    if not path.exists():
+        return {}
+    return {
+        name: Profile(name, item["role_arn"], datetime.fromisoformat(item["expires"]))
+        for name, item in json.loads(path.read_text()).items()
+    }
+
+
+def save_profile(profile: Profile, path: Path = PROFILES_FILE) -> None:
+    """Remember a profile, keeping the others.
+
+    :param profile: Profile to add or replace.
+    :param path: Profiles file to write.
+    """
+    profiles = load_profiles(path) | {profile.name: profile}
+    data = {
+        name: {"role_arn": item.role_arn, "expires": item.expires.isoformat()}
+        for name, item in sorted(profiles.items())
+    }
+    write_file(path, json.dumps(data, indent=2) + "\n")
+
+
+def _read_config(path: Path) -> dict:
+    """Read the config file as a dict.
+
+    :param path: Config file to read.
+    :return: The parsed TOML.
+    :raises SettingsError: If the file is missing or is not valid TOML.
+    """
+    try:
+        with path.open("rb") as file:
+            return tomllib.load(file)
+    except FileNotFoundError:
+        raise SettingsError(
+            "idp2aws is not set up yet. Run: idp2aws setup <start-url>"
+        ) from None
+    except tomllib.TOMLDecodeError as error:
+        raise SettingsError(f"{path} is not valid TOML: {error}") from None

idp2aws-0.2.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: idp2aws
+Version: 0.2.0
+Summary: Get short-lived AWS keys by signing in to your SAML IdP in a real browser
+Project-URL: Homepage, https://github.com/saimoncse19/idp2aws
+Project-URL: Documentation, https://github.com/saimoncse19/idp2aws/blob/main/docs/USAGE.md
+Project-URL: Issues, https://github.com/saimoncse19/idp2aws/issues
+Project-URL: Changelog, https://github.com/saimoncse19/idp2aws/blob/main/CHANGELOG.md
+Author: Saimon
+License-Expression: LicenseRef-MIT-Commons-Clause
+License-File: LICENSE
+Keywords: aws,cli,entra-id,google-workspace,okta,saml,sso,sts
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration :: Authentication/Directory
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: boto3>=1.34
+Requires-Dist: playwright>=1.44
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == 'dev'
+Requires-Dist: pylint>=3; extra == 'dev'
+Requires-Dist: pytest-mock>=3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# idp2aws
+
+idp2aws gets short-lived AWS keys for you. You sign in to your IdP in a real browser window.
+It works with Google Workspace, Okta, Entra ID and other SAML IdPs that sign you in to AWS
+accounts directly.
+
+```sh
+idp2aws setup 'https://accounts.google.com/o/saml2/initsso?idpid=XXXX&spid=YYYY'
+idp2aws login dev                  # pick a role, idp2aws saves the keys to profile "dev"
+aws --profile dev s3 ls            # use the keys
+idp2aws run dev -- terraform plan  # run one command with the keys
+idp2aws console dev                # open the AWS console
+```
+
+The first login for a profile shows the AWS role page, sorted by account name. idp2aws keeps
+the role that you pick. The next logins for that profile use this role and do not show the page.
+While your IdP session is active, the browser window opens and closes without input from you.
+
+idp2aws does not work with AWS IAM Identity Center. For Identity Center, use `aws sso login`.
+
+## Install
+
+idp2aws needs Python 3.12 or newer, and Google Chrome or Microsoft Edge.
+
+Install from PyPI with pipx or pip:
+
+```sh
+pipx install idp2aws
+pip install idp2aws          # if you manage the virtual environment yourself
+```
+
+Or install from source:
+
+```sh
+pipx install git+https://github.com/saimoncse19/idp2aws.git    # latest code on main
+
+git clone https://github.com/saimoncse19/idp2aws.git && cd idp2aws   # to change the code
+python3.12 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+For step-by-step install on macOS, Linux and Windows, the config file and troubleshooting, see
+[docs/USAGE.md](https://github.com/saimoncse19/idp2aws/blob/main/docs/USAGE.md).
+
+## How it works
+
+1. Chrome opens at the start URL. You sign in to your IdP with your usual 2-Step Verification.
+2. The IdP sends a signed SAML response to the AWS sign-in page.
+3. If you have more than one role and the profile has no role yet, idp2aws lets AWS show its
+   role page. You pick a role and click Sign In.
+4. idp2aws stops the SAML response before it gets to AWS, and closes the window.
+5. idp2aws calls STS `AssumeRoleWithSAML` with the SAML response and gets keys for the role.
+6. idp2aws writes the keys to the profile in `~/.aws/credentials`.
+
+## Development
+
+```sh
+git clone https://github.com/saimoncse19/idp2aws.git && cd idp2aws
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+pytest                 # unit tests
+pytest -m browser      # browser tests: headless Chrome with a fake IdP and AWS role page
+pylint src scripts
+```
+
+The `CI` workflow runs the same checks on each pull request, and also builds the packages.
+
+## Release
+
+idp2aws uses semantic versioning: `MAJOR.MINOR.PATCH`. Each release must be the next patch,
+minor or major version after the latest one on PyPI. After 1.4.2, the only choices are 1.4.3,
+1.5.0 and 2.0.0.
+
+1. Set `__version__` in `src/idp2aws/__init__.py`. This is the only place the version is set.
+2. Add the version and the date to `CHANGELOG.md`.
+3. Merge to `main`.
+4. On GitHub, create a release with the tag `v` plus the version, for example `v1.4.3`.
+
+The `Publish to PyPI` workflow then runs the tests, checks the version and uploads to PyPI. If
+the tag does not match `__version__`, or the version skips or repeats one, the workflow stops
+and uploads nothing. To check a version before you release, run
+`python scripts/check_version.py v1.4.3`.
+
+## License
+
+idp2aws is source-available under the MIT license with the
+[Commons Clause](https://commonsclause.com/). You can use, change and share it for free,
+including at work. You cannot sell it, or sell a product or service whose value comes mainly
+from it. See [LICENSE](https://github.com/saimoncse19/idp2aws/blob/main/LICENSE).

idp2aws-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+idp2aws/__init__.py,sha256=3S3mDGZBzj87MBRKQ04w6aiZgU3uumlXacBur-v4zhA,108
+idp2aws/aws.py,sha256=Bk7Wrb-FJkCdTlvn4YPieMeucvCxcCbwqJIiDvnZwTU,6811
+idp2aws/browser.py,sha256=pB47pqvZs60tULVHkY2_Lzk_0K7TRmIyYyx5vHR8i6w,7086
+idp2aws/cli.py,sha256=mvY9mSHSDBRtT2N17RsCp7kZ1gUW2wg8W_IRIsMTvrY,8560
+idp2aws/files.py,sha256=CNRy-jNntxvNS6vOrpCoYCCQA4Gk0EUKI0HTgHRUn7w,1065
+idp2aws/saml.py,sha256=I_UcWYxpSl_OsO7wiEjsI9YCYIs_Kic215-z46jRv0s,2944
+idp2aws/settings.py,sha256=vXwZKTXMeBMIJzwzVuhD3P6y4NAtCcU090ZBgYCnBSc,6754
+idp2aws-0.2.0.dist-info/METADATA,sha256=94VmyWIv8Furql-ecx78G32UA3rrBBgPoBVm_p2H7UQ,5275
+idp2aws-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+idp2aws-0.2.0.dist-info/entry_points.txt,sha256=bq5VCCB49SHz9rE0WAHL6yGXhzLNMAQZFLRd9aODeFo,44
+idp2aws-0.2.0.dist-info/licenses/LICENSE,sha256=NV3K4GXQfebKwPG1-RWs8T48LC4u9BfUXZSsSSCXXsw,2046
+idp2aws-0.2.0.dist-info/RECORD,,

idp2aws-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

idp2aws-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+idp2aws = idp2aws.cli:app

idp2aws-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,44 @@
+"Commons Clause" License Condition v1.0
+
+The Software is provided to you by the Licensor under the License, as defined
+below, subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights under the
+License will not include, and the License does not grant to you, the right to
+Sell the Software.
+
+For purposes of the foregoing, "Sell" means practicing any or all of the rights
+granted to you under the License to provide to third parties, for a fee or other
+consideration (including without limitation fees for hosting or consulting/
+support services related to the Software), a product or service whose value
+derives, entirely or substantially, from the functionality of the Software. Any
+license notice or attribution required by the License must also include this
+Commons Clause License Condition notice.
+
+Software: idp2aws
+License: MIT
+Licensor: Saimon
+
+-------------------------------------------------------------------------------
+
+MIT License
+
+Copyright (c) 2026 Saimon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.