README (4448B)
1 KYCH OAuth2 Gateway 2 =================== 3 4 A Rust service implementing OAuth2 authorization code flow with OpenID4VP 5 (OID4VP) credential verification. Acts as a bridge between OAuth2 clients 6 (such as GNU Taler exchanges) and the SWIYU verifier. 7 8 For detailed API documentation and man pages intended for GNU Taler docs, 9 see ../documentation/taler-docs/. 10 11 12 Dependencies 13 ------------ 14 15 Build requirements: 16 - Rust (edition 2024) 17 - Cargo 18 19 Runtime requirements: 20 - PostgreSQL 21 22 23 Building 24 -------- 25 26 cargo build --release 27 28 The build produces three binaries: 29 - kych-oauth2-gateway Main gateway service 30 - kych-client-management CLI tool for client management 31 - kych-dbinit Schema creation and migration 32 33 34 Database Setup 35 -------------- 36 37 kych-dbinit creates the schema and brings an existing one up to date; it 38 applies the oauth2gw-000N.sql patches the database does not have yet, in 39 order, and does nothing when there are none: 40 41 kych-dbinit -c kych.conf --sql-dir oauth2_gatewaydb --dry-run 42 kych-dbinit -c kych.conf --sql-dir oauth2_gatewaydb 43 44 It does not create the database itself. ../contrib/kych-dbconfig does that 45 for an installed system (as root, reading /etc/kych/kych.conf), and for a 46 throwaway development database there is 47 48 ./oauth2_gatewaydb/install_db.sh # run from here, not from inside it 49 ./oauth2_gatewaydb/uninstall_db.sh 50 51 52 Configuration 53 ------------- 54 55 Copy kych.conf.example to kych.conf and configure: 56 57 [kych-oauth2-gateway] 58 # Note: comments must stand on a line of their own, never after a value. 59 SERVE = unix 60 UNIXPATH = /path/to/socket 61 UNIXPATH_MODE = 660 62 DATABASE = postgres://... 63 64 # Cryptographic parameters 65 NONCE_BYTES = 32 66 TOKEN_BYTES = 32 67 AUTH_CODE_BYTES = 32 68 AUTH_CODE_TTL_MINUTES = 10 69 70 # Verifiable Credential settings 71 VC_TYPE = betaid-sdjwt 72 VC_FORMAT = dc+sd-jwt 73 VC_ALGORITHMS = {ES256} 74 VC_CLAIMS = {family_name, given_name, birth_date, ...} 75 76 # Client configuration (one section per client) 77 [client_name] 78 CLIENT_ID = ... 79 CLIENT_SECRET = ... 80 VERIFIER_URL = https://verifier.example.com 81 VERIFIER_MANAGEMENT_API_PATH = /management/api/verifications 82 REDIRECT_URI = https://client.example.com/callback 83 ACCEPTED_ISSUER_DIDS = {did:tdw:issuer1, did:tdw:issuer2} 84 85 86 Running 87 ------- 88 89 ./target/release/kych-oauth2-gateway -c /path/to/kych.conf 90 91 92 API Endpoints 93 ------------- 94 95 GET /config VC configuration (type, format, claims) 96 POST /setup/{client_id} Initialize verification session 97 GET /authorize/{nonce} Authorization page with QR code 98 POST /token Exchange authorization code for token 99 GET /info Retrieve verified user information 100 POST /notification Webhook for verifier status updates 101 GET /status/{verification_id} Check verification status 102 POST /finalize/{verification_id} Finalize verification 103 104 105 Client Management 106 ----------------- 107 108 Use the CLI tool to manage OAuth2 clients: 109 110 ./target/release/kych-client-management --help 111 112 113 Testing 114 ------- 115 116 cargo test 117 118 Integration tests are in tests/: 119 - db_integration.rs Database integration tests 120 - handlers_integration.rs HTTP handler tests 121 122 123 Project Structure 124 ----------------- 125 126 src/ 127 main.rs Entry point, server initialization 128 lib.rs Module exports 129 handlers.rs HTTP endpoint handlers 130 config.rs Configuration management 131 models.rs Data structures 132 state.rs Application state 133 crypto.rs Cryptographic operations 134 db/ Database layer 135 mod.rs Database initialization 136 clients.rs Client management 137 authorization_codes.rs Auth code handling 138 sessions.rs Session management 139 tokens.rs Token management 140 141 src/bin/ 142 client_management_cli.rs Client management CLI 143 dbinit.rs Schema creation and migration 144 145 templates/ 146 authorize.html Authorization page template 147 148 oauth2_gatewaydb/ 149 install_db.sh Development database creation 150 oauth2gw-0001.sql Schema patch 1; later patches are 000N.sql 151 versioning.sql Patch-level bookkeeping (the _v schema) 152 drop.sql Cleanup script