Kory Draughn, Chief Technologist

Martin Flores, Software Developer

iRODS Consortium

iRODS HTTP API v0.5.0

June 17-20, 2025

iRODS User Group Meeting 2025

Durham, NC

Updates since UGM 2023

v0.1.0

  • 88 issues closed - 10 bugs, 57 enhancements

 

v0.2.0

  • 57 issues closed - 11 bugs, 25 enhancements
  • Simplified OIDC configuration
  • Improved separation between HTTP status codes and iRODS status codes
  • Improved API documentation
  • Improved API usage by constraining input requirements
  • Improved stability
  • Configuration validation on server startup

 

v0.3.0

  • 6 issues closed - 1 bug, 4 enhancements
  • Improved support for OIDC - Protected Resource mode
  • Improved support for TLS between HTTP API and iRODS server

OAuth & OIDC in v0.3.0

User Mapping - Overview

  • Abstracted Mapping of JWTs to iRODS users
  • Previously built-in mapping now plugins
    • user_attribute_mapping -> libirods_http_api_plugin-local_file.so
    • irods_user_claim -> libirods_http_api_plugin-user_claim.so
  • Flexible mapping
    • e.g. query an external service for the mappings

User Mapping - Overview

User Mapping - Plugin Interface

  • Simple C interface
  • Full documentation in interface.h 
/// Initializes the user mapping plugin.
int user_mapper_init(const char* _args);

/// Matches the given information to a user.
int user_mapper_match(const char* _param, char** _match);

/// Frees a C-string generated from the user mapping plugin.
void user_mapper_free(char* _data);

/// Executes clean-up for the user mapping plugin.
int user_mapper_close();

User Mapping - Local File Configuration Example

...
// Defines relevant information related to the User Mapping plugin system.
// Allows for the selection and configuration of the plugin.
"user_mapping": {
  // The full path to the desired plugin to load.
  "plugin_path": "/some/path/libirods_http_api_plugin-local_file.so",

  // The configuration information required by
  // the selected plugin to execute properly.
  "configuration": {
    "file_path": "/some-file.json"
  }
}
...
...
"user_attribute_mapping": {
  "rodsBob": {
    "email": "bob@bobtopia.example",
    "sub": "a.very.real.sub",
    "phone_number": "56709"
  },
  "rodsAlice": {
    "email": "al-1s@wonderland.example",
    "sub": "a.different.sub"
  }
}
...

Old Configuration

New Configuration

User Mapping - Local File Configuration Example

Text

{
    "rodsAlice": {
        "email": "alice@example.org",
        "sub": "123-abc-456-xyz"
    },
    "rodsBob": {
        "email": "bob@example.org",
        "phone": "56709"
    }
}

Local File Mapping Example

User Mapping User Claim Configuration Example

...
"user_mapping": {
  "plugin_path": "/some/path/libirods_http_api_plugin-user_claim.so",

  "configuration": {
    "irods_user_claim": "irods_username"
  }
}
...
...
"irods_user_claim": "irods_username"
...

Old Configuration

New Configuration

Local JWT Access Token Validation

Local JWT Access Token Validation

  • Validate Tokens locally using JWKs
  • Similar to access token introspection
  • Retrieve JWKs on first validation attempt
    • Minimal communication to OpenID Provider
  • Support for more OpenID Providers

Local JWT Access Token Validation - Supported Algorithms

Table in Section 3.1 from JWA RFC 7518

Local JWT Access Token Validation - Nonstandard Behavior

  • Some OpenID providers may not use client_secret for symmetric ID Tokens
    • Allow for non-standard client secrets (nonstandard_id_token_secret)
  • JWT Profile for OAuth 2.0 Access Tokens (RFC 9068)
    • Allow for "jwt" vs strictly "at+jwt" in "typ" header

HTTP API as an OAuth 2.0 Protected Resource

Example of Protected Resource Communications

HTTP API Local Validation 

Example of Local Validation

HTTP API Local Validation 

Demo

Future Improvements

  • Encrypted JWTs
    • Depends on jwt-cpp library
  • Fix timeout issue on some Providers
  • Depend on OAuth 2.0 specs only
    • If enough providers support RFC 8414
  • Allow configurable Access Token inspection
  • Remove Client Mode
  • Re-retrieve JWKs when possibly out of date
  • Community suggestions

References

References

OAuth 2.0 Confidential Client

  • OAuth 2.0 Client Authentication
    • Currently Support Password Based Authentication
    • Both Client and Protected Resource modes supported

Alternate User Mapping

  • Previously required mapping in OpenID Provider
  • Provide mapping in configuration file

Alternate User Mapping

Text

...
"openid_connect": {
  ...
  "user_attribute_mapping": {
    "rodsBob": {
      "email": "bob@bobtopia.example",
      "sub": "a.very.real.sub",
      "phone_number": "56709"
    },
    "rodsAlice": {
      "email": "al-1s@wonderland.example",
      "sub": "a.different.sub"
    }
  }
  ...
}
...

User Mapping Example

Alternate User Mapping

  • Protected Resource Mode
    • Map via Introspection Endpoint
  • Client Mode
    • Map via OpenID Connect ID Token
  • Information received dependent on configuration

Alternate User Mapping

Text

{
  "active": true,
  "client_id": "l238j323ds-23ij4",
  "username": "jdoe",
  "scope": "read write dolphin",
  "sub": "Z5O3upPC88QrAjx00dis",
  "aud": "https://protected.example.net/resource",
  "iss": "https://server.example.com/",
  "exp": 1419356238,
  "iat": 1419350238,
  "extension_field": "twenty-seven"
}

Token Introspection Example

HTTP API as an OAuth 2.0 Protected Resource

  • Removes HTTP API from OAuth authentication flows
    • Simplifies Code Executed
    • Streamlines Integration with OpenID Provider
  • Only handle Access Token
  • Currently Supports OAuth 2.0 Introspection Endpoint

HTTP API as an OAuth 2.0 Protected Resource

Example of Protected Resource Communications

Draft Specifications

  • OAuth 2.0 Security Best Practices Draft (Work in Progress)
    • Resource Owner Password Credentials MUST NOT be used 
  • OAuth 2.1 Draft (Work in Progress)
    • Resource Owner Password Credentials Omitted
    • Removal of Implicit Grant

References

Future Work

High Priority

  • Make write operation web-friendly
  • Log client IP or other identifier(s) to distinguish users in log output

 

Medium Priority

  • Externalize OIDC user mapping
  • Update to use 4.3.2 GenQuery2 API
  • Implement missing iRODS API operations

 

Considering

  • Status / Cancellation operations for active transfers
  • Extending the lifetime of Basic Authentication tokens on use
  • Using API documentation generation tool

Thank you!

Questions?

UGM 2025 - iRODS HTTP API v0.5.0

By iRODS Consortium

Source: Martin Flores Jr

UGM 2025 - iRODS HTTP API v0.5.0

  • 59

More from iRODS Consortium