{"id":20358076,"url":"https://github.com/irods/irods_client_http_api","last_synced_at":"2025-07-14T16:39:18.552Z","repository":{"id":155503900,"uuid":"625003050","full_name":"irods/irods_client_http_api","owner":"irods","description":"An iRODS C++ HTTP API using Boost.Beast","archived":false,"fork":false,"pushed_at":"2025-05-23T14:59:07.000Z","size":652,"stargazers_count":0,"open_issues_count":91,"forks_count":8,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-05-23T16:21:18.558Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/irods.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-04-07T20:06:07.000Z","updated_at":"2025-05-23T14:59:12.000Z","dependencies_parsed_at":"2024-01-20T00:22:51.035Z","dependency_job_id":"b206a52f-947f-4e7f-9c30-4f60097e9c5e","html_url":"https://github.com/irods/irods_client_http_api","commit_stats":null,"previous_names":["irods/irods_client_http_api"],"tags_count":5,"template":false,"template_full_name":"irods/irods_project_template_cpp_client","purl":"pkg:github/irods/irods_client_http_api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irods%2Firods_client_http_api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irods%2Firods_client_http_api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irods%2Firods_client_http_api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irods%2Firods_client_http_api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/irods","download_url":"https://codeload.github.com/irods/irods_client_http_api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irods%2Firods_client_http_api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265319572,"owners_count":23746364,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T23:25:16.558Z","updated_at":"2025-07-14T16:39:18.538Z","avatar_url":"https://github.com/irods.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# iRODS HTTP API\n\nA project that presents an iRODS Zone as HTTP v1.1.\n\n## Quickstart (Running from Docker Hub Image)\n\nGenerate a local configuration JSON file.\n\n```\ndocker run --rm irods/irods_http_api --dump-config-template \u003e config.json\n```\n\nEdit/update the template `config.json` file (point to your iRODS Zone, remove OIDC and TLS sections, etc.).\n\n```\nvim config.json\n```\n\nLaunch the HTTP API with your customized configuration file to check for success/errors.\n\n```\ndocker run --rm --name irods_http_api \\\n    -v ./config.json:/config.json:ro \\\n    -p 9000:9000 \\\n    irods/irods_http_api\n```\n\nThen, the HTTP API will be available.\n\n```\n$ curl -X POST -u rods:rods \\\n    http://localhost:9000/irods-http-api/\u003cversion\u003e/authenticate\n568bbfc2-7d19-4723-b659-bb9325f9b076\n\n$ curl -s http://localhost:9000/irods-http-api/\u003cversion\u003e/collections \\\n    -H 'Authorization: Bearer 568bbfc2-7d19-4723-b659-bb9325f9b076' \\\n    --data-urlencode 'op=stat' \\\n    --data-urlencode 'lpath=/tempZone/home/rods' -G | jq\n{\n  \"inheritance_enabled\": false,\n  \"irods_response\": {\n    \"status_code\": 0\n  },\n  \"modified_at\": 1699448576,\n  \"permissions\": [\n    {\n      \"name\": \"rods\",\n      \"perm\": \"own\",\n      \"type\": \"rodsadmin\",\n      \"zone\": \"tempZone\"\n    },\n    {\n      \"name\": \"alice\",\n      \"perm\": \"read_object\",\n      \"type\": \"groupadmin\",\n      \"zone\": \"tempZone\"\n    }\n  ],\n  \"registered\": true,\n  \"type\": \"collection\"\n}\n```\n\n## Documentation\n\nAPI documentation can be found in [API.md](./API.md).\n\n## Build Dependencies\n\n- iRODS development package _(4.3.2 or later)_\n- iRODS externals package for boost\n- iRODS externals package for nlohmann-json\n- iRODS externals package for spdlog \n- Curl development package\n- OpenSSL development package\n\n## Build\n\n**IMPORTANT: As documented under [Build Dependencies](#build-dependencies), the minimum version requirement for the iRODS development package is 4.3.2 or later. As a result, support for the [GenQuery2 API plugin](https://github.com/irods/irods_api_plugin_genquery2) has been removed. To use GenQuery2, the iRODS HTTP API must be connected to a server running iRODS 4.3.2 or later.**\n\nTo build this project, follow the normal CMake build steps.\n```bash\nmkdir build # Preferably outside of the repository\ncd build\ncmake /path/to/repository\nmake package # Use -j to use more parallelism.\n```\n\nUpon success, you should have an installable package.\n\n## Docker\n\nThis project provides two types of Dockerfiles, some for building packages on various operating systems, and one for running the application.\n\n**IMPORTANT: All commands in the sections that follow assume you are located in the root of the repository.**\n\n### The Builder Image\n\nThe builder image is responsible for building the iRODS HTTP API package. Before you can use it, you must build the image. To do that, run the following:\n```bash\ndocker build -t irods-http-api-builder -f irods_builder.ub22.Dockerfile .\n```\n\nWith the builder image in hand, all that's left is to build the iRODS HTTP API project. The builder image is designed to compile code sitting on your machine. This is important because it gives you the ability to build any fork or branch of the project. **Keep in mind the [GenQuery2 API plugin](https://github.com/irods/irods_api_plugin_genquery2) is no longer supported.**\n\nBuilding the package requires mounting the project into the container at the appropriate location. The command you run should look similar to the one below. **Don't forget to create the directory which will hold your packages!**\n```bash\ndocker run -it --rm \\\n    -v /path/to/irods_client_http_api:/http_api_source:ro \\\n    -v /path/to/packages_directory:/packages_output \\\n    irods-http-api-builder\n```\n\nIf everything succeeds, you will have a DEB package in the local directory you mapped to **/packages_output**.\n\n### The Runner Image\n\nThe runner image is responsible for running the iRODS HTTP API. Building the runner image requires the DEB package for the iRODS HTTP API to exist on the local machine. See the previous section for details on generating the package.\n\nTo build the image, run the following command:\n```bash\ndocker build -t irods-http-api-runner \\\n    -f irods_runner.Dockerfile \\\n    /path/to/packages/directory\n```\n\nIf all goes well, you will have a containerized iRODS HTTP API server! You can verify this by checking the version information. Below is an example.\n```bash\n$ docker run -it --rm irods-http-api-runner -v\nirods_http_api v\u003cversion\u003e-\u003cbuild_sha\u003e\n```\n\n### Launching the Container\n\nTo run the containerized server, you need to provide a configuration file at the correct location. If you do not have a configuration file already, see [Configuration](#configuration) for details.\n\nTo launch the server, run the following command:\n```bash\ndocker run -d --rm --name irods_http_api \\\n    -v /path/to/config/file:/config.json:ro \\\n    -p 9000:9000 \\\n    irods-http-api-runner\n```\n\nThe first thing the server will do is validate the configuration. If the configuration fails validation, the server will exit immediately. If the configuration passes validation, then congratulations, you now have a working iRODS HTTP API server!\n\nYou can view the log output using `docker logs -f` or by passing `-it` to `docker run` instead of `-d`.\n\nIf for some reason the default schema file is not sufficient, you can instruct the iRODS HTTP API to use a different schema file. See the following example.\n```bash\n# Generate the default JSON schema.\ndocker run -it --rm irods-http-api-runner --dump-default-jsonschema \u003e schema.json\n\n# Tweak the schema.\nvim schema.json\n\n# Launch the server with the new schema file.\ndocker run -d --rm --name irods_http_api \\\n    -v /path/to/config/file:/config.json:ro \\\n    -v ./schema.json:/jsonschema.json:ro \\\n    -p 9000:9000 \\\n    irods-http-api-runner \\\n    --jsonschema-file /jsonschema.json\n```\n\n### Stopping the Container\n\nIf the container was launched with `-it`, use **CTRL-C** or `docker container stop \u003ccontainer_name\u003e` to shut it down.\n\nIf the container was launched with `-d`, use `docker container stop \u003ccontainer_name\u003e`.\n\n## Configuration\n\nBefore you can run the server, you'll need to create a configuration file.\n\nYou can generate a configuration file by running the following:\n```bash\nirods_http_api --dump-config-template \u003e config.json\n```\n\n**IMPORTANT: `--dump-config-template` does not produce a fully working configuration. It must be updated before it can be used.**\n\n### Configuration File Structure\n\nThe JSON structure below represents the default configuration.\n\nNotice how some of the configuration values are wrapped in angle brackets (e.g. `\"\u003cstring\u003e\"`). These are placeholder values that must be updated before launch.\n\n**IMPORTANT: The comments in the JSON structure are there for explanatory purposes and must not be included in your configuration. Failing to follow this requirement will result in the server failing to start up.**\n\n```js\n{\n    // Defines HTTP options that affect how the client-facing component of the\n    // server behaves.\n    \"http_server\": {\n        // The hostname or IP address to bind.\n        // \"0.0.0.0\" instructs the server to listen on all network interfaces.\n        \"host\": \"0.0.0.0\",\n\n        // The port used to accept incoming client requests.\n        \"port\": 9000,\n\n        // The minimum log level needed before logging activity.\n        //\n        // The following values are supported:\n        // - trace\n        // - debug\n        // - info\n        // - warn\n        // - error\n        // - critical\n        \"log_level\": \"info\",\n\n        // Defines options that affect various authentication schemes.\n        \"authentication\": {\n            // The amount of time that must pass before checking for expired\n            // bearer tokens.\n            \"eviction_check_interval_in_seconds\": 60,\n\n            // Defines options for the \"Basic\" authentication scheme.\n            \"basic\": {\n                // The amount of time before a user's authentication\n                // token expires.\n                \"timeout_in_seconds\": 3600\n            },\n\n            // Defines required OIDC related configuration.\n            \"openid_connect\": {\n                // The amount of time before a user's authentication\n                // token expires.\n                \"timeout_in_seconds\": 3600,\n\n                // The url of the OIDC provider, with a path leading to\n                // where the .well-known configuration is.\n                // The protocol will determine the default port used if\n                // none is specified in the url.\n                \"provider_url\": \"https://oidc.example.org/realms/irods\",\n\n                // The client id given to the application by OIDC provider.\n                \"client_id\": \"irods_http_api\",\n\n                // The client secret used for accessing the introspection endpoint.\n                // Optional unless running as a protected resource.\n                \"client_secret\": \"xxxxxxxxxxxxxxx\",\n\n                // The secret used when validating a JWT signed with\n                // a symmetric algorithm (e.g. HS256).\n                // Used if provided, otherwise, defaults to validating\n                // with \"client_secret\".\n                // If provided, it MUST be base64url encoded.\n                \"access_token_secret\": \"xxxxxxxxxxxxxxx\",\n\n                // The secret used when validating an OpenID Connect ID Token\n                // signed with a symmetric algorithm (e.g. HS256).\n                // Used if provided, otherwise, defaults to validating\n                // with \"client_secret\".\n                // If provided, it MUST be base64url encoded.\n                \"nonstandard_id_token_secret\": \"xxxxxxxxxxxxxxx\",\n\n                // Controls whether the HTTP API requires the presence of the\n                // \"aud\" member in the introspection endpoint response. If set\n                // to true and the \"aud\" member is NOT present, the provided\n                // access token will be rejected.\n                \"require_aud_member_from_introspection_endpoint\": false,\n\n                // The OIDC mode the HTTP API will run as.\n                // The following values are supported:\n                // - client:              Run the HTTP API as an OIDC client\n                // - protected_resource:  Run as an OAuth Protected Resource\n                \"mode\": \"client\",\n\n                // URI pointing to the irods HTTP API auth endpoint.\n                \"redirect_uri\": \"https://\u003cdomain\u003e/irods-http-api/\u003cversion\u003e/authenticate\",\n\n                // The amount of time before the OIDC Authorization Code grant\n                // times out, requiring another attempt at authentication.\n                \"state_timeout_in_seconds\": 600,\n\n                // Defines relevant information related to the User Mapping plugin system.\n                // Allows for the selection and configuration of the plugin.\n                \"user_mapping\": {\n                    // The full path to the desired plugin to load.\n                    // See the section titled \"Mapping OpenID Users to iRODS\"\n                    // for more details on available plugins.\n                    \"plugin_path\": \"/path/to/plugin/the_plugin.so\",\n\n                    // The configuration information required by\n                    // the selected plugin to execute properly.\n                    // See the section titled \"Mapping OpenID Users to iRODS\"\n                    // for more details on plugin configuration.\n                    \"configuration\": {\n                    }\n                },\n\n                // The path to the TLS certificates directory used to establish\n                // secure connections between the HTTP API and the OpenID provider.\n                // Typically, this should point to a standard certificate directory\n                // such as \"/etc/ssl/cert\".\n                \"tls_certificates_directory\": \"/path/to/certs\"\n            }\n        },\n\n        // Defines options that affect how client requests are handled.\n        \"requests\": {\n            // The number of threads dedicated to servicing client requests.\n            // When adjusting this value, consider adjusting \"background_io/threads\"\n            // and \"irods_client/connection_pool/size\" as well.\n            \"threads\": 3,\n\n            // The maximum size allowed for the body of a request.\n            \"max_size_of_request_body_in_bytes\": 8388608,\n\n            // The amount of time allowed to service a request. If the timeout\n            // is exceeded, the client's connection is terminated immediately.\n            \"timeout_in_seconds\": 30\n        },\n\n        // Defines options that affect tasks running in the background.\n        // These options are primarily related to long-running tasks.\n        \"background_io\": {\n            // The number of threads dedicated to background I/O.\n            \"threads\": 6\n        }\n    },\n\n    // Defines iRODS connection information.\n    \"irods_client\": {\n        // The hostname or IP of the target iRODS server.\n        \"host\": \"\u003cstring\u003e\",\n\n        // The port of the target iRODS server.\n        \"port\": 1247,\n\n        // The zone of the target iRODS server.\n        \"zone\": \"\u003cstring\u003e\",\n\n        // Defines options for secure communication with the target iRODS server.\n        \"tls\": {\n            // Controls whether the client and server communicate using TLS.\n            //\n            // The following values are supported:\n            // - CS_NEG_REFUSE:    Do not use secure communication.\n            // - CS_NEG_REQUIRE:   Demand secure communication.\n            // - CS_NEG_DONT_CARE: Let the server decide.\n            \"client_server_policy\": \"CS_NEG_REFUSE\",\n\n            // The file containing trusted CA certificates in PEM format.\n            //\n            // Note that the certificates in this file are used in conjunction\n            // with the system default trusted certificates.\n            \"ca_certificate_file\": \"\u003cstring\u003e\",\n\n            // Defines the level of server certificate authentication to\n            // perform.\n            //\n            // The following values are supported:\n            // - none:     Authentication is skipped.\n            // - cert:     The server verifies the certificate is signed by\n            //             a trusted CA.\n            // - hostname: Equivalent to \"cert\", but also verifies the FQDN\n            //             of the iRODS server matches either the common\n            //             name or one of the subjectAltNames.\n            \"verify_server\": \"cert\",\n\n            // Controls whether advanced negotiation is used.\n            //\n            // This option must be set to \"request_server_negotiation\" for\n            // establishing secure communication. \n            \"client_server_negotiation\": \"request_server_negotiation\",\n\n            // Defines the encryption algorithm used for secure communication.\n            \"encryption_algorithm\": \"AES-256-CBC\",\n\n            // Defines the size of key used for encryption.\n            \"encryption_key_size\": 32,\n\n            // Defines the number of hash rounds used for encryption.\n            \"encryption_hash_rounds\": 16,\n\n            // Defines the size of salt used for encryption.\n            \"encryption_salt_size\": 8\n        },\n\n        // Controls how the HTTP API communicates with the iRODS server.\n        //\n        // When set to true, the following applies:\n        // - Only APIs supported by the iRODS 4.2 series will be used.\n        // - Connection pool settings are ignored.\n        // - All HTTP requests will be served using a new iRODS connection.\n        //\n        // When set to false, the HTTP API will take full advantage of the\n        // iRODS server's capabilities.\n        //\n        // This option should be used when the HTTP API is configured to\n        // communicate with an iRODS 4.2 server.\n        //\n        // NOTE: The HTTP API will not be able to detect changes in policy\n        // within the connected iRODS server unless this option is enabled.\n        // See the \"connection_pool\" option for additional details.\n        \"enable_4_2_compatibility\": false,\n\n        // The credentials for the rodsadmin user that will act as a proxy\n        // for all authenticated users.\n        \"proxy_admin_account\": {\n            \"username\": \"\u003cstring\u003e\",\n            \"password\": \"\u003cstring\u003e\"\n        },\n\n        // Defines options for the connection pool.\n        //\n        // The options defined in this section are only used when\n        // \"enable_4_2_compatibility\" is set to false.\n        //\n        // When connection pooling is used, the HTTP API will not be able\n        // to detect changes in policy within the connected iRODS server.\n        // Any changes in policy will require a restart of the HTTP API.\n        //\n        // If this is a concern, set \"enable_4_2_compatibility\" to true to\n        // force the HTTP API to use a new iRODS connection for every HTTP\n        // request. The additional connections will honor any iRODS server\n        // policy changes, but will degrade overall performance.\n        \"connection_pool\": {\n            // The number of connections in the pool.\n            \"size\": 6,\n\n            // The amount of time that must pass before a connection is\n            // renewed (i.e. replaced).\n            \"refresh_timeout_in_seconds\": 600,\n\n            // The number of times a connection can be fetched from the pool\n            // before it is refreshed.\n            \"max_retrievals_before_refresh\": 16,\n\n            // Instructs the connection pool to track changes in resources.\n            // If a change is detected, all connections will be refreshed.\n            \"refresh_when_resource_changes_detected\": true\n        },\n\n        // The maximum number of parallel streams that can be associated to a\n        // single parallel write handle.\n        \"max_number_of_parallel_write_streams\": 3,\n\n        // The maximum number of bytes that can be read from a data object\n        // during a single read operation.\n        \"max_number_of_bytes_per_read_operation\": 8192,\n\n        // The maximum number of bytes that can be written to a data object\n        // during a single write operation.\n        \"max_number_of_bytes_per_write_operation\": 8192,\n\n        // The number of rows that can be returned by a General or Specific\n        // query. If the client specifies a number greater than the value\n        // defined here, it will be clamped to this value. If the client does\n        // not specify a value, it will be defaulted to this value.\n        \"max_number_of_rows_per_catalog_query\": 15\n    }\n}\n```\n\n## Run\n\nTo run the server, do the following:\n```bash\nirods_http_api /path/to/config.json\n```\n\nTo stop the server, you can use **CTRL-C** or send **SIGINT** or **SIGTERM** to the process.\n\n## OpenID Connect\n\nSome additional configuration is required to run the OpenID Connect portion of the HTTP API.\nFollowing are a few points of interest.\n\n### OpenID Provider Requirements and HTTP API Configuration\n\nThe OpenID Provider, at this moment, must support discovery via a well-known endpoint.\nThe URL to the OpenID Provider must be specified in the `provider_url` OIDC configuration parameter.\n\nOne should take care to ensure that `/.well-known/openid-configuration` is not included\nin the configuration parameter, as this is included automatically.\n\nThe OpenID Provider must be running prior to starting the HTTP API server, otherwise, the HTTP API server\nwill not be able to query the required information from the desired OpenID Provider.\n\nAdditionally, the OIDC `redirect_uri` parameter must be set to the HTTP API's authentication endpoint.\nThis is required, as the Authorization Code Grant needs to be redirected back to the HTTP API, to complete\nHTTP API token generation.\n\n### Mapping OpenID Users to iRODS\n\nBefore you can use OpenID with iRODS, you must enable one of the two shipped plugins, or develop your own to suit your specific needs.\n\n#### Local File plugin\n\nWithin the `user_mapping` stanza, set `plugin_path` to the absolute path of `libirods_http_api_plugin-local_file.so`.\nOn most Linux-based systems, the HTTP API user mapping plugins will be installed under `/usr/lib/irods_http_api/user_mapping`.\n\nThis plugin allows for the defining of mappings of iRODS users based on desired attributes.\nThe attributes specified within the file can be updated, and the plugin will reload the file\nto update the mappings without having to restart the server.\n\n##### Configuration\n\nThe required configuration for this plugin is as follows:\n\n```json\n\"configuration\": {\n    \"file_path\": \"/path/to/file.json\"\n}\n```\n\nWhere `file_path` is the full path to a JSON file containing the mapping of desired attributes to an iRODS user.\nAn example of what the JSON file can contain is as follows:\n\n```json\n{\n    \"alice\": {\n        \"email\": \"alice@example.org\",\n        \"sub\": \"123-abc-456-xyz\"\n    },\n    \"bob\": {\n        \"email\": \"bob@example.org\",\n        \"phone\": \"56709\"\n    }\n}\n```\n\n#### User Claim plugin\n\nWithin the `user_mapping` stanza, set `plugin_path` to the absolute path of `libirods_http_api_plugin-user_claim.so`.\nOn most Linux-based systems, the HTTP API user mapping plugins will be installed under `/usr/lib/irods_http_api/user_mapping`.\n\nThis plugin looks for a claim that provides a direct mapping of an authenticated OpenID user to an iRODS user.\nThis requires that you have the ability to add a claim within the OpenID Provider.\n\n##### Configuration\n\nThe configuration for this plugin is as follows:\n\n```json\n\"configuration\": {\n    \"irods_user_claim\": \"claim_to_map_user\"\n}\n```\n\nIn this particular example, `claim_to_map_user` is the claim that maps the OpenID user to an iRODS user.\n\n### Plugin Development\n\nTo develop your own plugin, make sure to conform to the plugin interface defined in [interface.h](./plugins/user_mapping/include/irods/http_api/plugins/user_mapping/interface.h).\nFurther documentation on the interface functions are within the file.\n\n### Supported Grants\n\nCurrently, the HTTP API server supports the following two grants:\n\n- Resource Owner Password Credentials Grant\n- Authorization Code Grant\n\nWhile we also currently support the _Resource Owner Password Credentials Grant_, there are plans to remove\nsupport for this in the future.\n\nReason being, the [OAuth 2.0 Security Best Current Practice](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics) draft,\nas well as the the [OAuth 2.1 Authorization Framework](https://datatracker.ietf.org/doc/draft-ietf-oauth-v2-1/) draft both deprecate that grant.\nMore information can be found on the reasoning for the deprecation in the links provided above.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Firods%2Firods_client_http_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Firods%2Firods_client_http_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Firods%2Firods_client_http_api/lists"}