-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* docs: add readme Signed-off-by: Pat Losoponkul <[email protected]> * docs: getting started docker section Signed-off-by: Pat Losoponkul <[email protected]> * docs: complete getting started Signed-off-by: Pat Losoponkul <[email protected]> * docs: release badge Signed-off-by: Pat Losoponkul <[email protected]> * docs: undo force pushed that revert fixes Signed-off-by: Pat Losoponkul <[email protected]> --------- Signed-off-by: Pat Losoponkul <[email protected]>
- Loading branch information
patlo-iog
authored
Jun 12, 2024
1 parent
38e5825
commit 01f504d
Showing
1 changed file
with
102 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,102 @@ | ||
| # Identus Keycloak Plugins | ||
|
|
||
|  | ||
|  | ||
|
|
||
| # Overview | ||
|
|
||
| This repository provides a Keycloak Plugin that extends Keycloak's functionality to handle Self-Sovereign Identity (SSI) tasks, | ||
| including OpenID for verifiable credential issuance. | ||
|
|
||
| # Getting started | ||
|
|
||
| ## Using published docker image | ||
|
|
||
| ### Default Keycloak plugin image | ||
|
|
||
| The plugin is available as a pre-bundled Docker image. | ||
| This image includes Keycloak and the plugin enabled for basic use cases. | ||
| For a more complex setup, the JAR file published in the Maven repository should be used to build a custom Keycloak image. | ||
| The docker-compose configuration below allows spinning up a basic Keycloak instance with the plugin enabled as part of the Identus cloud agent stack. | ||
|
|
||
| ```yaml | ||
| services: | ||
| keycloak-oid4vci-issuer: | ||
| image: ghcr.io/hyperledger/identus-keycloak-plugins:0.1.0 | ||
| ports: | ||
| - "9980:8080" | ||
| command: | ||
| - start-dev | ||
| - --features=preview | ||
| - --health-enabled=true | ||
| - --hostname-url=http://localhost:9980 | ||
| - --hostname-admin-url=http://localhost:9980 | ||
| environment: | ||
| IDENTUS_URL: <AGENT_URL> # point to cloud agent instance | ||
| KEYCLOAK_ADMIN: admin | ||
| KEYCLOAK_ADMIN_PASSWORD: admin | ||
| restart: always | ||
|
|
||
| # Identus cloud agent and other services below | ||
| ``` | ||
|
|
||
| ### Customized Keycloak plugin image | ||
|
|
||
| In many cases, Keycloak customization is necessary for branding or to meet custom | ||
| authentication and authorization requirements. The default plugin image can be used | ||
| in conjunction with docker multi-stage builds to extract the Keycloak plugin JARs and | ||
| create a customized Keycloak image. | ||
|
|
||
| The image contains plugin JARs in the `/opt/keycloak/providers` directory | ||
|
|
||
| Example `Dockerfile` | ||
|
|
||
| ``` | ||
| FROM ghcr.io/hyperledger/identus-keycloak-plugins:0.1.0 AS dist | ||
| FROM quay.io/keycloak/keycloak:23.0.7 | ||
| COPY --from=dist /opt/keycloak/providers/<PLUGIN_FILE>.jar /opt/keycloak/providers/<PLUGIN_FILE>.jar | ||
| # more steps to customize assets / themes / providers | ||
| RUN /opt/keycloak/bin/kc.sh build | ||
| ENTRYPOINT [ "/opt/keycloak/bin/kc.sh" ] | ||
| ``` | ||
|
|
||
| Please refer to the official [Keycloak documentation](https://www.keycloak.org/server/containers) | ||
| for customization using JAR providers. | ||
|
|
||
| ## Using published JAR | ||
|
|
||
| Each plugin is available individually on [Github maven packages](https://github.com/orgs/hyperledger/packages?repo_name=identus-keycloak-plugins), | ||
| for easy integration with your build process and fine-grained control over which plugins are included when customizing Keycloak. | ||
|
|
||
| Please refer to the official [Keycloak documentation](https://www.keycloak.org/server/containers) | ||
| for customization using JAR providers. | ||
|
|
||
| # Available Plugins | ||
|
|
||
| ## `identus-keycloak-oid4vci` | ||
|
|
||
| Extends Keycloak for integration with Hyperledger Identus Cloud Agent in [OID4VCI](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html) flow. | ||
| The Keycloak instance to use this is the Issuer Authorization Server where the plugin takes care of | ||
| the OpenID extension in the issuance flow. | ||
| The plugin supports the Authorization Endpoint and Token Endpoint according to the specification. | ||
| Additionally, the plugin communicates with the cloud agent during holder authorization to coordinate the issuance session. | ||
|
|
||
| ### Features | ||
|
|
||
| - [Authorization code flow](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-authorization-code-flow) | ||
| - _AuthorizationRequest_ supported parameters | ||
| - [`issuer_state`](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#section-5.1.3-2.3) | ||
| - _TokenResponse_ supported parameters | ||
| - [`c_nonce`](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#section-6.2-4.1) | ||
| - [`c_nonce_expires_in`](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#section-6.2-4.2) | ||
| - [Pre-authorized-code flow](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-pre-authorized-code-flow) | ||
| - Not yet supported | ||
|
|
||
| ### Environment Variables | ||
|
|
||
| |Name|Description| | ||
| |-|-| | ||
| |`IDENTUS_URL`|URL of the Identus Cloud Agent to coordinate the issuance session.| |