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:

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