OBP-API/OBP_OIDC_Configuration_Guide.md

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:

# 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)

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)

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

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:

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:

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:

oauth2.obp_oidc.issuer=http://your-oidc-server:port/obp-oidc

Debugging Tips

1. Enable Debug Logging: Add to your logback configuration:

   <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:

   curl http://localhost:9000/obp-oidc/.well-known/openid-configuration
   

4. Test JWKS Endpoint: Verify the JWKS endpoint returns valid keys:

   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:

   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