From 77b80cb2b0d4de59cef02fb93a33c0af538b1040 Mon Sep 17 00:00:00 2001 From: Abdulrahim Al Methiab Date: Tue, 28 May 2024 11:26:14 +0200 Subject: [PATCH 01/16] add opendid documentation --- docs/develop/08_opendid/01_overview.md | 31 ++++ docs/develop/08_opendid/02_opendid_flow.md | 74 ++++++++ docs/develop/08_opendid/03_opendid_service.md | 172 ++++++++++++++++++ .../08_opendid/04_integrate_opendid.md | 122 +++++++++++++ docs/develop/08_opendid/05_demo_project.md | 30 +++ docs/develop/08_opendid/06_advanced.md | 115 ++++++++++++ docs/develop/08_opendid/_category_.json | 5 + sidebars.js | 1 + 8 files changed, 550 insertions(+) create mode 100644 docs/develop/08_opendid/01_overview.md create mode 100644 docs/develop/08_opendid/02_opendid_flow.md create mode 100644 docs/develop/08_opendid/03_opendid_service.md create mode 100644 docs/develop/08_opendid/04_integrate_opendid.md create mode 100644 docs/develop/08_opendid/05_demo_project.md create mode 100644 docs/develop/08_opendid/06_advanced.md create mode 100644 docs/develop/08_opendid/_category_.json diff --git a/docs/develop/08_opendid/01_overview.md b/docs/develop/08_opendid/01_overview.md new file mode 100644 index 000000000..81c302692 --- /dev/null +++ b/docs/develop/08_opendid/01_overview.md @@ -0,0 +1,31 @@ +--- +id: overview +title: Overview +--- + + +[OpenDID](https://github.com/KILTprotocol/opendid) is an OpenID Provider implementation that is capable of authenticating users through their [Decentralized Identifier (DID)](/docs/concepts/02_did.md) and Verifiable Credentials. +It follows the [OpenID Connect 1.0 Specification](https://openid.net/specs/openid-connect-core-1_0.html#Introduction) and acts as a bridge between the decentralized identity world and the centralized authentication world supporting both the implicit and Authorization Code Flow. + +A major use of OpenDID is SSO (Single Sign-On) where the same DID and credentials can be used to sign into multiple +platforms and webservices for instance by adding a `Sign in with Kilt` button to a webpage. + +Although, integrating that functionality into a webpage is relatively simple, configuring and running the OpenDID is a little more involved. + +## Project Structure +The project is composed of multiple parts that supplement and interact with each other all shipped as docker containers +released to docker hub: + +### opendid-setup: +In order to run the OpenDID Service, some configurations are needed, these configurations can be conveniently created using this +container. For example, a DID is required to establish a session with the Identity Wallet. This container creates a DID +and the necessary configurations by providing an account with enough funds. Learn more at [Run Setup +Container](/docs/develop/opendid/opendid_service#run-setup-container). + +### kiltprotocol/opendid +This container [runs the OpenDID Service](/docs/develop/opendid/opendid_service#run-the-service), both the OpenDID front and backend. This container requires the +configuration file created from the `opendid-setup` container. + +### kiltprotocol/opendid-demo +A [WebApp demo](/docs/develop/opendid/demo_project) including simple front and backend services to demonstrate the use of OpenDID. + diff --git a/docs/develop/08_opendid/02_opendid_flow.md b/docs/develop/08_opendid/02_opendid_flow.md new file mode 100644 index 000000000..63c5e34f8 --- /dev/null +++ b/docs/develop/08_opendid/02_opendid_flow.md @@ -0,0 +1,74 @@ +--- +id: flow +title: OpenDID Flow +--- + +This section explains the internal workings of OpenDID. Understanding this flow is helpful for setting up and +configuring an OpenDID Service but less important if only integrating it in an application is needed. + +OpenDID includes interactions between multiple apps in order to authenticate and authorize users, common use cases +inlcude the following programs: + +- WebApp Frontend (App that includes the login button e.g. the Demo App) +- WebApp Backend +- OpenDID Frontend +- OpenDID Backend +- Identity Wallet (Browser Extension e.g. [Sporran](https://www.sporran.org/)) + +The following steps outline the interactions necessary to implement the Implicit Flow: + +1. The user clicks the login button on the *WebApp Frontend* +2. The *WebApp Frontend* redirects the user to the *OpenDID Frontend*. +3. The user chooses what wallet to authenticate with. +4. *OpenDID Backend* establishes a secure session with the *Identity Wallet*. +5. *OpenDID Backend* optionally requests a credential that implements a specific CTYPE. +6. *Identity Wallet* provides the *OpenDID Backend* with the requested credential, after authenticating the DID holder. +7. *OpenDID Backend* returns a `id_token` (JWT) to the *OpenDID Frontend*. +8. *OpenDID Frontend* redirects user back to a specific `redirect_url` on the *WebApp Frontend* includig the `id_token`. +9. The *WebApp Frontend* detects the `id_token` and sends it to the *WebApp Backend*. +10. The *WebApp Backend* verifies the `id_token` and ensures the validity of the credential. + + +```mermaid +sequenceDiagram + +participant AB as WebApp Backend +participant AF as WebApp Frontend +participant OF as OpenDID Frontend +participant OB as OpenDID Backend +participant IW as Identity Wallet + +AF->>OF: (1, 2) Authorize (redirect_uri: /callback) +OF->>OF: (3) Pick Identity Wallet +critical (4) Key Exchange +OF->>OB: GET Challenge +OB-->>OF: Challenge +OF->>IW: Start Session +IW-->>OF: Encrypted Challenge +OF->>OB: POST Challenge +OB-->>OF: OK +end + +critical Authenticate +OF->>OB: (5) GET Credential Requirements +OB-->>OF: Credential Requirements +OF->>IW: (6) Request Credential +IW->>IW: Authenticate User +IW->>OF: Credential +OF->>OB: POST Credential +OB->>OB: Verify Credential +OB->>OF: (7) `id_token`) +end + +OF->>AF: redirect to /callback with `id_token` +AF->>AB: (8) `id_token` +AB->>AB: (9) verify `id_token` +AB->>AF: (10) Access granted. + +``` + +:::note +Although this example describes the Implicit Flow, the Authorization Code Flow is similar. Instead of returning and +`id_token` directly, a `code` is returned by the OpenDID service that can be exchanged afterwards using the `token` +endpoint. +::: diff --git a/docs/develop/08_opendid/03_opendid_service.md b/docs/develop/08_opendid/03_opendid_service.md new file mode 100644 index 000000000..7ccca5780 --- /dev/null +++ b/docs/develop/08_opendid/03_opendid_service.md @@ -0,0 +1,172 @@ +--- +id: opendid_service +title: Run OpenDID Service +--- + + +## Configuration + +Running the OpenDID service requires a set of configuration as well as a DID. The DID is required to establish a session +with secure connection with the Identity Wallet. +This is done though a keyAgreement key of type `X25519KeyAgreementKey2019` included in the DID Document generated by the +setup container. +Additionally, OpenDID serves a [Well Known DID Configuration](https://identity.foundation/.well-known/resources/did-configuration/) +which is required by the Identity Wallet to ensure that the domain is linked to the specified DID. + +### Run Setup Container + +Before running the `opendid-setup` container, two environment variables must be set: + +1. `SEED` to provide an account with funds (minimum of 3 KILT) for the DID generation. + +```bash +export SEED="dont try this seed its completely made up for this nice example" +``` +2. `ENDPOINT` + + Set to `"spiritnet"` if the account is on the spiritnet. + + + ```bash + export ENDPOINT="spiritnet" + ``` + + Set to `"peregrine"` if the account is on the peregrine. + + ```bash + export ENDPOINT="peregrine" + ``` + +Then run the setup using: + +```bash +docker run --rm -it -e "ENDPOINT=${ENDPOINT}" -v $(pwd):/data docker.io/kiltprotocol/opendid-setup:latest "${SEED}" +``` + +The command generates a set of new mnemonics and then derives a DID from it and generates multiple files: + +1. `config.yaml` The configuration file that is used by the OpenDID service. +1. `did-secrets.json` This file contains all the public and secret keys in the DID Document. You might want to keep a + secure backup of this file since it contains all the secret keys. +1. `did-document.json` contains the DID Document generated by this setup. + +:::danger +Only the `config.yaml` is required to run the OpenDID service. This file includes the provided mnemonic as well as +secret keys and must be protected from unauthorized access. +::: + +In the `config.yaml` file you might want to change some settings: + +- Set `production` to true, this will only allow secure connections. +- Set the WellKnownDid origin, which should match the origin running the OpenDid service. +- Set the keys used for JWT issuance. +- Clients, including: + - Their `client_id`s (Default: "exmaple_client"). + - What CTYPEs are required for authentication. + - The trusted attesters (Default: SocialKYC attester). + - What `redirect_url`s are accepted.(Default: `http://localhost:1606/callback.html` for the demo project) + - The `client_secret`, it's optional but recommended, if set it will be required by the `token` endpoint for the + Authorization Code Flow. + +### Example +An example of `config.yaml` file created by the `opendid_setup` container for peregrine: + +```json +# OpenDID Config File + +# server config +host: 0.0.0.0 +port: 3001 +basePath: ./login-frontend/dist +production: false +kiltEndpoint: peregrine + +# session config +# contains the keyUri, naclSecretKey, naclPublicKey and sessionKey used to communicate with the identity extension +session: + # key uri of the key agreement key of the verifiers DID + keyUri: did:kilt:4rsBA7tD5KQ8L9WHjFjYQuHkMkakcfHdC5CaQUcUxyUjDVHA#0x1285e2a18c69bfb7c7f402497adaf5062eb29e35c85461faed403e5c4cc6a9e6 + # nacl secret key of the key agreement key of the verifiers DID + naclSecretKey: "0xdaa2d564ca316aea1f7f9fd1bcb8180cd55f5bf0084f9ecc818a8bc91275aad2" + # nacl public key of the key agreement key of the verifiers DID + naclPublicKey: "0x706ffa25bb26e0be6c7ca14f43029cdced904761979f1cf03b2d7ab25e4ba047" + # session key used to encrypt the session data, needs to be the same on all instances + sessionKey: "0x5388fdd8f1caa9cad34ce05e45df91c084cfe15ebb9d8dfb4bbb8ea82bb47f5173c86b6139cdddb494be751700ba661721bf94b6aff65bf666b51524c3f670e7" + # time in seconds a session lasts as default of 60 minutes + sessionTtl: 3600 + +# jwt config +# contains the jwt config for the access and refresh tokens +jwt: + tokenIssuer: did:kilt:4rsBA7tD5KQ8L9WHjFjYQuHkMkakcfHdC5CaQUcUxyUjDVHA + accessTokenLifetime: 60 + accessTokenAudience: application + refreshTokenLifetime: 600 + refreshTokenAudience: authentication + secretKey: "super-secret-jwt-secret" + publicKey: "super-secret-jwt-secret" + algorithm: HS256 + +# well known DID +wellKnownDid: + did: did:kilt:4rsBA7tD5KQ8L9WHjFjYQuHkMkakcfHdC5CaQUcUxyUjDVHA + origin: http://localhost:3001 + keyUri: did:kilt:4rsBA7tD5KQ8L9WHjFjYQuHkMkakcfHdC5CaQUcUxyUjDVHA#0x9d9fc7637b98f00919a7ebb925b729f5141d66222ea7736af7d444b58a6a99d6 + seed: "dentist call educate decorate bag renew success myself fine acoustic rally flush//did//assertion//0" + +# client configs +clients: + example-client: + # credential requirements + # contains the credential requirements for the verifiers DID + # if the user provides ANY of the listed credentials, the login is successful + # w3n:socialkyc on spiritnet or w3n:attester on peregrine are added as example trustedAttesters for email CType + requirements: + - cTypeHash: "0x3291bb126e33b4862d421bfaa1d2f272e6cdfc4f96658988fbcffea8914bd9ac" + trustedAttesters: ["did:kilt:4pehddkhEanexVTTzWAtrrfo2R7xPnePpuiJLC7shQU894aY"] + requiredProperties: ["Email"] + # valid redirect urls for this client + redirectUrls: + - http://localhost:1606/callback.html + clientSecret: "insecure_client_secret" + +``` + +Note that an [Email credential](https://test.ctypehub.galaniprojects.de/ctype/kilt:ctype:0x3291bb126e33b4862d421bfaa1d2f272e6cdfc4f96658988fbcffea8914bd9ac) issued by [attester](https://test.w3n.id/attester) is required. +This credential can be acquired on [test socialKYC](https://test.socialkyc.io/). +If All the requirements are removed, a DID will be enough for authentication. + +## Run the service + +Once the `config.yaml` file is adjusted, the OpenDID Service can be run. + +1. Specify the runtime through the environment variable `RUNTIME`: + + Set to `"spiritnet"` for production KILT + + + ```bash + export RUNTIME="spiritnet" + ``` + + Set to `"peregrine"` for the KILT test net. + + ```bash + export RUNTIME="peregrine" + ``` +2. Run the `docker.io/kiltprotocol/opendid` docker image . + +```bash +docker run -d --rm \ + -v $(pwd)/config.yaml:/app/config.yaml \ + -v $(pwd)/checks:/app/checks \ + -e "RUNTIME=${RUNTIME}" \ + -p 3001:3001 \ + docker.io/kiltprotocol/opendid:latest +``` +The login page will run on `http://localhost:3001`. + +:::note +An OpenID flow must be integrated in an application for the user to be able to make use of this login page. See +[Integrate OpenDID](/docs/develop/opendid/integrate_opendid). +::: diff --git a/docs/develop/08_opendid/04_integrate_opendid.md b/docs/develop/08_opendid/04_integrate_opendid.md new file mode 100644 index 000000000..41b51c785 --- /dev/null +++ b/docs/develop/08_opendid/04_integrate_opendid.md @@ -0,0 +1,122 @@ +--- +id: integrate_opendid +title: Integrate OpenDID +--- + +OpenDID follows the [OpenID Connect 1.0 +Specification](https://openid.net/specs/openid-connect-core-1_0.html#Introduction) and implements both the [Implicit Flow](https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowSteps) +and the [Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth). See [Demo Project](/docs/develop/opendid/demo_project) for an example of integrating OpenDID. + + +## Authorization Code Flow + +Initiate the flow by redirecting to the **GET** `/api/v1/authorize` endpoint on the OpenDID Service and setting the following query +parameters: + +* `response_type`: set value to `code` to indicate Authorization Code Flow. +* `client_id`: The client ID set in the config.yaml file. +* `redirect_uri`: OpenDID will redirect to this URL after authentication. +* `scope`: set value to `openid`. +* `state`: set to a secure random number. +* `nonce`: optional value, set to a secure random number. + +**Example**: + +``` +GET /api/v1/authorize? + response_type=code& + client_id=example-client& + redirect_uri=http://localhost:1606/callback.html& + scope=openid& + state=rkw49cbvd4azu5dsln1xbl& + nonce=vedur4om49ei8w91jt7wt HTTP/1.1 +``` + +After successful authentication, OpenDID will redirect back to the provided `redirect_uri` with `code` and `state` query +parameters. + + +**Example**: +``` +/callback.html? + code=lwDS1ZpQBwR4Vdm53_L8bWpUJ1mx9A0mA_-86dubTqzqzwGazx1RyLX4Z_qf& + state=rkw49cbvd4azu5dsln1xbl +``` + +The `id_token` can be retrieved by calling the **POST** `/api/v1/token` and providing the following values in **form +serialization**: + +* `code`: code value returned from `authorize`. +* `grant_type`: set value to "authorization_code". +* `redirect_uri`: the same `redirect_uri` used in `authorize`. +* `client_id`: the client ID set in the config.yaml file. +* `client_secret`: the client secret value set in the config.yaml file. + +**Example**: + +``` +POST /api/v1/token HTTP/1.1 +Content-Type: application/x-www-form-urlencoded + +code=lwDS1ZpQBwR4Vdm53_L8bWpUJ1mx9A0mA_-86dubTqzqzwGazx1RyLX4Z_qf& +grant_type=authorization_code& +redirect_uri=http%3A%2F%2Flocalhost%3A1606%2Fcallback.html& +client_id=example-client& +client_secret=insecure_client_secret + +``` + +The `id_token` is returned by the OpenDID Service in the response body serialized in a JSON object. + +```json +{ + "access_token":"SsFhhSBMWsLeDMxVUVGreKARNwYxMZtGFfBr0-ZiH6iondSmwPRvQDqkG6Fh", + "token_type":"bearer", + "refresh_token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkaWQ6a2lsdDo0b0VkNENVV3RwbkxUVnZENVBFd2lMUmlqMWdzQmprS1JMbVpES2lCOEdqN2I2V0wiLCJ3M24iOiJjdXN0b20iLCJleHAiOjE3MTY4MTYwNjQsImlhdCI6MTcxNjgxNTQ2NCwiaXNzIjoiZGlkOmtpbHQ6NHJzQkE3dEQ1S1E4TDlXSGpGallRdUhrTWtha2NmSGRDNUNhUVVjVXh5VWpEVkhBIiwiYXVkIjoiYXV0aGVudGljYXRpb24iLCJwcm8iOnsiRW1haWwiOiJhYmR1bEBraWx0LmlvIn0sIm5vbmNlIjoidmVkdXI0b200OWVpOHc5MWp0N3d0In0.yOmE_9jWKcAu8LpjVx7IsFyOOvlKbgo2oC4Imf-qrLY", + "id_token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkaWQ6a2lsdDo0b0VkNENVV3RwbkxUVnZENVBFd2lMUmlqMWdzQmprS1JMbVpES2lCOEdqN2I2V0wiLCJ3M24iOiJjdXN0b20iLCJleHAiOjE3MTY4MTU1MjQsImlhdCI6MTcxNjgxNTQ2NCwiaXNzIjoiZGlkOmtpbHQ6NHJzQkE3dEQ1S1E4TDlXSGpGallRdUhrTWtha2NmSGRDNUNhUVVjVXh5VWpEVkhBIiwiYXVkIjoiYXBwbGljYXRpb24iLCJwcm8iOnsiRW1haWwiOiJhYmR1bEBraWx0LmlvIn0sIm5vbmNlIjoidmVkdXI0b200OWVpOHc5MWp0N3d0In0.YlRE9EGnSExQCb5m2iy4__58PZJlZdCZMsSvsuW4oj8" +} +``` + +:::note +In full-stack applications, calling the `token` endpoint is usually done through the backend to improve security. +::: + + +The `id_token` is a JWT signed by the JWT key-pair specified in the config.yaml file of the OpenDID Service, it can be verified using the JWT public key, for example, by the backend of the Web app. + +## Implicit Flow + + +Initiate the flow by redirecting to the **GET** `/api/v1/authorize` endpoint on the OpenDID Service and setting the following query +parameters: + +* `response_type`: set value to `id_token` to indicate Implicit Flow. +* `client_id`: The client ID set in the config.yaml file. +* `redirect_uri`: OpenDID will redirect to this URL after authentication. +* `scope`: set value to `openid`. +* `state`: set to a secure random number. +* `nonce`: optional value, set to a secure random number. + +**Example**: + +``` +GET /api/v1/authorize? + response_type=id_token& + client_id=example-client& + redirect_uri=http://localhost:1606/callback.html& + scope=openid& + state=o0fl4c9gwylymzw5f4ik& + nonce=ia7sa06ungxdfzaqphk2 HTTP/1.1 +``` + +After successful authentication, OpenDID will redirect back to the provided `redirect_uri` with `id_token` and `state` +**fragment components**. + +**Example**: +``` +/callback.html# + id_token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkaWQ6a2lsdDo0b0VkNENVV3RwbkxUVnZENVBFd2lMUmlqMWdzQmprS1JMbVpES2lCOEdqN2I2V0wiLCJ3M24iOiJjdXN0b20iLCJleHAiOjE3MTY4ODQ5MDYsImlhdCI6MTcxNjg4NDg0NiwiaXNzIjoiZGlkOmtpbHQ6NHJzQkE3dEQ1S1E4TDlXSGpGallRdUhrTWtha2NmSGRDNUNhUVVjVXh5VWpEVkhBIiwiYXVkIjoiYXBwbGljYXRpb24iLCJwcm8iOnsiRW1haWwiOiJhYmR1bEBraWx0LmlvIn0sIm5vbmNlIjoiOTFzN2ZnZDZvcjR3c2NkdGVtcXQifQ.xTy3Oyc5e-vlP10mGy0f9GqNU4LV97s77s-l7w5EwF0& + refresh_token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkaWQ6a2lsdDo0b0VkNENVV3RwbkxUVnZENVBFd2lMUmlqMWdzQmprS1JMbVpES2lCOEdqN2I2V0wiLCJ3M24iOiJjdXN0b20iLCJleHAiOjE3MTY4ODU0NDYsImlhdCI6MTcxNjg4NDg0NiwiaXNzIjoiZGlkOmtpbHQ6NHJzQkE3dEQ1S1E4TDlXSGpGallRdUhrTWtha2NmSGRDNUNhUVVjVXh5VWpEVkhBIiwiYXVkIjoiYXV0aGVudGljYXRpb24iLCJwcm8iOnsiRW1haWwiOiJhYmR1bEBraWx0LmlvIn0sIm5vbmNlIjoiOTFzN2ZnZDZvcjR3c2NkdGVtcXQifQ.87UHGid3OotxO8Wpfuw-1sc5fsQJVt5gc2cqp9dVHiw& + state=nitctpl7nmqcpvob7xthrw& + token_type=bearer +``` diff --git a/docs/develop/08_opendid/05_demo_project.md b/docs/develop/08_opendid/05_demo_project.md new file mode 100644 index 000000000..809129588 --- /dev/null +++ b/docs/develop/08_opendid/05_demo_project.md @@ -0,0 +1,30 @@ +--- +id: demo_project +title: Demo Project +--- + +The example code at [demo-project](https://github.com/KILTprotocol/opendid/tree/main/demo-project) contains a minimal application that uses OpenDID. +It's an [express](https://expressjs.com) application that exposes three things: + +- A login page that handles the dispatching of the user to the opendid. +- A callback page for the openid connect flow to accept the token. +- A protected resource that only authenticated users can access. + +Run the pre-configured demo application with the following command: + +```bash +docker run -d -it --rm \ + --name demo-frontend \ + -p 1606:1606 \ + docker.io/kiltprotocol/opendid-demo +``` + +The demo page will run on [http://localhost:1606](http://localhost:1606). + +For this demo to work a running OpenDID Service is needed, an Identity Wallet (e.g. [Sporran](https://www.sporran.org/)) +with a DID and Credential issued by the required attester specified in the `config.yaml` file (Default is SocialKYC). + +:::note +The JWT secret can be set with the `TOKEN_SECRET` environment variable inside the docker container. It must match +the one specified in the `config.yaml` file to correctly verify the `id_token`. Default is `super-secret-jwt-secret`. +::: diff --git a/docs/develop/08_opendid/06_advanced.md b/docs/develop/08_opendid/06_advanced.md new file mode 100644 index 000000000..4214a77b8 --- /dev/null +++ b/docs/develop/08_opendid/06_advanced.md @@ -0,0 +1,115 @@ +--- +id: advanced +title: Advanced Usage +--- + +### Use dynamic client management + +If you want to dynamically create or remove OpenID Connect clients, you can configure the service to get its configuration from an [etcd cluster](https://etcd.io). +To do so, configure the connection parameters for the etcd cluster in the `config.yaml` file. + +```yaml +etcd: + endpoints: ["localhost:2379"] + user: etcd-user + password: my-password + tlsDomainName: my.etcd.cluster.example.com + tlsCaCert: | + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + tlsClientCert: | + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + tlsClientKey: | + -----BEGIN RSA PRIVATE KEY----- + + -----END RSA PRIVATE KEY----- +``` + +All fields except `endpoints` are optional and depending on your etcd setup you might not need them. +When everything is set up you can start putting client configurations into the etcd cluster. + +```bash +CLIENT_SPEC=$(cat < Date: Thu, 30 May 2024 12:59:04 +0200 Subject: [PATCH 02/16] remove SIOP related comment --- docs/develop/08_opendid/03_opendid_service.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/develop/08_opendid/03_opendid_service.md b/docs/develop/08_opendid/03_opendid_service.md index 7ccca5780..278383513 100644 --- a/docs/develop/08_opendid/03_opendid_service.md +++ b/docs/develop/08_opendid/03_opendid_service.md @@ -134,7 +134,6 @@ clients: Note that an [Email credential](https://test.ctypehub.galaniprojects.de/ctype/kilt:ctype:0x3291bb126e33b4862d421bfaa1d2f272e6cdfc4f96658988fbcffea8914bd9ac) issued by [attester](https://test.w3n.id/attester) is required. This credential can be acquired on [test socialKYC](https://test.socialkyc.io/). -If All the requirements are removed, a DID will be enough for authentication. ## Run the service From 42d7947acaf6d530975464d32c58cddcf8ca367e Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Tue, 4 Jun 2024 17:10:44 +0200 Subject: [PATCH 03/16] Draft review Signed-off-by: Chris Chinchilla --- docs/develop/02_chain/04_fullnode.md | 2 +- docs/develop/08_opendid/01_overview.md | 43 +++-- docs/develop/08_opendid/02_opendid_flow.md | 44 ++--- docs/develop/08_opendid/03_opendid_service.md | 167 ++++++------------ .../08_opendid/04_integrate_opendid.md | 71 ++++---- docs/develop/08_opendid/05_demo_project.md | 2 +- docs/develop/08_opendid/06_advanced.md | 4 +- .../01_become_a_collator/03_setup_node.md | 2 +- markdown-link-check.config.json | 3 + 9 files changed, 144 insertions(+), 194 deletions(-) diff --git a/docs/develop/02_chain/04_fullnode.md b/docs/develop/02_chain/04_fullnode.md index 39810ced4..d056efcc4 100644 --- a/docs/develop/02_chain/04_fullnode.md +++ b/docs/develop/02_chain/04_fullnode.md @@ -41,7 +41,7 @@ This can either be `peregrine` or `spiritnet`. Hence, to start a full node for the Spiritnet network, the parameter would be `--chain=spiritnet`. Unfortunately, there is no hardcoded chain spec for the Peregrine network, so the full path of the chainspec file must be provided `--chain=/node/dev-specs/kilt-parachain/peregrine-kilt.json`. -Please refer to the [KILT node repository](https://github.com/KILTprotocol/kilt-node/blob/develop/dev-specs/kilt-parachain/peregrine-kilt.json) or the [Docker image](https://hub.docker.com/r/kiltprotocol/kilt-node/tags) for more information. +Please refer to the [KILT node repository](https://github.com/KILTprotocol/kilt-node/blob/master/dev-specs/kilt-parachain/peregrine-kilt.json) or the [Docker image](https://hub.docker.com/r/kiltprotocol/kilt-node/tags) for more information. ### Specify the Blockchain Storage Path diff --git a/docs/develop/08_opendid/01_overview.md b/docs/develop/08_opendid/01_overview.md index 81c302692..88cb3a7bc 100644 --- a/docs/develop/08_opendid/01_overview.md +++ b/docs/develop/08_opendid/01_overview.md @@ -1,31 +1,40 @@ --- -id: overview +id: what-is-opendid title: Overview --- +[OpenDID](https://github.com/KILTprotocol/opendid) is an OpenID Provider implementation capable of authenticating users through their [Decentralized Identifier (DID)](../../concepts/02_did.md) and Verifiable Credentials. -[OpenDID](https://github.com/KILTprotocol/opendid) is an OpenID Provider implementation that is capable of authenticating users through their [Decentralized Identifier (DID)](/docs/concepts/02_did.md) and Verifiable Credentials. It follows the [OpenID Connect 1.0 Specification](https://openid.net/specs/openid-connect-core-1_0.html#Introduction) and acts as a bridge between the decentralized identity world and the centralized authentication world supporting both the implicit and Authorization Code Flow. -A major use of OpenDID is SSO (Single Sign-On) where the same DID and credentials can be used to sign into multiple -platforms and webservices for instance by adding a `Sign in with Kilt` button to a webpage. +A major use of OpenDID is Single Sign-On (SSO) is to use the same DID and credentials to sign into multiple platforms and web services. For instance, by adding a "Sign in with KILT" button to a webpage. -Although, integrating that functionality into a webpage is relatively simple, configuring and running the OpenDID is a little more involved. +Although integrating that functionality into a webpage is relatively simple, configuring and running OpenDID is more involved. -## Project Structure -The project is composed of multiple parts that supplement and interact with each other all shipped as docker containers -released to docker hub: +:::info -### opendid-setup: -In order to run the OpenDID Service, some configurations are needed, these configurations can be conveniently created using this -container. For example, a DID is required to establish a session with the Identity Wallet. This container creates a DID -and the necessary configurations by providing an account with enough funds. Learn more at [Run Setup -Container](/docs/develop/opendid/opendid_service#run-setup-container). +To learn more about the flow of OpenDID, see the [OpenDID Flow](./02_opendid_flow.md) documentation. -### kiltprotocol/opendid -This container [runs the OpenDID Service](/docs/develop/opendid/opendid_service#run-the-service), both the OpenDID front and backend. This container requires the -configuration file created from the `opendid-setup` container. +::: + +## Project container structure + +The project consist of multiple parts that supplement and interact with each other all shipped as docker containers and released to docker hub. + +### opendid-setup container + +The OpenDID Service needs configuration to run, which you can apply using this +container. +For example, it requires a DID to establish a session with an identity wallet. +This container creates a DID and the necessary configuration by providing an account with enough funds. + +Learn more in the [run setup container documentation](./03_opendid_service.md#run-setup-container). + +### kiltprotocol/opendid container + +This container [runs the OpenDID Service](./03_opendid_service.md#run-the-service), both the OpenDID front and back end. +This container requires the configuration file created from the `opendid-setup` container. ### kiltprotocol/opendid-demo -A [WebApp demo](/docs/develop/opendid/demo_project) including simple front and backend services to demonstrate the use of OpenDID. +This container is a [web app demo](./05_demo_project.md), including front and back end services to demonstrate the use of OpenDID. diff --git a/docs/develop/08_opendid/02_opendid_flow.md b/docs/develop/08_opendid/02_opendid_flow.md index 63c5e34f8..2f2cc1f09 100644 --- a/docs/develop/08_opendid/02_opendid_flow.md +++ b/docs/develop/08_opendid/02_opendid_flow.md @@ -3,31 +3,32 @@ id: flow title: OpenDID Flow --- -This section explains the internal workings of OpenDID. Understanding this flow is helpful for setting up and -configuring an OpenDID Service but less important if only integrating it in an application is needed. +This guide explains the internal workings of OpenDID. +Understanding this flow is helpful for setting up and configuring an OpenDID Service but less important if you only need to integrate it in an application. -OpenDID includes interactions between multiple apps in order to authenticate and authorize users, common use cases -inlcude the following programs: +OpenDID includes interactions between multiple apps to authenticate and authorize users. +Common use cases include the following: -- WebApp Frontend (App that includes the login button e.g. the Demo App) -- WebApp Backend -- OpenDID Frontend -- OpenDID Backend -- Identity Wallet (Browser Extension e.g. [Sporran](https://www.sporran.org/)) +- Web app Frontend (app that includes the login button, for example, the demo app) +- Web app back end +- OpenDID front end +- OpenDID back end +- Identity wallet (a browser extension, for example, [Sporran](https://www.sporran.org/)) The following steps outline the interactions necessary to implement the Implicit Flow: -1. The user clicks the login button on the *WebApp Frontend* -2. The *WebApp Frontend* redirects the user to the *OpenDID Frontend*. +1. The user clicks the login button on the *web app front end*. +2. The *web app front end* redirects the user to the *OpenDID front end*. 3. The user chooses what wallet to authenticate with. -4. *OpenDID Backend* establishes a secure session with the *Identity Wallet*. -5. *OpenDID Backend* optionally requests a credential that implements a specific CTYPE. -6. *Identity Wallet* provides the *OpenDID Backend* with the requested credential, after authenticating the DID holder. -7. *OpenDID Backend* returns a `id_token` (JWT) to the *OpenDID Frontend*. -8. *OpenDID Frontend* redirects user back to a specific `redirect_url` on the *WebApp Frontend* includig the `id_token`. -9. The *WebApp Frontend* detects the `id_token` and sends it to the *WebApp Backend*. -10. The *WebApp Backend* verifies the `id_token` and ensures the validity of the credential. +4. The *OpenDID back end* establishes a secure session with the *identity wallet*. +5. The *OpenDID back end* optionally requests a credential that implements a specific CType. +6. The *identity wallet* provides the *OpenDID back end* with the requested credential, after authenticating the DID holder. +7. The *OpenDID back end* returns a `id_token` as a JSON web token (JWT) to the *OpenDID front end*. +8. *OpenDID front end* redirects the user back to a specific `redirect_url` on the *web app front end* including the `id_token`. +9. The *web app front end* detects the `id_token` and sends it to the *web app back end*. +10. The *web app back end* verifies the `id_token` and ensures the validity of the credential. +The following sequence diagram summarizes the flow: ```mermaid sequenceDiagram @@ -67,8 +68,7 @@ AB->>AF: (10) Access granted. ``` -:::note -Although this example describes the Implicit Flow, the Authorization Code Flow is similar. Instead of returning and -`id_token` directly, a `code` is returned by the OpenDID service that can be exchanged afterwards using the `token` -endpoint. +:::info +Although this example describes the implicit flow, the authorization code flow is similar. +Instead of returning an `id_token` directly, the OpenDID service instead returns a `code` to exhange for an `id_token` using the `token` endpoint. ::: diff --git a/docs/develop/08_opendid/03_opendid_service.md b/docs/develop/08_opendid/03_opendid_service.md index 278383513..855e6ba90 100644 --- a/docs/develop/08_opendid/03_opendid_service.md +++ b/docs/develop/08_opendid/03_opendid_service.md @@ -3,156 +3,98 @@ id: opendid_service title: Run OpenDID Service --- + ## Configuration -Running the OpenDID service requires a set of configuration as well as a DID. The DID is required to establish a session -with secure connection with the Identity Wallet. -This is done though a keyAgreement key of type `X25519KeyAgreementKey2019` included in the DID Document generated by the -setup container. -Additionally, OpenDID serves a [Well Known DID Configuration](https://identity.foundation/.well-known/resources/did-configuration/) -which is required by the Identity Wallet to ensure that the domain is linked to the specified DID. +Running the OpenDID service requires some configuration and a DID. +The DID establishes a secure session with an identity wallet using a key agreement key of type `X25519KeyAgreementKey2019` included in the DID Document generated by the setup container. -### Run Setup Container +OpenDID serves a [well-known DID configuration](https://identity.foundation/.well-known/resources/did-configuration/), which the identity wallet uses to ensure that the domain is linked to the specified DID. -Before running the `opendid-setup` container, two environment variables must be set: +### Run setup container + +Before running the `opendid-setup` container, set two environment variables: 1. `SEED` to provide an account with funds (minimum of 3 KILT) for the DID generation. ```bash export SEED="dont try this seed its completely made up for this nice example" ``` -2. `ENDPOINT` - Set to `"spiritnet"` if the account is on the spiritnet. +2. `ENDPOINT` +Set to "spiritnet" if the account is on the spiritnet production network. - ```bash - export ENDPOINT="spiritnet" - ``` +```bash +export ENDPOINT="spiritnet" +``` - Set to `"peregrine"` if the account is on the peregrine. +Set to "peregrine" if the account is on the peregrine test network. - ```bash - export ENDPOINT="peregrine" - ``` +```bash +export ENDPOINT="peregrine" +``` -Then run the setup using: +Then run the setup with the following command: ```bash docker run --rm -it -e "ENDPOINT=${ENDPOINT}" -v $(pwd):/data docker.io/kiltprotocol/opendid-setup:latest "${SEED}" ``` -The command generates a set of new mnemonics and then derives a DID from it and generates multiple files: +The command generates a set of new mnemonics and then derives a DID from them and generates multiple files into the current directory: + +1. `config.yaml` The configuration file used by the OpenDID service. +2. `did-secrets.json` This file contains the public and secret keys in the DID Document. -1. `config.yaml` The configuration file that is used by the OpenDID service. -1. `did-secrets.json` This file contains all the public and secret keys in the DID Document. You might want to keep a - secure backup of this file since it contains all the secret keys. -1. `did-document.json` contains the DID Document generated by this setup. +Keep a secure backup of this file as it contains all the secret keys. + +3. `did-document.json` contains the DID Document generated by this setup. :::danger -Only the `config.yaml` is required to run the OpenDID service. This file includes the provided mnemonic as well as -secret keys and must be protected from unauthorized access. +You only need the `config.yaml` to run the OpenDID service. +This file includes the generated mnemonic and secret keys and you should protect it from unauthorized access. ::: -In the `config.yaml` file you might want to change some settings: - -- Set `production` to true, this will only allow secure connections. -- Set the WellKnownDid origin, which should match the origin running the OpenDid service. -- Set the keys used for JWT issuance. -- Clients, including: - - Their `client_id`s (Default: "exmaple_client"). - - What CTYPEs are required for authentication. - - The trusted attesters (Default: SocialKYC attester). - - What `redirect_url`s are accepted.(Default: `http://localhost:1606/callback.html` for the demo project) - - The `client_secret`, it's optional but recommended, if set it will be required by the `token` endpoint for the - Authorization Code Flow. - -### Example -An example of `config.yaml` file created by the `opendid_setup` container for peregrine: - -```json -# OpenDID Config File - -# server config -host: 0.0.0.0 -port: 3001 -basePath: ./login-frontend/dist -production: false -kiltEndpoint: peregrine - -# session config -# contains the keyUri, naclSecretKey, naclPublicKey and sessionKey used to communicate with the identity extension -session: - # key uri of the key agreement key of the verifiers DID - keyUri: did:kilt:4rsBA7tD5KQ8L9WHjFjYQuHkMkakcfHdC5CaQUcUxyUjDVHA#0x1285e2a18c69bfb7c7f402497adaf5062eb29e35c85461faed403e5c4cc6a9e6 - # nacl secret key of the key agreement key of the verifiers DID - naclSecretKey: "0xdaa2d564ca316aea1f7f9fd1bcb8180cd55f5bf0084f9ecc818a8bc91275aad2" - # nacl public key of the key agreement key of the verifiers DID - naclPublicKey: "0x706ffa25bb26e0be6c7ca14f43029cdced904761979f1cf03b2d7ab25e4ba047" - # session key used to encrypt the session data, needs to be the same on all instances - sessionKey: "0x5388fdd8f1caa9cad34ce05e45df91c084cfe15ebb9d8dfb4bbb8ea82bb47f5173c86b6139cdddb494be751700ba661721bf94b6aff65bf666b51524c3f670e7" - # time in seconds a session lasts as default of 60 minutes - sessionTtl: 3600 - -# jwt config -# contains the jwt config for the access and refresh tokens -jwt: - tokenIssuer: did:kilt:4rsBA7tD5KQ8L9WHjFjYQuHkMkakcfHdC5CaQUcUxyUjDVHA - accessTokenLifetime: 60 - accessTokenAudience: application - refreshTokenLifetime: 600 - refreshTokenAudience: authentication - secretKey: "super-secret-jwt-secret" - publicKey: "super-secret-jwt-secret" - algorithm: HS256 - -# well known DID -wellKnownDid: - did: did:kilt:4rsBA7tD5KQ8L9WHjFjYQuHkMkakcfHdC5CaQUcUxyUjDVHA - origin: http://localhost:3001 - keyUri: did:kilt:4rsBA7tD5KQ8L9WHjFjYQuHkMkakcfHdC5CaQUcUxyUjDVHA#0x9d9fc7637b98f00919a7ebb925b729f5141d66222ea7736af7d444b58a6a99d6 - seed: "dentist call educate decorate bag renew success myself fine acoustic rally flush//did//assertion//0" - -# client configs -clients: - example-client: - # credential requirements - # contains the credential requirements for the verifiers DID - # if the user provides ANY of the listed credentials, the login is successful - # w3n:socialkyc on spiritnet or w3n:attester on peregrine are added as example trustedAttesters for email CType - requirements: - - cTypeHash: "0x3291bb126e33b4862d421bfaa1d2f272e6cdfc4f96658988fbcffea8914bd9ac" - trustedAttesters: ["did:kilt:4pehddkhEanexVTTzWAtrrfo2R7xPnePpuiJLC7shQU894aY"] - requiredProperties: ["Email"] - # valid redirect urls for this client - redirectUrls: - - http://localhost:1606/callback.html - clientSecret: "insecure_client_secret" +The container generates sensible defaults in the `config.yaml` file, but here are some values you might want to change: -``` +- Set `production` to true, this only allows secure connections. +- Set the `WellKnownDid` > `origin`, which should match the host running the OpenDID service. +- Set the keys used for JWT issuance in the `jwt` section. +- The `client` section, including: -Note that an [Email credential](https://test.ctypehub.galaniprojects.de/ctype/kilt:ctype:0x3291bb126e33b4862d421bfaa1d2f272e6cdfc4f96658988fbcffea8914bd9ac) issued by [attester](https://test.w3n.id/attester) is required. -This credential can be acquired on [test socialKYC](https://test.socialkyc.io/). + - The client ID as a key (The default is: `example-client`). + - The `requirements` section, including: + - What CTypes are required for authentication. + - The trusted attesters as an address (The default is for the [SocialKYC attester](https://socialkyc.io/)). -## Run the service + :::note info + + The generated `config.yaml` requires an [email credential](https://test.ctypehub.galaniprojects.de/ctype/kilt:ctype:0x3291bb126e33b4862d421bfaa1d2f272e6cdfc4f96658988fbcffea8914bd9ac) issued by an attester. + + ::: + + - What `redirect_url`s the service accepts (The default is `http://localhost:1606/callback.html` for the demo project). + - The `clientSecret` is optional but recommended. If you use the authorization code flow, the `token` endpoint requires it. -Once the `config.yaml` file is adjusted, the OpenDID Service can be run. +## Run the service -1. Specify the runtime through the environment variable `RUNTIME`: +When you've made changes to the `config.yaml` file, you can run the OpenDID service. - Set to `"spiritnet"` for production KILT +1. Specify the runtime through the `RUNTIME` environment variable: + Set to `"spiritnet"` for production KILT ```bash export RUNTIME="spiritnet" ``` - Set to `"peregrine"` for the KILT test net. + Set to `"peregrine"` for the KILT test net. ```bash export RUNTIME="peregrine" ``` + 2. Run the `docker.io/kiltprotocol/opendid` docker image . ```bash @@ -163,9 +105,10 @@ docker run -d --rm \ -p 3001:3001 \ docker.io/kiltprotocol/opendid:latest ``` -The login page will run on `http://localhost:3001`. -:::note -An OpenID flow must be integrated in an application for the user to be able to make use of this login page. See -[Integrate OpenDID](/docs/develop/opendid/integrate_opendid). -::: +3. Open the login page at _http://localhost:3001_. + +## Next steps + +With configuration in place and a service running, next you need to [integrate OpenDID into an application](./04_integrate_opendid.md) so that a user can use the login page. + diff --git a/docs/develop/08_opendid/04_integrate_opendid.md b/docs/develop/08_opendid/04_integrate_opendid.md index 41b51c785..2fd0b7514 100644 --- a/docs/develop/08_opendid/04_integrate_opendid.md +++ b/docs/develop/08_opendid/04_integrate_opendid.md @@ -3,22 +3,21 @@ id: integrate_opendid title: Integrate OpenDID --- -OpenDID follows the [OpenID Connect 1.0 -Specification](https://openid.net/specs/openid-connect-core-1_0.html#Introduction) and implements both the [Implicit Flow](https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowSteps) -and the [Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth). See [Demo Project](/docs/develop/opendid/demo_project) for an example of integrating OpenDID. +OpenDID follows the [OpenID Connect 1.0 Specification](https://openid.net/specs/openid-connect-core-1_0.html#Introduction) and implements both the [implicit flow](https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowSteps) +and the [authorization code flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth). +Read the [demo project guide](05_demo_project.md) for an example of integrating OpenDID. +## Authorization code flow -## Authorization Code Flow - -Initiate the flow by redirecting to the **GET** `/api/v1/authorize` endpoint on the OpenDID Service and setting the following query +Initiate the flow by redirecting to the **GET** `/api/v1/authorize` endpoint on the OpenDID service and setting the following query parameters: -* `response_type`: set value to `code` to indicate Authorization Code Flow. -* `client_id`: The client ID set in the config.yaml file. -* `redirect_uri`: OpenDID will redirect to this URL after authentication. -* `scope`: set value to `openid`. -* `state`: set to a secure random number. -* `nonce`: optional value, set to a secure random number. +- `response_type`: set value to `code` to indicate Authorization Code Flow. +- `client_id`: The client ID set in the config.yaml file. +- `redirect_uri`: OpenDID will redirect to this URL after authentication. +- `scope`: set value to `openid`. +- `state`: set to a secure random number. +- `nonce`: optional value, set to a secure random number. **Example**: @@ -32,25 +31,23 @@ GET /api/v1/authorize? nonce=vedur4om49ei8w91jt7wt HTTP/1.1 ``` -After successful authentication, OpenDID will redirect back to the provided `redirect_uri` with `code` and `state` query -parameters. - +After successful authentication, the OpenDID service redirects back to the provided `redirect_uri` with `code` and `state` query parameters. **Example**: + ``` /callback.html? code=lwDS1ZpQBwR4Vdm53_L8bWpUJ1mx9A0mA_-86dubTqzqzwGazx1RyLX4Z_qf& state=rkw49cbvd4azu5dsln1xbl ``` -The `id_token` can be retrieved by calling the **POST** `/api/v1/token` and providing the following values in **form -serialization**: +You can retrieve the `id_token` by calling the **POST** `/api/v1/token` and providing the following values in the form serialization: -* `code`: code value returned from `authorize`. -* `grant_type`: set value to "authorization_code". -* `redirect_uri`: the same `redirect_uri` used in `authorize`. -* `client_id`: the client ID set in the config.yaml file. -* `client_secret`: the client secret value set in the config.yaml file. +- `code`: code value returned from `authorize`. +- `grant_type`: set value to `authorization_code`. +- `redirect_uri`: the same `redirect_uri` used in `authorize`. +- `client_id`: the client ID set in the `config.yaml` file. +- `client_secret`: the client secret value set in the `config.yaml` file. **Example**: @@ -63,39 +60,36 @@ grant_type=authorization_code& redirect_uri=http%3A%2F%2Flocalhost%3A1606%2Fcallback.html& client_id=example-client& client_secret=insecure_client_secret - ``` -The `id_token` is returned by the OpenDID Service in the response body serialized in a JSON object. +The OpenDID service returns the `id_token` in the response body serialized as a JSON object. ```json { - "access_token":"SsFhhSBMWsLeDMxVUVGreKARNwYxMZtGFfBr0-ZiH6iondSmwPRvQDqkG6Fh", - "token_type":"bearer", - "refresh_token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkaWQ6a2lsdDo0b0VkNENVV3RwbkxUVnZENVBFd2lMUmlqMWdzQmprS1JMbVpES2lCOEdqN2I2V0wiLCJ3M24iOiJjdXN0b20iLCJleHAiOjE3MTY4MTYwNjQsImlhdCI6MTcxNjgxNTQ2NCwiaXNzIjoiZGlkOmtpbHQ6NHJzQkE3dEQ1S1E4TDlXSGpGallRdUhrTWtha2NmSGRDNUNhUVVjVXh5VWpEVkhBIiwiYXVkIjoiYXV0aGVudGljYXRpb24iLCJwcm8iOnsiRW1haWwiOiJhYmR1bEBraWx0LmlvIn0sIm5vbmNlIjoidmVkdXI0b200OWVpOHc5MWp0N3d0In0.yOmE_9jWKcAu8LpjVx7IsFyOOvlKbgo2oC4Imf-qrLY", - "id_token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkaWQ6a2lsdDo0b0VkNENVV3RwbkxUVnZENVBFd2lMUmlqMWdzQmprS1JMbVpES2lCOEdqN2I2V0wiLCJ3M24iOiJjdXN0b20iLCJleHAiOjE3MTY4MTU1MjQsImlhdCI6MTcxNjgxNTQ2NCwiaXNzIjoiZGlkOmtpbHQ6NHJzQkE3dEQ1S1E4TDlXSGpGallRdUhrTWtha2NmSGRDNUNhUVVjVXh5VWpEVkhBIiwiYXVkIjoiYXBwbGljYXRpb24iLCJwcm8iOnsiRW1haWwiOiJhYmR1bEBraWx0LmlvIn0sIm5vbmNlIjoidmVkdXI0b200OWVpOHc5MWp0N3d0In0.YlRE9EGnSExQCb5m2iy4__58PZJlZdCZMsSvsuW4oj8" + "access_token": "SsFhhSBMWsLeDMxVUVGreKARNwYxMZtGFfBr0-ZiH6iondSmwPRvQDqkG6Fh", + "token_type": "bearer", + "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkaWQ6a2lsdDo0b0VkNENVV3RwbkxUVnZENVBFd2lMUmlqMWdzQmprS1JMbVpES2lCOEdqN2I2V0wiLCJ3M24iOiJjdXN0b20iLCJleHAiOjE3MTY4MTYwNjQsImlhdCI6MTcxNjgxNTQ2NCwiaXNzIjoiZGlkOmtpbHQ6NHJzQkE3dEQ1S1E4TDlXSGpGallRdUhrTWtha2NmSGRDNUNhUVVjVXh5VWpEVkhBIiwiYXVkIjoiYXV0aGVudGljYXRpb24iLCJwcm8iOnsiRW1haWwiOiJhYmR1bEBraWx0LmlvIn0sIm5vbmNlIjoidmVkdXI0b200OWVpOHc5MWp0N3d0In0.yOmE_9jWKcAu8LpjVx7IsFyOOvlKbgo2oC4Imf-qrLY", + "id_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkaWQ6a2lsdDo0b0VkNENVV3RwbkxUVnZENVBFd2lMUmlqMWdzQmprS1JMbVpES2lCOEdqN2I2V0wiLCJ3M24iOiJjdXN0b20iLCJleHAiOjE3MTY4MTU1MjQsImlhdCI6MTcxNjgxNTQ2NCwiaXNzIjoiZGlkOmtpbHQ6NHJzQkE3dEQ1S1E4TDlXSGpGallRdUhrTWtha2NmSGRDNUNhUVVjVXh5VWpEVkhBIiwiYXVkIjoiYXBwbGljYXRpb24iLCJwcm8iOnsiRW1haWwiOiJhYmR1bEBraWx0LmlvIn0sIm5vbmNlIjoidmVkdXI0b200OWVpOHc5MWp0N3d0In0.YlRE9EGnSExQCb5m2iy4__58PZJlZdCZMsSvsuW4oj8" } ``` :::note -In full-stack applications, calling the `token` endpoint is usually done through the backend to improve security. +In full-stack applications, calling the `token` endpoint is usually done through the back end to improve security. ::: - -The `id_token` is a JWT signed by the JWT key-pair specified in the config.yaml file of the OpenDID Service, it can be verified using the JWT public key, for example, by the backend of the Web app. +The `id_token` is a JSON web token (JWT) signed by the JWT key-pair specified in the `config.yaml` file of the OpenDID service. Yout can be verified using the JWT public key, for example, by the backend of the Web app. ## Implicit Flow - Initiate the flow by redirecting to the **GET** `/api/v1/authorize` endpoint on the OpenDID Service and setting the following query parameters: -* `response_type`: set value to `id_token` to indicate Implicit Flow. -* `client_id`: The client ID set in the config.yaml file. -* `redirect_uri`: OpenDID will redirect to this URL after authentication. -* `scope`: set value to `openid`. -* `state`: set to a secure random number. -* `nonce`: optional value, set to a secure random number. +- `response_type`: set value to `id_token` to indicate Implicit Flow. +- `client_id`: The client ID set in the config.yaml file. +- `redirect_uri`: OpenDID will redirect to this URL after authentication. +- `scope`: set value to `openid`. +- `state`: set to a secure random number. +- `nonce`: optional value, set to a secure random number. **Example**: @@ -113,6 +107,7 @@ After successful authentication, OpenDID will redirect back to the provided `red **fragment components**. **Example**: + ``` /callback.html# id_token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkaWQ6a2lsdDo0b0VkNENVV3RwbkxUVnZENVBFd2lMUmlqMWdzQmprS1JMbVpES2lCOEdqN2I2V0wiLCJ3M24iOiJjdXN0b20iLCJleHAiOjE3MTY4ODQ5MDYsImlhdCI6MTcxNjg4NDg0NiwiaXNzIjoiZGlkOmtpbHQ6NHJzQkE3dEQ1S1E4TDlXSGpGallRdUhrTWtha2NmSGRDNUNhUVVjVXh5VWpEVkhBIiwiYXVkIjoiYXBwbGljYXRpb24iLCJwcm8iOnsiRW1haWwiOiJhYmR1bEBraWx0LmlvIn0sIm5vbmNlIjoiOTFzN2ZnZDZvcjR3c2NkdGVtcXQifQ.xTy3Oyc5e-vlP10mGy0f9GqNU4LV97s77s-l7w5EwF0& diff --git a/docs/develop/08_opendid/05_demo_project.md b/docs/develop/08_opendid/05_demo_project.md index 809129588..406dc0ca4 100644 --- a/docs/develop/08_opendid/05_demo_project.md +++ b/docs/develop/08_opendid/05_demo_project.md @@ -19,7 +19,7 @@ docker run -d -it --rm \ docker.io/kiltprotocol/opendid-demo ``` -The demo page will run on [http://localhost:1606](http://localhost:1606). +The demo page will run on _http://localhost:1606_. For this demo to work a running OpenDID Service is needed, an Identity Wallet (e.g. [Sporran](https://www.sporran.org/)) with a DID and Credential issued by the required attester specified in the `config.yaml` file (Default is SocialKYC). diff --git a/docs/develop/08_opendid/06_advanced.md b/docs/develop/08_opendid/06_advanced.md index 4214a77b8..7c65ced30 100644 --- a/docs/develop/08_opendid/06_advanced.md +++ b/docs/develop/08_opendid/06_advanced.md @@ -3,7 +3,7 @@ id: advanced title: Advanced Usage --- -### Use dynamic client management +## Use dynamic client management If you want to dynamically create or remove OpenID Connect clients, you can configure the service to get its configuration from an [etcd cluster](https://etcd.io). To do so, configure the connection parameters for the etcd cluster in the `config.yaml` file. @@ -50,7 +50,7 @@ CLIENT_SPEC=$(echo $CLIENT_SPEC | jq -c) etcdctl put /opendid/clients/new-client "${CLIENT_SPEC}" ``` -If you want to try this out you can first generate a config using the setup image as described above, add the etcd configuration and then start the service using the example script in [./scripts/start-demo-etcd.sh](./scripts/start-demo-etcd.sh). +If you want to try this out you can first generate a config using the setup image as described above, add the etcd configuration and then start the service using the example script in _./scripts/start-demo-etcd.sh_. ### Add advanced claim checks using RHAI scripts diff --git a/docs/participate/01_staking/01_become_a_collator/03_setup_node.md b/docs/participate/01_staking/01_become_a_collator/03_setup_node.md index 42e979570..d7d47eff5 100644 --- a/docs/participate/01_staking/01_become_a_collator/03_setup_node.md +++ b/docs/participate/01_staking/01_become_a_collator/03_setup_node.md @@ -74,7 +74,7 @@ This can either be `peregrine` or `spiritnet`. Hence, to start a collator node for the Spiritnet network, the parameter would be `--chain=spiritnet`. Unfortunately, there is no hardcoded chain spec for the Peregrine network, so the full path of the chainspec file must be provided `--chain=/node/dev-specs/kilt-parachain/peregrine-kilt.json`. -Please refer to the [KILT node repository](https://github.com/KILTprotocol/kilt-node/blob/develop/dev-specs/kilt-parachain/peregrine-kilt.json) or the [Docker image](https://hub.docker.com/r/kiltprotocol/kilt-node/tags) for more information. +Please refer to the [KILT node repository](https://github.com/KILTprotocol/kilt-node/blob/master/dev-specs/kilt-parachain/peregrine-kilt.json) or the [Docker image](https://hub.docker.com/r/kiltprotocol/kilt-node/tags) for more information. ### Specify the Blockchain Storage Path diff --git a/markdown-link-check.config.json b/markdown-link-check.config.json index 145246f3f..a00c94747 100644 --- a/markdown-link-check.config.json +++ b/markdown-link-check.config.json @@ -16,6 +16,9 @@ "ignorePatterns": [ { "pattern": "^#.+" + }, + { + "pattern": "/(localhost)." } ] } \ No newline at end of file From 8af6141cfadee7344351683ac73dbd77058fbc88 Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Mon, 10 Jun 2024 11:33:56 +1000 Subject: [PATCH 04/16] Review Signed-off-by: Chris Chinchilla --- docs/develop/08_opendid/03_opendid_service.md | 63 ++++++------- .../08_opendid/04_integrate_opendid.md | 12 +-- docs/develop/08_opendid/05_demo_project.md | 16 ++-- docs/develop/08_opendid/06_advanced.md | 92 +++++++++---------- docusaurus.config.js | 18 +++- 5 files changed, 105 insertions(+), 96 deletions(-) diff --git a/docs/develop/08_opendid/03_opendid_service.md b/docs/develop/08_opendid/03_opendid_service.md index 855e6ba90..d93ef8883 100644 --- a/docs/develop/08_opendid/03_opendid_service.md +++ b/docs/develop/08_opendid/03_opendid_service.md @@ -18,43 +18,45 @@ Before running the `opendid-setup` container, set two environment variables: 1. `SEED` to provide an account with funds (minimum of 3 KILT) for the DID generation. -```bash -export SEED="dont try this seed its completely made up for this nice example" -``` + ```bash + export SEED="dont try this seed its completely made up for this nice example" + ``` 2. `ENDPOINT` -Set to "spiritnet" if the account is on the spiritnet production network. + Set to "spiritnet" if the account is on the spiritnet production network. -```bash -export ENDPOINT="spiritnet" -``` + ```bash + export ENDPOINT="spiritnet" + ``` -Set to "peregrine" if the account is on the peregrine test network. + Set to "peregrine" if the account is on the peregrine test network. -```bash -export ENDPOINT="peregrine" -``` + ```bash + export ENDPOINT="peregrine" + ``` -Then run the setup with the following command: + Then run the setup with the following command: -```bash -docker run --rm -it -e "ENDPOINT=${ENDPOINT}" -v $(pwd):/data docker.io/kiltprotocol/opendid-setup:latest "${SEED}" -``` + ```bash + docker run --rm -it -e "ENDPOINT=${ENDPOINT}" -v $(pwd):/data docker.io/kiltprotocol/opendid-setup:latest "${SEED}" + ``` The command generates a set of new mnemonics and then derives a DID from them and generates multiple files into the current directory: 1. `config.yaml` The configuration file used by the OpenDID service. 2. `did-secrets.json` This file contains the public and secret keys in the DID Document. -Keep a secure backup of this file as it contains all the secret keys. + :::warning + Keep a secure backup of this file as it contains all the secret keys. + ::: 3. `did-document.json` contains the DID Document generated by this setup. -:::danger -You only need the `config.yaml` to run the OpenDID service. -This file includes the generated mnemonic and secret keys and you should protect it from unauthorized access. -::: + :::danger + You only need the `config.yaml` to run the OpenDID service. + This file includes the generated mnemonic and secret keys and you should protect it from unauthorized access. + ::: The container generates sensible defaults in the `config.yaml` file, but here are some values you might want to change: @@ -81,7 +83,7 @@ The container generates sensible defaults in the `config.yaml` file, but here ar When you've made changes to the `config.yaml` file, you can run the OpenDID service. -1. Specify the runtime through the `RUNTIME` environment variable: +1. Specify the runtime through the `RUNTIME` environment variable: Set to `"spiritnet"` for production KILT @@ -95,20 +97,19 @@ When you've made changes to the `config.yaml` file, you can run the OpenDID serv export RUNTIME="peregrine" ``` -2. Run the `docker.io/kiltprotocol/opendid` docker image . +2. Run the `docker.io/kiltprotocol/opendid` docker image. -```bash -docker run -d --rm \ - -v $(pwd)/config.yaml:/app/config.yaml \ - -v $(pwd)/checks:/app/checks \ - -e "RUNTIME=${RUNTIME}" \ - -p 3001:3001 \ - docker.io/kiltprotocol/opendid:latest -``` + ```bash + docker run -d --rm \ + -v $(pwd)/config.yaml:/app/config.yaml \ + -v $(pwd)/checks:/app/checks \ + -e "RUNTIME=${RUNTIME}" \ + -p 3001:3001 \ + docker.io/kiltprotocol/opendid:latest + ``` 3. Open the login page at _http://localhost:3001_. ## Next steps With configuration in place and a service running, next you need to [integrate OpenDID into an application](./04_integrate_opendid.md) so that a user can use the login page. - diff --git a/docs/develop/08_opendid/04_integrate_opendid.md b/docs/develop/08_opendid/04_integrate_opendid.md index 2fd0b7514..0eeb3352a 100644 --- a/docs/develop/08_opendid/04_integrate_opendid.md +++ b/docs/develop/08_opendid/04_integrate_opendid.md @@ -77,16 +77,16 @@ The OpenDID service returns the `id_token` in the response body serialized as a In full-stack applications, calling the `token` endpoint is usually done through the back end to improve security. ::: -The `id_token` is a JSON web token (JWT) signed by the JWT key-pair specified in the `config.yaml` file of the OpenDID service. Yout can be verified using the JWT public key, for example, by the backend of the Web app. +The `id_token` is a JSON web token (JWT) signed by the JWT key-pair specified in the `config.yaml` file of the OpenDID service. +You can verify this using the JWT public key, for example, by the back end of the Web app. -## Implicit Flow +## Implicit flow -Initiate the flow by redirecting to the **GET** `/api/v1/authorize` endpoint on the OpenDID Service and setting the following query -parameters: +Initiate the flow by redirecting to the **GET** `/api/v1/authorize` endpoint on the OpenDID Service and setting the following query parameters: - `response_type`: set value to `id_token` to indicate Implicit Flow. - `client_id`: The client ID set in the config.yaml file. -- `redirect_uri`: OpenDID will redirect to this URL after authentication. +- `redirect_uri`: OpenDID redirects to this URL after authentication. - `scope`: set value to `openid`. - `state`: set to a secure random number. - `nonce`: optional value, set to a secure random number. @@ -103,7 +103,7 @@ GET /api/v1/authorize? nonce=ia7sa06ungxdfzaqphk2 HTTP/1.1 ``` -After successful authentication, OpenDID will redirect back to the provided `redirect_uri` with `id_token` and `state` +After successful authentication, OpenDID redirects back to the provided `redirect_uri` with `id_token` and `state` **fragment components**. **Example**: diff --git a/docs/develop/08_opendid/05_demo_project.md b/docs/develop/08_opendid/05_demo_project.md index 406dc0ca4..c4b48fc9e 100644 --- a/docs/develop/08_opendid/05_demo_project.md +++ b/docs/develop/08_opendid/05_demo_project.md @@ -6,10 +6,13 @@ title: Demo Project The example code at [demo-project](https://github.com/KILTprotocol/opendid/tree/main/demo-project) contains a minimal application that uses OpenDID. It's an [express](https://expressjs.com) application that exposes three things: -- A login page that handles the dispatching of the user to the opendid. -- A callback page for the openid connect flow to accept the token. +- A login page that handles the dispatching of the user to the OpenDID service. +- A callback page for the OpenID connect flow to accept the token. - A protected resource that only authenticated users can access. +For the demo application to work you need a running OpenDID Service and an identity wallet (e.g. [Sporran](https://www.sporran.org/)) with a DID and Credential issued by the required attester specified in the `config.yaml` file (Default is SocialKYC). +If you follow the steps in this section in order, you have all the necessary components for the demo application to run. + Run the pre-configured demo application with the following command: ```bash @@ -19,12 +22,9 @@ docker run -d -it --rm \ docker.io/kiltprotocol/opendid-demo ``` -The demo page will run on _http://localhost:1606_. - -For this demo to work a running OpenDID Service is needed, an Identity Wallet (e.g. [Sporran](https://www.sporran.org/)) -with a DID and Credential issued by the required attester specified in the `config.yaml` file (Default is SocialKYC). +The demo page runs on _http://localhost:1606_. It pre-fills the Client ID value and offers login buttons to follow the implicit or authorization code flow. :::note -The JWT secret can be set with the `TOKEN_SECRET` environment variable inside the docker container. It must match -the one specified in the `config.yaml` file to correctly verify the `id_token`. Default is `super-secret-jwt-secret`. +You can set the JSON web token (JWT) secret can with the `TOKEN_SECRET` environment variable inside the docker container. It must match +the one specified in the `config.yaml` file to correctly verify the `id_token`. The default is `super-secret-jwt-secret`. ::: diff --git a/docs/develop/08_opendid/06_advanced.md b/docs/develop/08_opendid/06_advanced.md index 7c65ced30..48db7918e 100644 --- a/docs/develop/08_opendid/06_advanced.md +++ b/docs/develop/08_opendid/06_advanced.md @@ -3,33 +3,32 @@ id: advanced title: Advanced Usage --- -## Use dynamic client management +## Use dynamic client management with etcd -If you want to dynamically create or remove OpenID Connect clients, you can configure the service to get its configuration from an [etcd cluster](https://etcd.io). -To do so, configure the connection parameters for the etcd cluster in the `config.yaml` file. +To dynamically create or remove OpenID Connect clients, configure the service to get its configuration from an [etcd cluster](https://etcd.io) by adding the connection parameters for the cluster in the `config.yaml` file. ```yaml etcd: - endpoints: ["localhost:2379"] - user: etcd-user - password: my-password - tlsDomainName: my.etcd.cluster.example.com - tlsCaCert: | - -----BEGIN CERTIFICATE----- - - -----END CERTIFICATE----- - tlsClientCert: | - -----BEGIN CERTIFICATE----- - - -----END CERTIFICATE----- - tlsClientKey: | - -----BEGIN RSA PRIVATE KEY----- - - -----END RSA PRIVATE KEY----- + endpoints: ['localhost:2379'] + user: etcd-user + password: my-password + tlsDomainName: my.etcd.cluster.example.com + tlsCaCert: | + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + tlsClientCert: | + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + tlsClientKey: | + -----BEGIN RSA PRIVATE KEY----- + + -----END RSA PRIVATE KEY----- ``` -All fields except `endpoints` are optional and depending on your etcd setup you might not need them. -When everything is set up you can start putting client configurations into the etcd cluster. +All fields except `endpoints` are optional. +When everything is set up you can start adding client configurations into the etcd cluster. ```bash CLIENT_SPEC=$(cat <help us test this new feature!', + content: + 'DIP enables OpenID inspired cross-chain identity, help us test this new feature!', backgroundColor: '#2db528', textColor: '#fff', isCloseable: true, @@ -98,6 +99,11 @@ module.exports = { docId: 'develop/dApp/welcome', label: 'DApp Documentation', }, + { + type: 'doc', + docId: 'develop/opendid/what-is-opendid', + label: 'OpenDID Documentation', + }, ], }, { @@ -239,7 +245,10 @@ module.exports = { documents: ['README.md'], modifyContent(filename, content) { if (filename.includes('README')) { - var trimContent = content.replace("# Decentralized Identity Provider (DIP) provider pallet", "# Provider pallet") + var trimContent = content.replace( + '# Decentralized Identity Provider (DIP) provider pallet', + '# Provider pallet' + ) return { filename: '02_provider.md', content: trimContent, @@ -260,7 +269,10 @@ module.exports = { documents: ['README.md'], modifyContent(filename, content) { if (filename.includes('README')) { - var trimContent = content.replace("# Decentralized Identity Provider (DIP) consumer pallet", "# Consumer pallet") + var trimContent = content.replace( + '# Decentralized Identity Provider (DIP) consumer pallet', + '# Consumer pallet' + ) return { filename: '03_consumer.md', content: trimContent, From a568b1d476e9c533cbc33d135cfd5547cdd028cc Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Tue, 11 Jun 2024 11:04:46 +1000 Subject: [PATCH 05/16] Update docs/develop/08_opendid/01_overview.md Co-authored-by: Antonio --- docs/develop/08_opendid/01_overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/08_opendid/01_overview.md b/docs/develop/08_opendid/01_overview.md index 88cb3a7bc..da6d140f4 100644 --- a/docs/develop/08_opendid/01_overview.md +++ b/docs/develop/08_opendid/01_overview.md @@ -7,7 +7,7 @@ title: Overview It follows the [OpenID Connect 1.0 Specification](https://openid.net/specs/openid-connect-core-1_0.html#Introduction) and acts as a bridge between the decentralized identity world and the centralized authentication world supporting both the implicit and Authorization Code Flow. -A major use of OpenDID is Single Sign-On (SSO) is to use the same DID and credentials to sign into multiple platforms and web services. For instance, by adding a "Sign in with KILT" button to a webpage. +A major use of OpenDID is Single Sign-On (SSO), which allows users to use the same DID and credentials to sign into multiple platforms and web services. For instance, by adding a "Sign in with KILT" button to a webpage. Although integrating that functionality into a webpage is relatively simple, configuring and running OpenDID is more involved. From 748d5a8f44e18dfd928cde66701409f02adc874f Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Tue, 11 Jun 2024 11:05:03 +1000 Subject: [PATCH 06/16] Update docs/develop/08_opendid/01_overview.md Co-authored-by: Antonio --- docs/develop/08_opendid/01_overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/08_opendid/01_overview.md b/docs/develop/08_opendid/01_overview.md index da6d140f4..f599db770 100644 --- a/docs/develop/08_opendid/01_overview.md +++ b/docs/develop/08_opendid/01_overview.md @@ -19,7 +19,7 @@ To learn more about the flow of OpenDID, see the [OpenDID Flow](./02_opendid_flo ## Project container structure -The project consist of multiple parts that supplement and interact with each other all shipped as docker containers and released to docker hub. +The project consist of multiple parts that supplement and interact with each other all shipped as Docker containers and released to Docker Hub. ### opendid-setup container From 156a8ea23f4b4f08107e77bc9100d9b9faa33505 Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Tue, 11 Jun 2024 11:05:35 +1000 Subject: [PATCH 07/16] Update docs/develop/08_opendid/04_integrate_opendid.md Co-authored-by: Antonio --- docs/develop/08_opendid/04_integrate_opendid.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/08_opendid/04_integrate_opendid.md b/docs/develop/08_opendid/04_integrate_opendid.md index 0eeb3352a..ecd10e611 100644 --- a/docs/develop/08_opendid/04_integrate_opendid.md +++ b/docs/develop/08_opendid/04_integrate_opendid.md @@ -77,7 +77,7 @@ The OpenDID service returns the `id_token` in the response body serialized as a In full-stack applications, calling the `token` endpoint is usually done through the back end to improve security. ::: -The `id_token` is a JSON web token (JWT) signed by the JWT key-pair specified in the `config.yaml` file of the OpenDID service. +The `id_token` is a bearer JSON web token (JWT) signed by the JWT key-pair specified in the `config.yaml` file of the OpenDID service. You can verify this using the JWT public key, for example, by the back end of the Web app. ## Implicit flow From 927c5cc91d5e5a83fec9a7f85703c562ac28fe38 Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Tue, 11 Jun 2024 11:08:13 +1000 Subject: [PATCH 08/16] Update docs/develop/08_opendid/04_integrate_opendid.md --- docs/develop/08_opendid/04_integrate_opendid.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/08_opendid/04_integrate_opendid.md b/docs/develop/08_opendid/04_integrate_opendid.md index ecd10e611..505b0e3af 100644 --- a/docs/develop/08_opendid/04_integrate_opendid.md +++ b/docs/develop/08_opendid/04_integrate_opendid.md @@ -78,7 +78,7 @@ In full-stack applications, calling the `token` endpoint is usually done through ::: The `id_token` is a bearer JSON web token (JWT) signed by the JWT key-pair specified in the `config.yaml` file of the OpenDID service. -You can verify this using the JWT public key, for example, by the back end of the Web app. +You must verify this using the JWT public key, for example, by the back end of the Web app. ## Implicit flow From b2c0030b5022f3e48f8e1a1234eab700db52ebac Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Tue, 11 Jun 2024 11:08:31 +1000 Subject: [PATCH 09/16] Update docs/develop/08_opendid/05_demo_project.md Co-authored-by: Antonio --- docs/develop/08_opendid/05_demo_project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/08_opendid/05_demo_project.md b/docs/develop/08_opendid/05_demo_project.md index c4b48fc9e..e1fb0a9bb 100644 --- a/docs/develop/08_opendid/05_demo_project.md +++ b/docs/develop/08_opendid/05_demo_project.md @@ -7,7 +7,7 @@ The example code at [demo-project](https://github.com/KILTprotocol/opendid/tree/ It's an [express](https://expressjs.com) application that exposes three things: - A login page that handles the dispatching of the user to the OpenDID service. -- A callback page for the OpenID connect flow to accept the token. +- A callback page for one of the OpenID Connect flows supported to accept the token. - A protected resource that only authenticated users can access. For the demo application to work you need a running OpenDID Service and an identity wallet (e.g. [Sporran](https://www.sporran.org/)) with a DID and Credential issued by the required attester specified in the `config.yaml` file (Default is SocialKYC). From aa93ade7f5e6664edf290acd578113bed2178ac8 Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Tue, 11 Jun 2024 11:09:00 +1000 Subject: [PATCH 10/16] Update docs/develop/08_opendid/06_advanced.md Co-authored-by: Antonio --- docs/develop/08_opendid/06_advanced.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/08_opendid/06_advanced.md b/docs/develop/08_opendid/06_advanced.md index 48db7918e..6240b9c18 100644 --- a/docs/develop/08_opendid/06_advanced.md +++ b/docs/develop/08_opendid/06_advanced.md @@ -107,5 +107,5 @@ docker run -d --rm \ docker.io/kiltprotocol/opendid:latest ``` -When you now log in with a user that has an email address ending with `kilt.io` the service allows you to log in. +When you now log in with a user that has an email address ending with `kilt.io` as attested by the configured attester, the service allows you to log in. If you use a different email address, the service denies you access. \ No newline at end of file From 004377a07d70d5e75e907dccdaaae8442d442d38 Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Tue, 11 Jun 2024 11:09:32 +1000 Subject: [PATCH 11/16] Update docs/develop/08_opendid/03_opendid_service.md Co-authored-by: Antonio --- docs/develop/08_opendid/03_opendid_service.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/08_opendid/03_opendid_service.md b/docs/develop/08_opendid/03_opendid_service.md index d93ef8883..95f9523a2 100644 --- a/docs/develop/08_opendid/03_opendid_service.md +++ b/docs/develop/08_opendid/03_opendid_service.md @@ -7,7 +7,7 @@ title: Run OpenDID Service ## Configuration -Running the OpenDID service requires some configuration and a DID. +Running the OpenDID service requires some configuration and a KILT DID. The DID establishes a secure session with an identity wallet using a key agreement key of type `X25519KeyAgreementKey2019` included in the DID Document generated by the setup container. OpenDID serves a [well-known DID configuration](https://identity.foundation/.well-known/resources/did-configuration/), which the identity wallet uses to ensure that the domain is linked to the specified DID. From a76c357d999d18a399cf0b7351886a14bf66da9c Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Tue, 11 Jun 2024 11:09:53 +1000 Subject: [PATCH 12/16] Update docs/develop/08_opendid/03_opendid_service.md Co-authored-by: Antonio --- docs/develop/08_opendid/03_opendid_service.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/08_opendid/03_opendid_service.md b/docs/develop/08_opendid/03_opendid_service.md index 95f9523a2..f00c8b460 100644 --- a/docs/develop/08_opendid/03_opendid_service.md +++ b/docs/develop/08_opendid/03_opendid_service.md @@ -72,7 +72,7 @@ The container generates sensible defaults in the `config.yaml` file, but here ar :::note info - The generated `config.yaml` requires an [email credential](https://test.ctypehub.galaniprojects.de/ctype/kilt:ctype:0x3291bb126e33b4862d421bfaa1d2f272e6cdfc4f96658988fbcffea8914bd9ac) issued by an attester. + The generated default `config.yaml` requires an [email credential](https://test.ctypehub.galaniprojects.de/ctype/kilt:ctype:0x3291bb126e33b4862d421bfaa1d2f272e6cdfc4f96658988fbcffea8914bd9ac) issued by an attester. ::: From 10cf605a932968ccdebea3908442d14c28d07b6d Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Tue, 11 Jun 2024 11:12:11 +1000 Subject: [PATCH 13/16] Update docs/develop/08_opendid/04_integrate_opendid.md Co-authored-by: Antonio --- docs/develop/08_opendid/04_integrate_opendid.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/08_opendid/04_integrate_opendid.md b/docs/develop/08_opendid/04_integrate_opendid.md index 505b0e3af..841609dd4 100644 --- a/docs/develop/08_opendid/04_integrate_opendid.md +++ b/docs/develop/08_opendid/04_integrate_opendid.md @@ -13,7 +13,7 @@ Initiate the flow by redirecting to the **GET** `/api/v1/authorize` endpoint on parameters: - `response_type`: set value to `code` to indicate Authorization Code Flow. -- `client_id`: The client ID set in the config.yaml file. +- `client_id`: The client ID set in the `config.yaml` file. - `redirect_uri`: OpenDID will redirect to this URL after authentication. - `scope`: set value to `openid`. - `state`: set to a secure random number. From 04a3ba71985142085293cf06013ddef79133fcbf Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Tue, 11 Jun 2024 11:21:40 +1000 Subject: [PATCH 14/16] Changes Signed-off-by: Chris Chinchilla --- docs/develop/08_opendid/02_opendid_flow.md | 4 ++-- docs/develop/08_opendid/03_opendid_service.md | 14 +++++++------- docs/develop/08_opendid/05_demo_project.md | 2 +- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/develop/08_opendid/02_opendid_flow.md b/docs/develop/08_opendid/02_opendid_flow.md index 2f2cc1f09..85ffa3645 100644 --- a/docs/develop/08_opendid/02_opendid_flow.md +++ b/docs/develop/08_opendid/02_opendid_flow.md @@ -13,7 +13,7 @@ Common use cases include the following: - Web app back end - OpenDID front end - OpenDID back end -- Identity wallet (a browser extension, for example, [Sporran](https://www.sporran.org/)) +- Identity wallet that follows [the Credential API spec](https://github.com/KILTprotocol/spec-ext-credential-api) (typically a browser extension, for example, [Sporran](https://www.sporran.org/)) The following steps outline the interactions necessary to implement the Implicit Flow: @@ -70,5 +70,5 @@ AB->>AF: (10) Access granted. :::info Although this example describes the implicit flow, the authorization code flow is similar. -Instead of returning an `id_token` directly, the OpenDID service instead returns a `code` to exhange for an `id_token` using the `token` endpoint. +Instead of returning an `id_token` directly, the OpenDID service instead returns a `code` to exchange for an `id_token` using the `token` endpoint. ::: diff --git a/docs/develop/08_opendid/03_opendid_service.md b/docs/develop/08_opendid/03_opendid_service.md index f00c8b460..f78f8714c 100644 --- a/docs/develop/08_opendid/03_opendid_service.md +++ b/docs/develop/08_opendid/03_opendid_service.md @@ -67,17 +67,17 @@ The container generates sensible defaults in the `config.yaml` file, but here ar - The client ID as a key (The default is: `example-client`). - The `requirements` section, including: - - What CTypes are required for authentication. - - The trusted attesters as an address (The default is for the [SocialKYC attester](https://socialkyc.io/)). + - What CTypes are required for authentication. + - The trusted attesters as an address (The default is for the [SocialKYC attester](https://socialkyc.io/)). - :::note info + :::note info - The generated default `config.yaml` requires an [email credential](https://test.ctypehub.galaniprojects.de/ctype/kilt:ctype:0x3291bb126e33b4862d421bfaa1d2f272e6cdfc4f96658988fbcffea8914bd9ac) issued by an attester. + The generated default `config.yaml` requires an [email credential](https://test.ctypehub.galaniprojects.de/ctype/kilt:ctype:0x3291bb126e33b4862d421bfaa1d2f272e6cdfc4f96658988fbcffea8914bd9ac) issued by an attester. - ::: + ::: - - What `redirect_url`s the service accepts (The default is `http://localhost:1606/callback.html` for the demo project). - - The `clientSecret` is optional but recommended. If you use the authorization code flow, the `token` endpoint requires it. + - What `redirect_url`s the service accepts (The default is `http://localhost:1606/callback.html` for the demo project). + - The `clientSecret` is optional but recommended. If you use the authorization code flow, the `token` endpoint requires it. ## Run the service diff --git a/docs/develop/08_opendid/05_demo_project.md b/docs/develop/08_opendid/05_demo_project.md index e1fb0a9bb..2eac69810 100644 --- a/docs/develop/08_opendid/05_demo_project.md +++ b/docs/develop/08_opendid/05_demo_project.md @@ -10,7 +10,7 @@ It's an [express](https://expressjs.com) application that exposes three things: - A callback page for one of the OpenID Connect flows supported to accept the token. - A protected resource that only authenticated users can access. -For the demo application to work you need a running OpenDID Service and an identity wallet (e.g. [Sporran](https://www.sporran.org/)) with a DID and Credential issued by the required attester specified in the `config.yaml` file (Default is SocialKYC). +For the demo application to work you need a running OpenDID Service and an identity wallet that follows [the Credential API spec](https://github.com/KILTprotocol/spec-ext-credential-api) (e.g. [Sporran](https://www.sporran.org/)) with a DID and Credential issued by the required attester specified in the `config.yaml` file (Default is SocialKYC). If you follow the steps in this section in order, you have all the necessary components for the demo application to run. Run the pre-configured demo application with the following command: From 1563bcf2e3aa5afef5ca39f4313109be95866924 Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Tue, 11 Jun 2024 13:03:24 +1000 Subject: [PATCH 15/16] Fixes Signed-off-by: Chris Chinchilla --- docs/develop/08_opendid/02_opendid_flow.md | 4 ++-- docs/develop/08_opendid/04_integrate_opendid.md | 5 ++--- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/develop/08_opendid/02_opendid_flow.md b/docs/develop/08_opendid/02_opendid_flow.md index 85ffa3645..d1bda7e7e 100644 --- a/docs/develop/08_opendid/02_opendid_flow.md +++ b/docs/develop/08_opendid/02_opendid_flow.md @@ -15,7 +15,7 @@ Common use cases include the following: - OpenDID back end - Identity wallet that follows [the Credential API spec](https://github.com/KILTprotocol/spec-ext-credential-api) (typically a browser extension, for example, [Sporran](https://www.sporran.org/)) -The following steps outline the interactions necessary to implement the Implicit Flow: +The following steps outline the interactions necessary to implement [the implicit flow](https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth): 1. The user clicks the login button on the *web app front end*. 2. The *web app front end* redirects the user to the *OpenDID front end*. @@ -69,6 +69,6 @@ AB->>AF: (10) Access granted. ``` :::info -Although this example describes the implicit flow, the authorization code flow is similar. +Although this example describes the implicit flow, [the authorization code flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) is similar. Instead of returning an `id_token` directly, the OpenDID service instead returns a `code` to exchange for an `id_token` using the `token` endpoint. ::: diff --git a/docs/develop/08_opendid/04_integrate_opendid.md b/docs/develop/08_opendid/04_integrate_opendid.md index 841609dd4..6757cee95 100644 --- a/docs/develop/08_opendid/04_integrate_opendid.md +++ b/docs/develop/08_opendid/04_integrate_opendid.md @@ -9,12 +9,11 @@ Read the [demo project guide](05_demo_project.md) for an example of integrating ## Authorization code flow -Initiate the flow by redirecting to the **GET** `/api/v1/authorize` endpoint on the OpenDID service and setting the following query -parameters: +Initiate the flow by redirecting to the **GET** `/api/v1/authorize` endpoint on the OpenDID service and setting the following query URL-encoded parameters: - `response_type`: set value to `code` to indicate Authorization Code Flow. - `client_id`: The client ID set in the `config.yaml` file. -- `redirect_uri`: OpenDID will redirect to this URL after authentication. +- `redirect_uri`: OpenDID redirects to this URL after authentication. - `scope`: set value to `openid`. - `state`: set to a secure random number. - `nonce`: optional value, set to a secure random number. From fc6f3560eabe761497fbad0384a52f59971618f1 Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Wed, 12 Jun 2024 12:30:07 +1000 Subject: [PATCH 16/16] Review Signed-off-by: Chris Chinchilla --- docs/develop/08_opendid/02_opendid_flow.md | 2 +- docs/develop/08_opendid/03_opendid_service.md | 11 ++++++----- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/develop/08_opendid/02_opendid_flow.md b/docs/develop/08_opendid/02_opendid_flow.md index d1bda7e7e..49dc3e272 100644 --- a/docs/develop/08_opendid/02_opendid_flow.md +++ b/docs/develop/08_opendid/02_opendid_flow.md @@ -9,7 +9,7 @@ Understanding this flow is helpful for setting up and configuring an OpenDID Ser OpenDID includes interactions between multiple apps to authenticate and authorize users. Common use cases include the following: -- Web app Frontend (app that includes the login button, for example, the demo app) +- Web app front end (app that includes the login button, for example, the demo app) - Web app back end - OpenDID front end - OpenDID back end diff --git a/docs/develop/08_opendid/03_opendid_service.md b/docs/develop/08_opendid/03_opendid_service.md index f78f8714c..ccb6213f3 100644 --- a/docs/develop/08_opendid/03_opendid_service.md +++ b/docs/develop/08_opendid/03_opendid_service.md @@ -45,6 +45,12 @@ Before running the `opendid-setup` container, set two environment variables: The command generates a set of new mnemonics and then derives a DID from them and generates multiple files into the current directory: 1. `config.yaml` The configuration file used by the OpenDID service. + + :::warning + You only need the `config.yaml` to run the OpenDID service. + This file includes the generated mnemonic and secret keys and you should protect it from unauthorized access. + ::: + 2. `did-secrets.json` This file contains the public and secret keys in the DID Document. :::warning @@ -53,11 +59,6 @@ The command generates a set of new mnemonics and then derives a DID from them an 3. `did-document.json` contains the DID Document generated by this setup. - :::danger - You only need the `config.yaml` to run the OpenDID service. - This file includes the generated mnemonic and secret keys and you should protect it from unauthorized access. - ::: - The container generates sensible defaults in the `config.yaml` file, but here are some values you might want to change: - Set `production` to true, this only allows secure connections.