rp_python_sdk 0.3.0__py3-none-any.whl

rp_python_sdk-0.3.0.dist-info/METADATA

@@ -0,0 +1,414 @@
+Metadata-Version: 2.1
+Name: rp_python_sdk
+Version: 0.3.0
+Summary: Python SDK for Relying Parties to enable simple integration with the Digital Identity ecosystem
+License: MIT
+Author: Erik Pragt
+Author-email: erik.pragt@connectid.com.au
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: authlib (>=1.3.0,<2.0.0)
+Requires-Dist: dataclass-wizard (>=0.22.3,<0.23.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Python SDK for Relying Parties
+
+[![rp-python-sdk](https://github.com/connectid-tools/rp-python-sdk/actions/workflows/python-app.yml/badge.svg)](https://github.com/connectid-tools/rp-python-sdk/actions/workflows/python-app.yml)
+
+rp-python-sdk is an SDK that allows Relying Parties to easily integrate with the Digital Identity ecosystem 
+using the Python programming language.
+
+# Getting Started
+
+You will need a Python 3.12 (or greater).
+
+- [quickstart](#quickstart)
+- [pyenv/pyenv-virtualenv](#pyenvpyenv-virtualenv)
+- [poetry](#poetry)
+- [reference](#reference)
+
+## pyenv/pyenv-virtualenv
+
+- make sure `pyenv` is installed
+- make sure `pyenv-virtualenv` is installed
+- install python `3.12`, for example `3.12.0`
+  ```bash
+  pyenv install 3.12.0
+  ```
+- create a virtual environment
+  ```bash
+  pyenv virtualenv 3.12.0 rp-python-sdk
+  ```
+- activate the virtual environment
+  ```bash
+  pyenv activate rp-python-sdk
+  ```
+(if this fails, add the following to .zshrc):
+
+```bash
+eval "$(pyenv init -)"
+eval "$(pyenv virtualenv-init -)"
+```
+
+- make sure `pip` and `setuptools` are up-to-date
+  ```bash
+  pip install --upgrade pip setuptools
+  ```
+
+## poetry
+
+- install poetry
+  ```bash
+  pip install --upgrade poetry
+  ```
+- install the application runtime dependencies
+  ```bash
+  poetry install --only main
+  ```
+- install the application test dependencies
+  ```bash
+  poetry install --with test
+  ```
+- install the application dev, test dependencies
+  ```bash
+  poetry install --with test,dev
+  ```
+- install the dependencies but not the current project
+  ```bash
+  poetry install --no-root --with test,dev
+  ```
+
+## running tests
+
+To run all the test, you can execute the following:
+
+```bash
+poetry run pytest
+```
+
+To run a selection of the tests, for example, run all the unit tests:
+
+```bash
+poetry run pytest -v -m "not conformance"
+```
+
+To only run the Conformance test, execute the following:
+
+```bash
+poetry run pytest -v -m conformance
+```
+
+## pre-commit
+
+This project use `pre-commit`. A `.pre-commit-config.yaml` is included.
+
+Run `pre-commit install` to install the Git hooks.
+
+
+## reference
+
+- poetry
+  - [Installation](https://python-poetry.org/docs/#installation)
+  - [Installing poetry manually](https://python-poetry.org/docs/#installing-manually)
+  - [Managing dependencies](https://python-poetry.org/docs/managing-dependencies/)
+- pre-commit
+  - [Installation](https://pre-commit.com/#install)
+  - [Usage](https://pre-commit.com/#usage)
+  - [Supported hooks](https://pre-commit.com/hooks.html)
+
+## certificates
+
+At the moment, there's a challenge to get the certificate loading to work well. This results in the following error:
+
+`[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1000)')`
+
+To fix this, you can run the following command:
+
+`ln -s ~/.pyenv/versions/3.12.0/envs/python-template-3-12/lib/python3.12/site-packages/certifi/cacert.pem cert.pem`
+
+And combine the `[connectid-sandbox-ca.pem](certs%2Fconnectid-sandbox-ca.pem)` with the `cert.pem` output.
+
+# Process Overview Sequence Diagram
+
+The expected interactions between the Relying Party and RP Connector as part of a standard flow are shown in the diagram below.
+
+The key steps are:
+
+* Retrieve the list of Participants so the user can be prompted to choose their identity provider (IDP)
+* Send a Pushed Authorisation Request (PAR) to the selected IDP with the requested claims and redirect the user to their IDP
+* Use the callback querystring to retrieve the access token and identity token with the claims the user has consented to share
+
+```mermaid
+sequenceDiagram
+    Customer->>+Relying Party: Use Digital ID
+    Relying Party->>+rp-java-sdk: getParticipants()
+    rp-java-sdk-->>-Relying Party: Participant metadata
+    Relying Party-->>-Customer: Display IDP Selector 
+    Customer->>+Relying Party: Select IDP
+    Relying Party->>+rp-java-sdk: sendPushedAuthorisationRequest()
+    rp-java-sdk-->>-Relying Party: authUrl, codeVerifier, state, nonce
+    Note right of Relying Party: The RP must associate the codeVerifier,<br/>state and nonce with the user<br/>to use when retrieving claims
+    Relying Party-->>-Customer: redirect to IDP using authUrl         
+    Customer->>+IDP: redirect to AuthUrl
+    IDP->>IDP: Authenticate & Capture Consent
+    IDP-->>-Customer: Redirect customer to RP callback URI
+    Customer->>+Relying Party: redirect to callback URL
+    Relying Party->>+rp-java-sdk: retrievetokens()
+    rp-java-sdk-->>-Relying Party: access and identity tokens
+    Relying Party-->>-Customer: Display outcome
+```
+
+# SDK Operations
+
+The expected usage and key points for each of the main SDK operations is described in detail below.
+
+## get_participants
+
+This allows the list of Identity Providers within the scheme to be retrieved, so that the Relying Party can display them
+to the user and allow the user to choose which Identity Provider they will use to prove their identity.
+
+Note that by default the SDK is configured to only return Identity Providers that are fully certified. If you wish to test
+one of the uncertified Identity Providers you will need to set the `include_uncertified_participants` configuration
+option to `true`. (This should only be done in a test environment, and should never be done in production.)
+
+You may also set the `required_claims` and `required_participant_certifications` configuration options to filter
+the list of IDPs returned based on the needs of your use case (eg: if you require IDPs to be TDIF certified).
+
+```python
+from rp_python_sdk.relying_party_client_sdk import RelyingPartyClientSdk
+from rp_python_sdk.sdk_config import SdkConfig, CustomConfig
+
+
+client = RelyingPartyClientSdk(
+  config=SdkConfig(
+    signing_key="the actual signing key here",
+    transport_key='certs/transport.key',
+    transport_pem='certs/transport.pem',
+    signing_pem='certs/signing.pem',
+    ca_pem='certs/connectid-sandbox-ca-with-root-certs.pem',
+    application_redirect_uri='https://tpp.localhost/cb',
+    registry_participants_uri='https://data.directory.sandbox.connectid.com.au/participants',
+    client_id='https://rp.directory.sandbox.connectid.com.au/openid_relying_party/280518db-9807-4824-b080-324d94b45f6a',
+    signing_kid='1X8udt28NY8NiSS8OJFvabv63K5igyFx5pM5ajKlMx8',
+    custom_config=CustomConfig(
+      enable_auto_compliance_verification=False
+    )
+  ),
+)
+
+participants = client.get_participants()
+```
+
+The response will contain List of Organisations and their Authorisation Server, with an object structure similar to below.
+
+They key fields of interest are:
+
+* `CustomerFriendlyName` - this is the name of the Bank to display to the customer
+* `CustomerFriendlyLogoUri` - this is a logo for the Bank that can be displayed alongside the bank name
+* `AuthorisationServerId` - this uniquely identifies the authorisation server. It will be needed as part of the next call
+  in the flow to identify the Authorisation Server to send the PAR to.
+
+Note that in the response there may be:
+
+* multiple organisations - each Bank will be its own organisation
+* multiple authorisation servers per bank - a Bank may have different authorisation servers for its different brands (or potentially
+  to differentiate Business Banking from Retail Banking).
+
+<!--
+TO DO: Suggest further instructions such as: The IDP selector needs to present all authorisation servers from all active organisations (status='Active')
+-->
+
+```json
+    [
+      {
+        "Status": "Active",
+        "OrgDomainRoleClaims": [],
+        "AuthorisationServers": [
+          {
+            "PayloadSigningCertLocationUri": "https://auth.bank4.directory.sandbox.connectid.com.au/na",
+            "ParentAuthorisationServerId": null,
+            "OpenIDDiscoveryDocument": "https://auth.bank4.directory.sandbox.connectid.com.au/.well-known/openid-configuration",
+            "CustomerFriendlyName": "Bank W",
+            "CustomerFriendlyDescription": "Bank4",
+            "TermsOfServiceUri": null,
+            "ApiResources": [],
+            "AutoRegistrationSupported": true,
+            "CustomerFriendlyLogoUri": "https://static.relyingparty.net/BankW.svg",
+            "SupportsDCR": false,
+            "AuthorisationServerCertifications": [],
+            "SupportsCiba": false,
+            "DeveloperPortalUri": null,
+            "NotificationWebhookAddedDate": null,
+            "AuthorisationServerId": "cde44c30-9138-4b58-ba50-221833d14319"
+          },
+          {
+            "PayloadSigningCertLocationUri": "https://auth.bank3.directory.sandbox.connectid.com.au/na",
+            "ParentAuthorisationServerId": null,
+            "OpenIDDiscoveryDocument": "https://auth.bank3.directory.sandbox.connectid.com.au/.well-known/openid-configuration",
+            "CustomerFriendlyName": "Bank N",
+            "CustomerFriendlyDescription": "Bank3",
+            "TermsOfServiceUri": null,
+            "ApiResources": [],
+            "AutoRegistrationSupported": true,
+            "CustomerFriendlyLogoUri": "https://static.relyingparty.net/BankN.svg",
+            "SupportsDCR": false,
+            "AuthorisationServerCertifications": [],
+            "SupportsCiba": false,
+            "DeveloperPortalUri": null,
+            "NotificationWebhookAddedDate": null,
+            "AuthorisationServerId": "22c2d67e-4d95-414a-b51a-ca863e9d691d"
+          }
+        ],
+        "OrgDomainClaims": [],
+        "Size": null,
+        "RegistrationId": null,
+        "OrganisationId": "ed63c5b4-4dcb-4867-bd8b-e2b04a0ab04b",
+        "City": "Banksville",
+        "Postcode": "4103",
+        "AddressLine2": "Bank Town",
+        "RegisteredName": "RefBank",
+        "AddressLine1": "1 Reference Bank Street",
+        "LegalEntityName": "Reference Bank",
+        "OrganisationName": "Reference Banks",
+        "Country": "AU",
+        "RegistrationNumber": "ABN 123 456 7890",
+        "CreatedOn": "2021-12-14T23:09:03.581Z",
+        "Tag": null,
+        "ParentOrganisationReference": "",
+        "CompanyRegister": "ABN",
+        "CountryOfRegistration": "AU"
+      },
+      {
+        "Status": "Active",
+        "OrgDomainRoleClaims": [],
+        "AuthorisationServers": [
+          {
+            "PayloadSigningCertLocationUri": "https://mtls.partner.idp.test.commbank.com.au/pf/JWKS",
+            "ParentAuthorisationServerId": null,
+            "OpenIDDiscoveryDocument": "https://mtls.partner.idp.test.commbank.com.au/.well-known/openid-configuration",
+            "CustomerFriendlyName": "Commonwealth Bank",
+            "CustomerFriendlyDescription": "Test IDP for CBA",
+            "TermsOfServiceUri": null,
+            "ApiResources": [],
+            "AutoRegistrationSupported": true,
+            "CustomerFriendlyLogoUri": "https://www.commbank.com.au/test.svg",
+            "SupportsDCR": false,
+            "AuthorisationServerCertifications": [],
+            "SupportsCiba": false,
+            "DeveloperPortalUri": null,
+            "NotificationWebhookAddedDate": null,
+            "AuthorisationServerId": "355df9aa-bf8f-4cec-aa4d-78b10356762e"
+          }
+        ],
+        "OrgDomainClaims": [],
+        "Size": null,
+        "RegistrationId": "",
+        "OrganisationId": "adf2af89-2782-4058-86d9-ff3a9068e4a5",
+        "City": "Sydney",
+        "Postcode": "2000",
+        "AddressLine2": "201 Sussex Street",
+        "RegisteredName": "Commonwealth Bank of Australia",
+        "AddressLine1": "Ground Floor Tower 1",
+        "LegalEntityName": "Commonwealth Bank of Australia",
+        "OrganisationName": "Commonwealth Bank of Australia",
+        "Country": "AU",
+        "RegistrationNumber": "ABN 48 123 123 124",
+        "CreatedOn": "2022-03-14T00:42:29.202Z",
+        "Tag": null,
+        "ParentOrganisationReference": "",
+        "CompanyRegister": "ABN",
+        "CountryOfRegistration": "AU"
+      }
+    ]
+```
+
+## get_fallback_provider_participants()
+
+This allows the list of Fallback Identity Providers (ie: manual document based verification) within the scheme to be retrieved,
+so that the Relying Party can use them as a fallback option if the user does not have a relationship
+with one of the identity providers. Note that there is only expected to be a single Fallback Provider authorisation
+server for the Scheme.
+
+It is expected that clients will only use this method if they are building their own IDP selector and need to
+identify the scheme Fallback Identity Provider.
+
+Note that there is only expected to be a single Fallback Provider for the scheme (so only one participant with one
+auth server should be returned here).
+
+```python
+participants = client.get_fallback_provider_participants()
+```
+
+The response will contain a list of Organisations and their Authorisation Servers, with the same return type as for `get_participants()`.
+
+## send_pushed_authorisation_request(authorisation_server_id, essential_claims, voluntary_claims, purpose)
+
+This sends a Pushed Authorisation Request to the specified Identity Server requesting the list of supplied claims.
+`send_pushed_authorisation_request(authorisation_server_id)` requests a default list of essential claims:
+`"name", "given_name", "middle_name", "family_name", "phone_number", "email", "address", "birthdate", "txn"`.
+The response will include the `authUrl` which is the URL that the user needs to be redirected to, so they can complete the authorisation process.
+
+Function parameters are:
+
+* `authorisationServerId` - identifies the authorisation server to send the PAR to
+* `essentialClaims` - a set of the essential identity claim names that are to be retrieved for the user. Note that permitted claim names
+  are defined in section 6 of the [Digital ID Identity Assurance Profile](https://docs.sandbox.connectid.com.au/docs/network-documentation/technical-specifications/) specification.
+* `voluntaryClaims` - a set of the voluntary identity claim names that are to be retrieved for the user. Note that permitted claim names
+  are defined in section 6 of the [Digital ID Identity Assurance Profile](https://docs.sandbox.connectid.com.au/docs/network-documentation/technical-specifications/) specification.
+* `purpose` - the purpose to be displayed to the consumer on the IDP consent screen to indicate why their data is being requested to be shared. If not supplied, the default purpose configured in the SDK config will be used.
+
+The method will return a `PARResponse` with properties for: `authUrl`, `code_verifier`, `state`, `nonce`, `xFapiInteractionId`. The properties represent:
+
+* `authUrl` - the URL that the user agent must be redirected to in order to complete the authorisation process with their Identity Provider
+* `xFapiInteractionId` - a unique identifier for this interaction with the Authorisation Server, that was sent in the `x-fapi-interaction-id` request
+  header to the server. Intended as a correlation id for diagnosing issues between the client and the authorisation server.
+
+The `codeVerifier`, `state` and `nonce` are all associated with this specific PAR and are required when retrieving the
+token claims when the user has authorised the request. You must securely associate these with your user request
+so that you can use them on the subsequent call.
+
+## retrieve_tokens(authorisation_server_id, callback_queries, code_verifier, state, nonce)
+
+This retrieves the access and identity token containing the claims that the user has consented to share with the
+Relying Party. It uses the authorisation code provided in the callback from the IDP and exchanges this for the access and
+identity token with the claims. The tokens are then returned to the API caller.
+
+The required function parameters are:
+
+* `authorisationServerId` - identifies the authorisation server providing the user information
+* `callbackQueries` - a `CallbackBody` that contains the query string parameters returned in the callback from the Authorisation Server
+* `codeVerifier` - from the response to the PAR for this identity request
+* `state` - from the response to the PAR for this identity request
+* `nonce` - from the response to the PAR for this identity request
+
+The method will return a `Tokenset` that contains the access_token and id_token with the requested claims along
+with a unique `x-fapi-interaction-id` that was used for this request to the authorisation server.
+
+## Conformance test
+
+An automated conformance test has been added. To execute the conformance test, a token is required,
+which can be created on the [OpenID Foundation conformance suite](https://www.certification.openid.net/tokens.html) page.
+
+This token needs to be set as an environment variable named `CONFORMANCE_API_TOKEN`, for example:
+
+```bash
+export CONFORMANCE_API_TOKEN=<token here>
+```
+
+After this, running `poetry run pytest -v -m conformance` will run the conformance test, and produce a test report.
+
+The test results are also available on GitHub after a successful merge to the main branch.
+
+## Release Notes
+
+### 0.3.0 (April 5, 2024)
+- Added participant / auth server filtering
+
+### 0.2.0 (March 30, 2024)
+- Implemented all endpoints
+
+### 0.1.0 (March 27, 2024)
+- Initial version

rp_python_sdk-0.3.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+rp_python_sdk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rp_python_sdk/endpoints/get_participants.py,sha256=AexSjIIpUR337Tzrdk24Tr_4te3FVsyEc5K94n-Br-Q,4862
+rp_python_sdk/endpoints/pushed_authorisation_request.py,sha256=A4sh5y1Io7o0Sq3LfU8gTQyZNnSwTwfc2Zfl3UazL5o,7820
+rp_python_sdk/endpoints/retrieve_tokens.py,sha256=VEu4YDrDK3l2dFHmvPNmoP-JOKGYEFBDIHEvSsBvaKY,10371
+rp_python_sdk/endpoints/user_info.py,sha256=OklfukQK8JlN6XTIECGSwQifMyCQhcy1aBr-Zdy2NQs,1745
+rp_python_sdk/endpoints/util/fapi.py,sha256=Ig5hGTaADuC8xSDXlrApDByFhFcED7mk9QRhAYWRfbE,1234
+rp_python_sdk/filters/participant_filters.py,sha256=tICb7KRC1GfBZsMif0tYOmMD0ezX5Gj74xZRcVQJ_6I,4646
+rp_python_sdk/model.py,sha256=ossWahCzBG_MLs_GDq4lh0tBK2xgPkmZweGBsag6tXI,3763
+rp_python_sdk/relying_party_client_sdk.py,sha256=cDO5SkPMBvLZLRAEfU4UaExFMflTeMOG5VQfkDrRz1c,2227
+rp_python_sdk/relying_party_client_sdk_exception.py,sha256=oODQi4wo3lSY3IXXVd6AZl_HLcBCg3ibu_a_MSPyXQU,58
+rp_python_sdk/sdk_config.py,sha256=DYz4ZzT3Af96CWDJmtsUY2T27tQ8kIxYYhypUKhCgaI,2759
+rp_python_sdk/setup_logger.py,sha256=YGcGEc_C2AR3YPCTxav53oQ2SdBUiVD4FzM_w0UXZMA,346
+rp_python_sdk-0.3.0.dist-info/LICENSE,sha256=eBxSWT9nCsY1PWnwgPcAYvvW0RBVbC18FiHmVVnonYQ,1069
+rp_python_sdk-0.3.0.dist-info/METADATA,sha256=uXmqsHv_u1KPLR0fFETLeKX9PYiRADHIlXk5AfMHPrw,17640
+rp_python_sdk-0.3.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+rp_python_sdk-0.3.0.dist-info/RECORD,,

rp_python_sdk-0.3.0.dist-info/WHEEL

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