Develop

.github/workflows/mkdocs-publish.yml

@@ -0,0 +1,64 @@
+name: Publish documentation
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.9'
+
+      - name: Install package
+        run: pip install ./
+
+      - name: Install MkDocs and Material for MkDocs
+        run: pip install -r requirements-dev.txt
+
+      - name: Install Pillow and CairoSVG (required for social card generation)
+        run: pip install pillow cairosvg
+      - name: Setup caching
+        uses: actions/cache@v3
+        with:
+          key: ${{ github.sha }}
+          path: .cache
+      - name: Build site (_site directory name is used for Jekyll compatiblity)
+        run: mkdocs build --config-file ./mkdocs.yml --site-dir ./_site
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

.github/workflows/python-test.yml

@@ -16,7 +16,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
 
     steps:
     - uses: actions/checkout@v3
@@ -43,4 +43,4 @@ jobs:
         name: pytest-results-${{ matrix.python-version }}
         path: junit/test-results-${{ matrix.python-version }}.xml
       # Use always() to always run this step to publish test results when there are test failures
-      if: ${{ always() }}
+      if: ${{ always() }}

.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 23.1.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files

README.md

@@ -2,14 +2,21 @@
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![PyPI version](https://badge.fury.io/py/iam-rolesanywhere-session.svg)](https://badge.fury.io/py/iam-rolesanywhere-session)
+![Status](https://img.shields.io/pypi/status/iam-rolesanywhere-session.svg)
+
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)
 
 This package provides an easy way to create a __refreshable__ boto3 Session with [AWS Roles Anywhere](https://docs.aws.amazon.com/rolesanywhere/latest/APIReference/Welcome.html).
 
 This package implements the algorithm described here: https://docs.aws.amazon.com/rolesanywhere/latest/userguide/authentication-sign-process.html.
 
-## Limitations
 
-* Additional x509 Certificate Chain not yet supported
+## Requirements
+
+- Python 3.5 or later
+- Creation and configuration of a trust anchor. See [documentation](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/getting-started.html)
+- Valid X.509 certificate, private key, and optionally a certificate chain file associated with your trust anchor
 
 ## Install
 
@@ -23,7 +30,7 @@ pip install iam-rolesanywhere-session
 
 ```bash
 git clone https://github.com/awslabs/iam-roles-anywhere-session.git
-python3 setup.py install 
+python3 setup.py install
 ```
 
 ## Configuration
@@ -47,10 +54,6 @@ IAMRoleAnywhereSession will take multiple arguments:
 
 ## Usage
 
-### Example
-
-- Minimum implementation
-
 ```python
 from iam_rolesanywhere_session import IAMRolesAnywhereSession
 
@@ -65,43 +68,18 @@ roles_anywhere_session = IAMRolesAnywhereSession(
 
 s3 = roles_anywhere_session.client("s3")
 print(s3.list_buckets())
-
-```
-
-- Use a different region for IAM Roles Anywhere and the session.
 
-```python
-from iam_rolesanywhere_session import IAMRolesAnywhereSession
+```
 
-roles_anywhere_session = IAMRolesAnywhereSession(
-    profile_arn="arn:aws:rolesanywhere:eu-central-1:************:profile/a6294488-77cf-4d4a-8c5c-40b96690bbf0",
-    role_arn="arn:aws:iam::************:role/IAMRolesAnywhere-01",
-    trust_anchor_arn="arn:aws:rolesanywhere:eu-central-1::************::trust-anchor/4579702c-9abb-47c2-88b2-c734e0b29539,
-    certificate='certificate.pem',
-    private_key='privkey.pem',
-    region="eu-central-1"
-).get_session(region="eu-west-1")
+# Documentation
 
-s3 = roles_anywhere_session.client("s3")
-print(s3.list_buckets())
-
-```
+You can find [here](https://tbuatois.github.io/iam-rolesanywhere-session/) the complete documentation with additional usage and module reference.
 
-- Private Key encoded with a passphrase
+## Contributing
 
-```python
-from iam_rolesanywhere_session import IAMRolesAnywhereSession
+Contributions are very welcome.
+To learn more, see the [Contributor Guide](CONTRIBUTING.md).
 
-roles_anywhere_session = IAMRolesAnywhereSession(
-    profile_arn="arn:aws:rolesanywhere:eu-central-1:************:profile/a6294488-77cf-4d4a-8c5c-40b96690bbf0",
-    role_arn="arn:aws:iam::************:role/IAMRolesAnywhere-01",
-    trust_anchor_arn="arn:aws:rolesanywhere:eu-central-1::************::trust-anchor/4579702c-9abb-47c2-88b2-c734e0b29539,
-    certificate='certificate.pem',
-    private_key='privkey.pem',
-    private_key_passphrase = "my_secured_passphrase",
-    region="eu-central-1"
-).get_session(region="eu-west-1")
+## License
 
-s3 = roles_anywhere_session.client("s3")
-print(s3.list_buckets()) 
-```
+Distributed under the terms of the [Apache 2](LICENSE)

docs/index.md

@@ -0,0 +1,37 @@
+# IAM Roles Anywhere Session
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![PyPI version](https://badge.fury.io/py/iam-rolesanywhere-session.svg)](https://badge.fury.io/py/iam-rolesanywhere-session)
+![Status](https://img.shields.io/pypi/status/iam-rolesanywhere-session.svg)
+
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)
+
+This package provides an easy way to create a __refreshable__ boto3 Session with [AWS Roles Anywhere](https://docs.aws.amazon.com/rolesanywhere/latest/APIReference/Welcome.html).
+
+This package implements the algorithm described here: https://docs.aws.amazon.com/rolesanywhere/latest/userguide/authentication-sign-process.html.
+
+## Requirements
+
+- Python 3.5 or later
+- Creation and configuration of a trust anchor. See [documentation](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/getting-started.html)
+- Valid X.509 certificate, private key, and optionally a certificate chain file associated with your trust anchor
+
+## Install
+
+- From PyPi
+
+```bash
+pip install iam-rolesanywhere-session
+```
+
+- From source
+
+```bash
+git clone https://github.com/awslabs/iam-roles-anywhere-session.git
+python3 setup.py install
+```
+
+## Configuration
+
+For this package to work you will need to have at your disposal your `certificate` and `private_key` file in a PEM format.

docs/reference.md

@@ -0,0 +1,8 @@
+# Reference
+
+## Session Class
+::: iam_rolesanywhere_session.IAMRolesAnywhereSession
+
+## Signer Class
+
+::: iam_rolesanywhere_session.IAMRolesAnywhereSigner

docs/usage.md

@@ -0,0 +1,105 @@
+---
+title: Usage
+---
+
+# Examples
+
+## Minimal implementation
+
+```python
+from iam_rolesanywhere_session import IAMRolesAnywhereSession
+
+roles_anywhere_session = IAMRolesAnywhereSession(
+    profile_arn="arn:aws:rolesanywhere:eu-central-1:************:profile/a6294488-77cf-4d4a-8c5c-40b96690bbf0",
+    role_arn="arn:aws:iam::************:role/IAMRolesAnywhere-01",
+    trust_anchor_arn="arn:aws:rolesanywhere:eu-central-1::************::trust-anchor/4579702c-9abb-47c2-88b2-c734e0b29539,
+    certificate='certificate.pem',
+    private_key='privkey.pem',
+    region="eu-central-1"
+).get_session()
+
+s3 = roles_anywhere_session.client("s3")
+print(s3.list_buckets())
+
+```
+
+## Use a different region for IAM Roles Anywhere and the session.
+
+```python
+from iam_rolesanywhere_session import IAMRolesAnywhereSession
+
+roles_anywhere_session = IAMRolesAnywhereSession(
+    profile_arn="arn:aws:rolesanywhere:eu-central-1:************:profile/a6294488-77cf-4d4a-8c5c-40b96690bbf0",
+    role_arn="arn:aws:iam::************:role/IAMRolesAnywhere-01",
+    trust_anchor_arn="arn:aws:rolesanywhere:eu-central-1::************::trust-anchor/4579702c-9abb-47c2-88b2-c734e0b29539,
+    certificate='certificate.pem',
+    private_key='privkey.pem',
+    region="eu-central-1"
+).get_session(region="eu-west-1")
+
+s3 = roles_anywhere_session.client("s3")
+print(s3.list_buckets())
+
+```
+
+## Private Key encoded with a passphrase
+
+```python
+from iam_rolesanywhere_session import IAMRolesAnywhereSession
+
+roles_anywhere_session = IAMRolesAnywhereSession(
+    profile_arn="arn:aws:rolesanywhere:eu-central-1:************:profile/a6294488-77cf-4d4a-8c5c-40b96690bbf0",
+    role_arn="arn:aws:iam::************:role/IAMRolesAnywhere-01",
+    trust_anchor_arn="arn:aws:rolesanywhere:eu-central-1::************::trust-anchor/4579702c-9abb-47c2-88b2-c734e0b29539,
+    certificate='certificate.pem',
+    private_key='privkey.pem',
+    private_key_passphrase = "my_secured_passphrase",
+    region="eu-central-1"
+).get_session(region="eu-west-1")
+
+s3 = roles_anywhere_session.client("s3")
+print(s3.list_buckets())
+```
+
+## Use a certificate chain
+
+```python
+from iam_rolesanywhere_session import IAMRolesAnywhereSession
+
+roles_anywhere_session = IAMRolesAnywhereSession(
+    profile_arn="arn:aws:rolesanywhere:eu-central-1:************:profile/a6294488-77cf-4d4a-8c5c-40b96690bbf0",
+    role_arn="arn:aws:iam::************:role/IAMRolesAnywhere-01",
+    trust_anchor_arn="arn:aws:rolesanywhere:eu-central-1::************::trust-anchor/4579702c-9abb-47c2-88b2-c734e0b29539,
+    certificate='certificate.pem',
+    certificate_chain='my_cert_cahin.pem',
+    private_key='privkey.pem',
+    private_key_passphrase = "my_secured_passphrase",
+    region="eu-central-1"
+).get_session(region="eu-west-1")
+
+s3 = roles_anywhere_session.client("s3")
+print(s3.list_buckets())
+```
+
+## Get Frozen Credentials
+
+
+```python
+from iam_rolesanywhere_session import IAMRolesAnywhereSession
+
+creds = IAMRolesAnywhereSession(
+    profile_arn="arn:aws:rolesanywhere:eu-central-1:************:profile/a6294488-77cf-4d4a-8c5c-40b96690bbf0",
+    role_arn="arn:aws:iam::************:role/IAMRolesAnywhere-01",
+    trust_anchor_arn="arn:aws:rolesanywhere:eu-central-1::************::trust-anchor/4579702c-9abb-47c2-88b2-c734e0b29539,
+    certificate='certificate.pem',
+    certificate_chain='my_cert_cahin.pem',
+    private_key='privkey.pem',
+    private_key_passphrase = "my_secured_passphrase",
+    region="eu-central-1"
+).get_refreshable_credentials()
+
+ACCESS_KEY = creds.access_key
+SECRET_KEY = creds.secret_key
+TOKEN = creds.token
+
+```