1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
# GitHub Copilot Instructions for scitokens-cpp
## Project Overview
scitokens-cpp is a C++ library for creating and validating SciTokens (JWT-based authorization tokens for scientific computing). The library uses JWT-cpp for token operations and supports OIDC discovery with JWKS for public key distribution.
## Building the Project
### Prerequisites
- CMake 3.10 or later
- C++11 compatible compiler (gcc, clang)
- OpenSSL 1.1.1 or later (3.0+ recommended)
- libuuid
- sqlite3
- jwt-cpp (included as vendor submodule)
### Build Commands
```bash
# Create build directory
mkdir -p build
cd build
# Configure with CMake (enable tests with -DSCITOKENS_BUILD_UNITTESTS=ON)
cmake .. -DSCITOKENS_BUILD_UNITTESTS=ON
# Build all targets
make
# Install (optional)
sudo make install
```
### CMake Build Options
- Tests are **disabled by default** - use `-DSCITOKENS_BUILD_UNITTESTS=ON` to enable
- Build produces:
- `libSciTokens.so` - Main library
- `scitokens-test` - Unit tests (Google Test)
- `scitokens-integration-test` - Integration tests with real HTTPS server
- `scitokens-generate-jwks` - JWKS generation utility
- Command-line tools: `scitokens-verify`, `scitokens-create`, `scitokens-list-access`, `scitokens-test-access`
## Running Tests
### Unit Tests
```bash
cd build
./scitokens-test
```
Expected: 29 unit tests should pass
### Integration Tests
Integration tests use CTest fixtures with setup/teardown phases:
```bash
cd build/test
ctest --output-on-failure
```
Or run specific test phases:
```bash
ctest -R integration::setup # Start HTTPS JWKS server
ctest -R integration::test # Run integration tests
ctest -R integration::teardown # Stop server
```
**Integration test infrastructure:**
- `test/jwks_server.py` - Python HTTPS server with OIDC discovery and JWKS endpoints
- `test/integration-test-setup.sh` - Generates TLS certificates and starts server
- `test/integration-test-teardown.sh` - Stops server gracefully
- `test/integration_test.cpp` - C++ tests using real HTTPS connections
Expected: 3 integration tests should pass (total time ~1-2 seconds)
### All Tests
```bash
cd build/test
ctest --output-on-failure
```
Expected: 32 total tests (29 unit + 3 integration)
## Code Style
- C++11 standard
- Use `clang-format` for formatting (configuration in project root)
- Format before committing: `clang-format -i src/*.cpp src/*.h`
## Testing Infrastructure Details
### JWKS Server (test/jwks_server.py)
Python HTTPS server that provides:
- `/.well-known/openid-configuration` - OIDC discovery document
- `/oauth2/certs` - JWKS public key endpoint
Server features:
- HTTP/1.1 with keep-alive support
- TLS 1.2+ with self-signed certificates
- Graceful shutdown with SIGTERM
- Logs to `build/tests/integration/server.log`
### Integration Test Flow
1. **Setup**: Generate EC P-256 key pair, create JWKS, generate TLS certificates, start HTTPS server
2. **Test**: Create tokens, verify with JWKS discovery, test dynamic issuer enforcement
3. **Teardown**: Stop server, print logs if tests failed
### Debugging Integration Tests
If integration tests fail:
1. Check server log: `cat build/tests/integration/server.log`
2. Verify server started: `cat build/tests/integration/server_ready`
3. Test HTTPS manually: `curl -k https://localhost:<port>/.well-known/openid-configuration`
## Key Files
- `src/scitokens.cpp`, `src/scitokens.h` - Main library API
- `src/generate_jwks.cpp` - JWKS generation (EC P-256 keys)
- `src/scitokens_internal.cpp` - Token validation and OIDC discovery
- `src/scitokens_cache.cpp` - JWKS caching
- `test/integration_test.cpp` - End-to-end integration tests
- `test/main.cpp` - Google Test unit tests
## Development Workflow
1. Make code changes
2. Build: `cd build && cmake .. && make`
3. Run unit tests: `./scitokens-test`
4. Run integration tests: `cd test && ctest --output-on-failure`
5. Format code: `clang-format -i <modified-files>`
6. Commit with descriptive message
## CI/CD
GitHub Actions runs tests on:
- Ubuntu 22.04 (OpenSSL 3.0.2)
- Ubuntu 24.04 (OpenSSL 3.0.13)
Integration tests verify TLS compatibility across OpenSSL versions.
|
