README (3762B)
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 two binaries: 29 - kych-oauth2-gateway Main gateway service 30 - kych-client-management CLI tool for client management 31 32 33 Database Setup 34 -------------- 35 36 Set up the PostgreSQL database using the scripts in oauth2_gatewaydb/: 37 38 cd oauth2_gatewaydb 39 ./install_db.sh 40 41 To remove: 42 43 ./uninstall_db.sh 44 45 46 Configuration 47 ------------- 48 49 Copy kych.conf.example to kych.conf and configure: 50 51 [kych-oauth2-gateway] 52 UNIXPATH = /path/to/socket # Unix socket path (or use HOST/PORT) 53 DATABASE = postgres://... # PostgreSQL connection string 54 55 # Cryptographic parameters 56 NONCE_BYTES = 32 57 TOKEN_BYTES = 32 58 AUTH_CODE_BYTES = 32 59 AUTH_CODE_TTL_MINUTES = 10 60 61 # Verifiable Credential settings 62 VC_TYPE = betaid-sdjwt 63 VC_FORMAT = vc+sd-jwt 64 VC_ALGORITHMS = {ES256} 65 VC_CLAIMS = {family_name, given_name, birth_date, ...} 66 67 # Client configuration (one section per client) 68 [client_name] 69 CLIENT_ID = ... 70 CLIENT_SECRET = ... 71 VERIFIER_URL = https://verifier.example.com 72 VERIFIER_MANAGEMENT_API_PATH = /management/api/verifications 73 REDIRECT_URI = https://client.example.com/callback 74 ACCEPTED_ISSUER_DIDS = {did:tdw:issuer1, did:tdw:issuer2} 75 76 77 Running 78 ------- 79 80 ./target/release/kych-oauth2-gateway -c /path/to/kych.conf 81 82 83 API Endpoints 84 ------------- 85 86 GET /config VC configuration (type, format, claims) 87 POST /setup/{client_id} Initialize verification session 88 GET /authorize/{nonce} Authorization page with QR code 89 POST /token Exchange authorization code for token 90 GET /info Retrieve verified user information 91 POST /notification Webhook for verifier status updates 92 GET /status/{verification_id} Check verification status 93 POST /finalize/{verification_id} Finalize verification 94 95 96 Client Management 97 ----------------- 98 99 Use the CLI tool to manage OAuth2 clients: 100 101 ./target/release/kych-client-management --help 102 103 104 Testing 105 ------- 106 107 cargo test 108 109 Integration tests are in tests/: 110 - db_integration.rs Database integration tests 111 - handlers_integration.rs HTTP handler tests 112 113 114 Project Structure 115 ----------------- 116 117 src/ 118 main.rs Entry point, server initialization 119 lib.rs Module exports 120 handlers.rs HTTP endpoint handlers 121 config.rs Configuration management 122 models.rs Data structures 123 state.rs Application state 124 crypto.rs Cryptographic operations 125 db/ Database layer 126 mod.rs Database initialization 127 clients.rs Client management 128 authorization_codes.rs Auth code handling 129 sessions.rs Session management 130 tokens.rs Token management 131 132 src/bin/ 133 client_management_cli.rs Client management CLI 134 135 templates/ 136 authorize.html Authorization page template 137 138 oauth2_gatewaydb/ 139 install_db.sh Database installation 140 oauth2gw-0001.sql Schema migration 141 versioning.sql Version control 142 drop.sql Cleanup script