Skip to content

README.md

Latest commit

 

History

History
130 lines (108 loc) · 10.2 KB

README.md

File metadata and controls

130 lines (108 loc) · 10.2 KB

Identity gRPC Bindings

This project provides the functionalities of Identity in a language-agnostic way through a gRPC server.

The server can easily be run with docker using this dockerfile.

Build

Run docker build -f bindings/grpc/Dockerfile -t iotaleger/identity-grpc . from the project root.

Dockerimage env variables and volume binds

The provided docker image requires the following variables to be set in order to properly work:

  • API_ENDPOINT: IOTA node address.
  • STRONGHOLD_PWD: Stronghold password.
  • SNAPSHOT_PATH: Stronghold's snapshot location.

Make sure to provide a valid stronghold snapshot at the provided SNAPSHOT_PATH prefilled with all the needed key material.

Available services

Service description Service Id Proto File
Credential Revocation Checking credentials/CredentialRevocation.check credentials.proto
SD-JWT Validation sd_jwt/Verification.verify sd_jwt.proto
Credential JWT creation credentials/Jwt.create credentials.proto
Credential JWT validation credentials/VcValidation.validate credentials.proto
DID Document Creation document/DocumentService.create document.proto
Domain Linkage - validate domain, let server fetch did-configuration domain_linkage/DomainLinkage.validate_domain domain_linkage.proto
Domain Linkage - validate domain, pass did-configuration to service domain_linkage/DomainLinkage.validate_domain_against_did_configuration domain_linkage.proto
Domain Linkage - validate endpoints in DID, let server fetch did-configuration domain_linkage/DomainLinkage.validate_did domain_linkage.proto
Domain Linkage - validate endpoints in DID, pass did-configuration to service domain_linkage/DomainLinkage.validate_did_against_did_configurations domain_linkage.proto
StatusList2021Credential creation status_list_2021/StatusList2021Svc.create status_list_2021.proto
StatusList2021Credential update status_list_2021/StatusList2021Svc.update status_list_2021.proto

Testing

Domain Linkage

Http server

In order to test domain linkage, you need access to a server that is reachable via HTTPS. If you already have one, you can ignore the server setup steps here and provide the did-configuration.json on your server.

  1. create a folder with did configuration in it, e.g. (you can also use the template in ./tooling/domain-linkage-test-server)

    test-server/
└── .well-known
    └── did-configuration.json

    the did-configuration should look like this for now:

    {
    "@context": "https://identity.foundation/.well-known/did-configuration/v1",
    "linked_dids": [
        "add your domain linkage credential here"
    ]
}

  2. start a server that will serve this folder, e.g. with a NodeJs "http-server": http-server ./test-server/, in this example the server should now be running on local port 8080

  3. tunnel your server's port (here 8080) to a public domain with https, e.g. with ngrok: ngrok http http://127.0.0.1:8080
    the output should now have a line like
    Forwarding https://0d40-2003-d3-2710-e200-485f-e8bb-7431-79a7.ngrok-free.app -> http://127.0.0.1:8080
    check that the https url is reachable, this will be used in the next step. You can also start ngrok with a static domain, which means you don't have to update credentials after each http server restart

  4. for convenience, you can find a script to start the HTTP server, that you can adjust in tooling/start-http-server.sh, don't forget to insert your static domain or to remove the --domain parameter

Domain linkage credential

  1. copy the public url and insert it into 6_domain_linkage.rs as domain 1, e.g. let domain_1: Url = Url::parse("https://0d40-2003-d3-2710-e200-485f-e8bb-7431-79a7.ngrok-free.app")?; .1 run the example with cargo run --release --example 6_domain_linkage

GRPC server

  1. grab the configuration resource from the log and replace the contents of your did-configuration.json with it
  2. you now have a publicly reachable (sub)domain, that serves a did-configuration file containing a credential pointing to your DID
  3. to verify this, run the server via Docker or with the following command, remember to replace the placeholders ;) API_ENDPOINT=replace_me STRONGHOLD_PWD=replace_me SNAPSHOT_PATH=replace_me cargo run --release The arguments can be taken from examples, e.g. after running a 6_domain_linkage.rs, which also logs snapshot path passed to secret manager (let snapshot_path = random_stronghold_path(); dbg!(&snapshot_path.to_str());), for example
    • API_ENDPOINT: "http://localhost"
    • STRONGHOLD_PWD: "secure_password"
    • SNAPSHOT_PATH: "/var/folders/41/s1sm86jx0xl4x435t81j81440000gn/T/test_strongholds/8o2Nyiv5ENBi7Ik3dEDq9gNzSrqeUdqi.stronghold"
  4. for convenience, you can find a script to start the GRPC server, that you can adjust in tooling/start-rpc-server.sh, don't forget to insert the env variables as described above

Calling the endpoints

  1. call the validate_domain endpoint with your domain, e.g with:

    {
    "domain": "https://0d40-2003-d3-2710-e200-485f-e8bb-7431-79a7.ngrok-free.app"
}

    you should now receive a response like this:

    {
    "linked_dids": [
        {
            "document": "... (compact JWT domain linkage credential)",
            "status": "ok"
        }
    ]
}

  2. to call the validate_did endpoint, you need a DID to check, you can find a testable in you domain linkage credential. for this just decode it (e.g. on jwt.io) and get the iss value, then you can submit as "did" like following

    {
    "did": "did:iota:snd:0x967bf8f0c7487f61378611b6a1c6a59cb99e65b839681ee70be691b09a024ab9"
}

    you should not receive a response like this:

    {
    "service": [
        {
            "service_endpoint": [
                {
                    "valid": true,
                    "document": "eyJraWQiOiJkaWQ6aW90YTpzbmQ6MHg5NjdiZjhmMGM3NDg3ZjYxMzc4NjExYjZhMWM2YTU5Y2I5OWU2NWI4Mzk2ODFlZTcwYmU2OTFiMDlhMDI0YWI5IzA3QjVWRkxBa0FabkRhaC1OTnYwYUN3TzJ5ZnRzX09ZZ0YzNFNudUloMlUiLCJ0eXAiOiJKV1QiLCJhbGciOiJFZERTQSJ9.eyJleHAiOjE3NDE2NzgyNzUsImlzcyI6ImRpZDppb3RhOnNuZDoweDk2N2JmOGYwYzc0ODdmNjEzNzg2MTFiNmExYzZhNTljYjk5ZTY1YjgzOTY4MWVlNzBiZTY5MWIwOWEwMjRhYjkiLCJuYmYiOjE3MTAxNDIyNzUsInN1YiI6ImRpZDppb3RhOnNuZDoweDk2N2JmOGYwYzc0ODdmNjEzNzg2MTFiNmExYzZhNTljYjk5ZTY1YjgzOTY4MWVlNzBiZTY5MWIwOWEwMjRhYjkiLCJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vaWRlbnRpdHkuZm91bmRhdGlvbi8ud2VsbC1rbm93bi9kaWQtY29uZmlndXJhdGlvbi92MSJdLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiRG9tYWluTGlua2FnZUNyZWRlbnRpYWwiXSwiY3JlZGVudGlhbFN1YmplY3QiOnsib3JpZ2luIjoiaHR0cHM6Ly9ob3QtYnVsbGRvZy1wcm9mb3VuZC5uZ3Jvay1mcmVlLmFwcC8ifX19.69e7T0DbRw9Kz7eEQ96P9E5HWbEo5F1fLuMjyQN6_Oa1lwBdbfj0wLlhS1j_d8AuNmvu60lMdLVixjMZJLQ5AA"
                },
                {
                    "valid": false,
                    "error": "domain linkage error: error sending request for url (https://bar.example.com/.well-known/did-configuration.json): error trying to connect: dns error: failed to lookup address information: nodename nor servname provided, or not known"
                }
            ],
            "id": "did:iota:snd:0x967bf8f0c7487f61378611b6a1c6a59cb99e65b839681ee70be691b09a024ab9"
        }
    ]
}

    Which tells us that it found a DID document with one matching service with a serviceEndpoint, that contains two domains. Out of these domains one links back to the given DID, the other domain could not be resolved.