From fc0672b48e20c8eecd3872ba0aa394dc85cbe19c Mon Sep 17 00:00:00 2001 From: simonredfern Date: Wed, 17 Sep 2025 12:15:29 +0200 Subject: [PATCH] docfix/Some info about using OBP-OIDC as a development OIDC server --- OBP_OIDC_Configuration_Guide.md | 186 ++++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 OBP_OIDC_Configuration_Guide.md diff --git a/OBP_OIDC_Configuration_Guide.md b/OBP_OIDC_Configuration_Guide.md new file mode 100644 index 000000000..8b5e72e81 --- /dev/null +++ b/OBP_OIDC_Configuration_Guide.md @@ -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 + + + ``` + +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