https://github.com/curityio/example-consentor
The example consentor is a basic plugin and shows how to prompt user for consent.
https://github.com/curityio/example-consentor
consentor plugin prefix-scope scopes
Last synced: 10 months ago
JSON representation
The example consentor is a basic plugin and shows how to prompt user for consent.
- Host: GitHub
- URL: https://github.com/curityio/example-consentor
- Owner: curityio
- License: apache-2.0
- Created: 2021-03-18T13:19:51.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2021-03-24T14:48:57.000Z (almost 5 years ago)
- Last Synced: 2025-01-30T13:29:39.072Z (12 months ago)
- Topics: consentor, plugin, prefix-scope, scopes
- Language: Java
- Homepage: https://curity.io/resources/learn/example-generic-consentor/
- Size: 376 KB
- Stars: 2
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Example Consentor
[](https://curity.io/resources/code-examples/status/)
[](https://curity.io/resources/code-examples/status/)
A Consentor that takes the value of a (prefix) scope, queries an API for details and presents a screen to the user for confirmation.
This project provides an example of a Consentor plugin for Curity Identity Server. The code shows how to configure and implement a custom Consentor of type `price-consent`. You can do basically anything in a plugin.
In this example we show how you can call an API for getting data during an approval flow. We also show how to present this data to the user.
The resulting Consentor will use an id from the user's session and take the value to query an external API. We assume that the id is part of a prefix scope used by the client. The prefix in this example is called `transactionId`.
## System Requirements
Curity Identity Server 6.0.0 and its system requirements .
## Building the Plugin
The source code is written entirely in Java. You will need Maven 3 and Java SDK 8 to be able to compile the plugin.
You can build the plugin by issuing the command `mvn package`. This will produce a JAR file in the `target` directory. Use this JAR file during installation.
## Installation
As of now there is no binary version of the plugin yet. Before installing compile the code and create a package (see above). The resulting JAR file and its dependencies are then copied in the directory `${IDSVR_HOME}/usr/share/plugins/consent.exampleconsentor` on each node, including the admin node. You can replace the plugin group `consent.exampleconsentor` with any other arbitrary name of your choice.
For a list of the dependencies and their versions, run `mvn dependency:list`. Ensure that all of these are installed in the plugin group; otherwise, they will not be accessible to this plugin and run-time errors will result.
## Creating the Example Consentor
The easiest way to configure a new Consentor is using the Curity admin UI.
- Go to the `Profiles` page. Select a profile of type Token Service Profile. This is where the Consentor instance should be created.
- Navigate lower in the `General` section and at the `Consentors` sub-section click the `New consentor` button.
- Once the pop-up shows up, type a name/identifier for the Consentor and select the type `Price Consent`. Click `Next`.
- Enter the prefix of the scope for the transaction id that the client will request during login. The plugin will take the first scope that starts with the prefix and parse the value (suffix).
- Configure the API endpoint to query. In this example the query will look like `://:?transactionId=` where `` is the suffix from the scope as described above.
- Select an HTTP client that will be used for communicating with the API. The HTTP client defines among others the protocol to be used, i.e. HTTP or HTTPS.
- Commit the configuration changes.
## Using the Example Consentor
Assign the Example Consentor to a client and make sure the client may use the scope defined in the configuration of the Example Consentor. When a user logs in using the client Curity Identity Server will ask for consent before issuing any tokens.
- In `Token Service Profile` open `Clients` and select a client of your choice. We will use a client called `www`.
- Navigate to the section called `OAuth\OpenID Settings` and scroll to the `User Consent` part of the section.
- Enable `User Consent` and `Only Consentors` since we only want to use the custom Consentor from this example and not the built-in screens.
- In the list of Consentors add the Example Consentor configured above.
- Commit the configuration changes.
The Consentor is now ready to be used.
## Testing
When a user logs in with the client Curity Identity Server will show a prompt asking the user for consent. The text on the consent screen was retrieved from the external API. The screen will look similar to this one:
## Under the Hood
### Assumptions
The plugin expects the API to support the query-parameter `transactionId`. The response from the API is a JSON array with the objects that match the query. The plugin then reads the first JSON object in the list. It takes the value of the attribute `total_price` and includes it in the confirmation screen.
### Calling the API
The request to the API looks similar to the following one but changes according to the configuration of the Consentor plugin:
```
GET http://hostname:80/orders?transactionId=123
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"id": 123,
"item_count": 2,
"total_price": 198,
"status": "created",
"transactionId": 123
}
]
```
### Note
This code is just for demonstration. Its purpose is to show the basic features of a consent plugin and provide basic classes. It is by no means complete and has known limitations. For example, it is missing an opt-out workflow, lacks error handling and has hardcoded values, but it includes everything to get started with a Consentor plugin.
#### License
This plugin and its associated documentation is listed under the `Apache 2 license` .
#### More Information
Please visit **curity.io** for more information about the **Curity Identity Server**.
*Copyright (C) 2021 Curity AB*.