Skip to content

Commit

Permalink
feat: docs (#291)
Browse files Browse the repository at this point in the history 
* feat: trust docs + lint

* feat: storage ttl docs
  • Loading branch information
@Zicchio
Zicchio authored Oct 24, 2024
1 parent bc8ed4e commit da47074
Show file tree
Hide file tree
Showing 3 changed files with 98 additions and 42 deletions.
86 changes: 44 additions & 42 deletions README.SATOSA.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,14 @@ To install the OpenID4VP SATOSA backend you just need to:
4. In `plugins/microservices/target_based_routing.yaml` please add ` "https://eudi.wallet.gov.it": "OpenID4VP"`
5. Customize [example/satosa/static/disco.html](example/satosa/static/disco.html), then copy it in satosa static file folder. Example `example/static/static/disco.html`
6. Customize [example/satosa/templates/*.html](example/satosa/templates/*.html), then copy it in satosa templates file folder (the path your have configured in your `pyeudiw_backend.yaml` file).
7. Customize [example/satosa/internal_attributes.yaml](example/satosa/internal_attributes.yaml), then copy it the path your have configured in your `proxy_conf.yaml` file).
7. Customize [example/satosa/internal_attributes.yaml](example/satosa/internal_attributes.yaml), then copy it the path your have configured in your `proxy_conf.yaml` file.

### Backend Configuration Parameters

#### Top-Level

| Parameter | Description | Example value |
|-----------|----------------------------------------------------|-----------------------------------------|
| --------- | -------------------------------------------------- | --------------------------------------- |
| module | The name of the module that implements the backend | pyeudiw.satosa.backend.OpenID4VPBackend |
| name | The name of the backend | OpenID4VP |

Expand All @@ -33,7 +33,7 @@ To install the OpenID4VP SATOSA backend you just need to:
##### UI

| Parameter | Description | Example value |
|------------------------------|-----------------------------------------------|-----------------------------------|
| ---------------------------- | --------------------------------------------- | --------------------------------- |
| config.ui.static_storage_url | The URL of the static storage for the UI | https://localhost/static |
| config.ui.template_folder | The folder where the UI templates are located | templates |
| config.ui.qrcode_template | The name of the template for the QR code | qr_code.html |
Expand All @@ -43,7 +43,7 @@ To install the OpenID4VP SATOSA backend you just need to:
##### Endpoints

| Parameter | Description | Example value |
|---------------------------------------|---------------------------------------------------|--------------------------------|
| ------------------------------------- | ------------------------------------------------- | ------------------------------ |
| config.endpoints.pre_request | The endpoint for the pre-request | /pre-request |
| config.endpoints.response | The endpoint for the response | /response-uri |
| config.endpoints.request | The endpoint for the request | /request-uri |
Expand All @@ -54,7 +54,7 @@ To install the OpenID4VP SATOSA backend you just need to:
##### QR Code

| Parameter | Description | Example value |
|-------------------------------|----------------------------------------------------|---------------|
| ----------------------------- | -------------------------------------------------- | ------------- |
| config.qrcode.size | The size of the QR code in pixels | 100 |
| config.qrcode.color | The color of the QR code in hexadecimal | #2B4375 |
| config.qrcode.expiration_time | The expiration time of the QR code in seconds | 120 |
Expand All @@ -63,64 +63,65 @@ To install the OpenID4VP SATOSA backend you just need to:

##### JWT

| Parameter | Description | Example value |
|--------------------------------|---------------------------------------------------------|-----------------------------------------------------------------------------------|
| config.jwt.default_sig_alg | The default signature algorithm for the JWT | ES256 |
| config.jwt.default_enc_alg | The default encryption algorithm for the JWT | RSA-OAEP |
| config.jwt.default_enc_enc | The default encryption encoding for the JWT | A256CBC-HS512 |
| config.jwt.default_exp | The default expiration time for the JWT in minutes | 6 |
| config.jwt.enc_alg_supported | The list of supported encryption algorithms for the JWT | [RSA-OAEP, RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW] |
| config.jwt.enc_enc_supported | The list of supported encryption encodings for the JWT | [A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM] |
| config.jwt.sig_alg_supported | The list of supported signature algorithms for the JWT | [RS256, RS384, RS512, ES256, ES384, ES512] |
| Parameter | Description | Example value |
| ---------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------- |
| config.jwt.default_sig_alg | The default signature algorithm for the JWT | ES256 |
| config.jwt.default_enc_alg | The default encryption algorithm for the JWT | RSA-OAEP |
| config.jwt.default_enc_enc | The default encryption encoding for the JWT | A256CBC-HS512 |
| config.jwt.default_exp | The default expiration time for the JWT in minutes | 6 |
| config.jwt.enc_alg_supported | The list of supported encryption algorithms for the JWT | [RSA-OAEP, RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW] |
| config.jwt.enc_enc_supported | The list of supported encryption encodings for the JWT | [A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM] |
| config.jwt.sig_alg_supported | The list of supported signature algorithms for the JWT | [RS256, RS384, RS512, ES256, ES384, ES512] |

##### Authorization

| Parameter | Description | Example value |
|------------------------------------------------|--------------------------------------------------------------------------------|-----------------------------------------------|
| config.authorization.url_scheme | The URL scheme for the authorization | eudiw |
| config.authorization.scopes | The list of scopes for the authorization | [pid-sd-jwt:unique_id+given_name+family_name] |
| config.authorization.default_acr_value | The default authentication context class reference value for the authorization | https://www.spid.gov.it/SpidL2 |
| Parameter | Description | Example value |
| -------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------- |
| config.authorization.url_scheme | The URL scheme for the authorization | eudiw |
| config.authorization.scopes | The list of scopes for the authorization | [pid-sd-jwt:unique_id+given_name+family_name] |
| config.authorization.default_acr_value | The default authentication context class reference value for the authorization | https://www.spid.gov.it/SpidL2 |

##### User Attributes

| Parameter | Description | Example value |
|------------------------------------------------|--------------------------------------------------------------------------------|--------------------------|
| config.user_attributes.unique_identifiers | The list of unique identifiers for the user attributes | [tax_id_code, unique_id] |
| config.user_attributes.subject_id_random_value | A random value to be used in hashing | CHANGE_ME! |
| Parameter | Description | Example value |
| ---------------------------------------------- | ------------------------------------------------------ | ------------------------ |
| config.user_attributes.unique_identifiers | The list of unique identifiers for the user attributes | [tax_id_code, unique_id] |
| config.user_attributes.subject_id_random_value | A random value to be used in hashing | CHANGE_ME! |

##### Network

| Parameter | Description | Example Value |
|---------------------------------------------|-----------------------------------------------------------------|---------------|
| ------------------------------------------- | --------------------------------------------------------------- | ------------- |
| config.network.httpc_params.connection.ssl | The flag to indicate whether to use SSL for the HTTP connection | true |
| config.network.httpc_params.session.timeout | The timeout value for the HTTP session | 6 |

##### Federation

| Parameter | Description | Example Value |
|----------------------------------------------------------------|-----------------------------------------------------------|--------------------------------------------------------------------------|
| config.federation.metadata_type | The type of metadata to use for the federation | wallet_relying_party |
| config.federation.authority_hints | The list of authority hints to use for the federation | [http://127.0.0.1:10000] |
| config.federation.trust_anchors | The list of trust anchors to use for the federation | [http://127.0.0.1:10000] |
| config.federation.default_sig_alg | The default signature algorithm to use for the federation | RS256 |
| config.federation.federation_entity_metadata.organization_name | The organization name | Developers Italia SATOSA OpenID4VP backend policy_uri, tos_uri, logo_uri |
| config.federation.federation_entity_metadata.homepage_uri | The URI of the homepage | https://developers.italia.it |
| config.federation.federation_entity_metadata.policy_uri | The URI of the policy | https://developers.italia.it/policy.html |
| config.federation.federation_entity_metadata.tos_uri | The URI of the TOS | https://developers.italia.it/tos.html |
| config.federation.federation_entity_metadata.logo_uri | The URI of the logo | https://developers.italia.it/assets/icons/logo-it.svg |
| config.federation.federation_jwks | The list of (private) JSON Web Keys for the federation | |
##### Trust

| Parameter | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------- |
| config.trust | A dictionary of trust implementation, where the key is a user friendly identitfier and the value is described below |

The parameters of a `config.trust` dictionary entry value are

| Parameter | Description | Example Value |
| -------------------------------- | ----------------------------------------------------------- | -------------------------------------------- |
| config.trust.<identifier>.module | A python module that provides a trust implementation | pyeudiw.trust.default.direct_trust_sd_jwt_vc |
| config.trust.<identifier>.class | The class in the module that implements the trust interface | DirectTrustSdJwtVc |
| config.trust.<identifier>.config | The configuration of the class in the module |

For more deatils on available trust implementations and their configurations, see [docs/TRUST.md](/docs/TRUST.md)

##### Metadata jwks

| Parameter | Description | Example Value |
|----------------------|------------------------------------------------------|---------------|
| -------------------- | ---------------------------------------------------- | ------------- |
| config.metadata_jwks | The list of (private) JSON Web Keys for the metadata | |


##### Storage

| Parameter | Description | Example Value |
|-----------------------------------------------------------------------------------|--------------------------------------------------------|-------------------------------|
| --------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------- |
| config.storage.mongo_db.cache.module | The module name for the MongoDB cache | pyeudiw.storage.mongo_cache |
| config.storage.mongo_db.cache.class | The class name for the MongoDB cache | MongoCache |
| config.storage.mongo_db.cache.init_params.url | The URL for the MongoDB connection | mongodb://satosa-mongo:27017 |
Expand All @@ -134,13 +135,14 @@ To install the OpenID4VP SATOSA backend you just need to:
| config.storage.mongo_db.storage.init_params.conf.db_sessions_collection | The name of the collection to store sessions | sessions |
| config.storage.mongo_db.storage.init_params.conf.db_trust_attestations_collection | The name of the collection to store trust attestations | trust_attestations |
| config.storage.mongo_db.storage.init_params.conf.db_trust_anchors_collection | The name of the collection to store trust anchors | trust_anchors |
| config.storage.mongo_db.storage.init_params.conf.data_ttl | The lifetime duration of data in the database | 63072000 |
| config.storage.mongo_db.storage.connection_params.username | The username for authentication to the database | satosa |
| config.storage.mongo_db.storage.connection_params.password | The password for authentication to the database | thatpassword |

##### Metadata

| Parameter | Description | Example value |
|--------------------------------------------------------|------------------------------------------------------------------------------------------|------------------------------------------------------------------|
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| config.metadata.application_type | The type of application that uses the OpenID Connect protocol | web |
| config.metadata.authorization_encrypted_response_alg | The algorithm used to encrypt the authorization response | `<jwt.enc_alg_supported>` |
| config.metadata.authorization_encrypted_response_enc | The encryption method used to encrypt the authorization response | `<jwt.enc_enc_supported>` |
Expand All @@ -164,7 +166,7 @@ To install the OpenID4VP SATOSA backend you just need to:
###### Presentation definition

| Parameter | Description | Example value |
|----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|------------------------------------------------|
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| config.metadata.presentation_definition.id | The unique identifier of the presentation definition | d76c51b7-ea90-49bb-8368-6b3d194fc131 |
| config.metadata.presentation_definition.input_descriptors | The list of input descriptors that specify the verifiable credentials that the client requests | See below |
| config.metadata.presentation_definition.id | The unique identifier of the input descriptor | IdentityCredential |
Expand Down
Loading

0 comments on commit da47074

Please sign in to comment.