mirror of
https://github.com/OpenBankProject/OBP-API.git
synced 2026-02-06 09:26:53 +00:00
docfix/Some info about using OBP-OIDC as a development OIDC server
This commit is contained in:
simonredfern
parent
72d3626ff7
commit
fc0672b48e
186
OBP_OIDC_Configuration_Guide.md
Normal file
186
OBP_OIDC_Configuration_Guide.md
Normal file
@ -0,0 +1,186 @@
|
||||
# OBP-OIDC Configuration Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide explains how to configure OBP API to work with (the updated) OBP-OIDC development server that uses URL-based issuer identifiers instead of semantic identifiers.
|
||||
|
||||
Please take this doc with a LARGE pinch of salt (it was generated by AI).
|
||||
|
||||
## Background
|
||||
|
||||
The OBP-OIDC server has been updated to use a hybrid approach:
|
||||
|
||||
- **Old issuer format**: `"obp-oidc"` (semantic identifier)
|
||||
- **New issuer format**: `"http://localhost:9000/obp-oidc"` (URL-based for JWT validation)
|
||||
|
||||
This change was made to improve JWT validation standards compliance and interoperability.
|
||||
|
||||
## Configuration Changes
|
||||
|
||||
### 1. Properties File Updates
|
||||
|
||||
Update your `default.props` file with the following configurations:
|
||||
|
||||
```properties
|
||||
# OAuth2 Provider Selection
|
||||
oauth2.oidc_provider=obp-oidc
|
||||
|
||||
# OBP-OIDC OAuth2 Provider Settings
|
||||
oauth2.obp_oidc.host=http://localhost:9000
|
||||
oauth2.obp_oidc.issuer=http://localhost:9000/obp-oidc
|
||||
oauth2.obp_oidc.well_known=http://localhost:9000/obp-oidc/.well-known/openid-configuration
|
||||
|
||||
# OAuth2 JWKS URI configuration for token validation
|
||||
oauth2.jwk_set.url=http://localhost:9000/obp-oidc/jwks
|
||||
|
||||
# OpenID Connect Client Configuration
|
||||
openid_connect_1.button_text=OBP-OIDC
|
||||
openid_connect_1.client_id=obp-api-client
|
||||
openid_connect_1.client_secret=your-client-secret
|
||||
openid_connect_1.callback_url=http://localhost:8080/auth/openid-connect/callback
|
||||
openid_connect_1.endpoint.discovery=http://localhost:9000/obp-oidc/.well-known/openid-configuration
|
||||
openid_connect_1.endpoint.authorization=http://localhost:9000/obp-oidc/auth
|
||||
openid_connect_1.endpoint.userinfo=http://localhost:9000/obp-oidc/userinfo
|
||||
openid_connect_1.endpoint.token=http://localhost:9000/obp-oidc/token
|
||||
openid_connect_1.endpoint.jwks_uri=http://localhost:9000/obp-oidc/jwks
|
||||
openid_connect_1.access_type_offline=true
|
||||
```
|
||||
|
||||
### 2. Environment-Specific Configuration
|
||||
|
||||
#### Development (HTTP, localhost)
|
||||
|
||||
```properties
|
||||
oauth2.obp_oidc.host=http://localhost:9000
|
||||
oauth2.obp_oidc.issuer=http://localhost:9000/obp-oidc
|
||||
oauth2.jwk_set.url=http://localhost:9000/obp-oidc/jwks
|
||||
```
|
||||
|
||||
#### Production (HTTPS, custom domain)
|
||||
|
||||
```properties
|
||||
oauth2.obp_oidc.host=https://oidc.yourdomain.com
|
||||
oauth2.obp_oidc.issuer=https://oidc.yourdomain.com/obp-oidc
|
||||
oauth2.jwk_set.url=https://oidc.yourdomain.com/obp-oidc/jwks
|
||||
```
|
||||
|
||||
#### Docker/Container Environment
|
||||
|
||||
```properties
|
||||
oauth2.obp_oidc.host=http://obp-oidc:9000
|
||||
oauth2.obp_oidc.issuer=http://obp-oidc:9000/obp-oidc
|
||||
oauth2.jwk_set.url=http://obp-oidc:9000/obp-oidc/jwks
|
||||
```
|
||||
|
||||
## Key Changes Made
|
||||
|
||||
### 1. Code Changes
|
||||
|
||||
#### OAuth2.scala
|
||||
|
||||
- Updated `obpOidcIssuer` to be configurable via `oauth2.obp_oidc.issuer` property
|
||||
- Modified `wellKnownOpenidConfiguration` to use the new `/obp-oidc` path
|
||||
- Enhanced `checkUrlOfJwkSets` method to handle URL-based issuers more robustly
|
||||
|
||||
#### Properties Files
|
||||
|
||||
- Added `oauth2.obp_oidc.issuer` configuration option
|
||||
- Updated default well-known endpoint paths
|
||||
- Added `oauth2.jwk_set.url` configuration for JWKS validation
|
||||
|
||||
### 2. Backward Compatibility
|
||||
|
||||
The system maintains backward compatibility by:
|
||||
|
||||
- Supporting both semantic and URL-based issuer matching
|
||||
- Providing sensible defaults when properties are not configured
|
||||
- Gracefully handling different URL formats (HTTP/HTTPS, different hosts/ports)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### 1. "OBP-20208: Cannot match the issuer and JWKS URI"
|
||||
|
||||
**Cause**: The JWKS URI in `oauth2.jwk_set.url` doesn't match the issuer in JWT tokens.
|
||||
|
||||
**Solution**: Ensure the `oauth2.jwk_set.url` contains the correct JWKS endpoint that corresponds to your issuer:
|
||||
|
||||
```properties
|
||||
oauth2.jwk_set.url=http://your-oidc-server:port/obp-oidc/jwks
|
||||
```
|
||||
|
||||
#### 2. Well-known endpoint not found
|
||||
|
||||
**Cause**: The well-known configuration endpoint path is incorrect.
|
||||
|
||||
**Solution**: Verify the `oauth2.obp_oidc.well_known` property points to the correct endpoint:
|
||||
|
||||
```properties
|
||||
oauth2.obp_oidc.well_known=http://your-oidc-server:port/obp-oidc/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
#### 3. JWT token validation fails
|
||||
|
||||
**Cause**: The issuer in JWT tokens doesn't match the configured issuer.
|
||||
|
||||
**Solution**: Ensure `oauth2.obp_oidc.issuer` matches exactly what the OBP-OIDC server puts in the `iss` claim:
|
||||
|
||||
```properties
|
||||
oauth2.obp_oidc.issuer=http://your-oidc-server:port/obp-oidc
|
||||
```
|
||||
|
||||
### Debugging Tips
|
||||
|
||||
1. **Enable Debug Logging**: Add to your logback configuration:
|
||||
|
||||
```xml
|
||||
<logger name="code.api.OAuth2" level="DEBUG"/>
|
||||
<logger name="code.api.util.JwtUtil" level="DEBUG"/>
|
||||
```
|
||||
|
||||
2. **Verify JWT Token Contents**: Use online JWT decoders to inspect the `iss` claim in your tokens.
|
||||
|
||||
3. **Test Well-known Endpoint**: Verify the endpoint is accessible:
|
||||
|
||||
```bash
|
||||
curl http://localhost:9000/obp-oidc/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
4. **Test JWKS Endpoint**: Verify the JWKS endpoint returns valid keys:
|
||||
```bash
|
||||
curl http://localhost:9000/obp-oidc/jwks
|
||||
```
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
- [ ] Update `oauth2.obp_oidc.issuer` property with full URL
|
||||
- [ ] Update `oauth2.obp_oidc.well_known` property with new path
|
||||
- [ ] Set `oauth2.jwk_set.url` property with correct JWKS URL
|
||||
- [ ] Update all OpenID Connect endpoint URLs to include `/obp-oidc` path
|
||||
- [ ] Test JWT token validation with `/obp/v5.1.0/users/current` endpoint
|
||||
- [ ] Verify well-known endpoint discovery works
|
||||
- [ ] Test with different environments (HTTP/HTTPS, different hosts)
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **HTTPS in Production**: Always use HTTPS for production deployments:
|
||||
|
||||
```properties
|
||||
oauth2.obp_oidc.host=https://your-domain.com
|
||||
```
|
||||
|
||||
2. **Client Secret Management**: Store client secrets securely and rotate them regularly.
|
||||
|
||||
3. **JWKS Caching**: The system caches JWKS keys - consider the cache TTL in key rotation scenarios.
|
||||
|
||||
4. **Network Security**: Ensure the OBP API can reach the OBP-OIDC server's JWKS endpoint.
|
||||
|
||||
## Support
|
||||
|
||||
For issues related to this configuration:
|
||||
|
||||
1. Check the OBP API logs for detailed error messages
|
||||
2. Verify all endpoints are accessible from the OBP API server
|
||||
3. Ensure the OBP-OIDC server is running the updated version with URL-based issuers
|
||||
4. Test the configuration step by step using the troubleshooting section
|
||||
Loading…
Reference in New Issue
Block a user