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