{"id":20471597,"url":"https://github.com/backbase/authorization-server","last_synced_at":"2026-04-18T05:31:10.287Z","repository":{"id":233476907,"uuid":"629030440","full_name":"Backbase/authorization-server","owner":"Backbase","description":"Mastercard OpenBanking Connect - Account Information Authorization Server","archived":false,"fork":false,"pushed_at":"2024-03-20T17:10:18.000Z","size":139,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-11-20T20:02:49.890Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Backbase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-04-17T13:31:19.000Z","updated_at":"2025-04-11T03:37:23.000Z","dependencies_parsed_at":"2024-04-16T10:58:19.584Z","dependency_job_id":"06e2c169-0bd2-498a-95ee-355452d2f96d","html_url":"https://github.com/Backbase/authorization-server","commit_stats":null,"previous_names":["backbase/authorization-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Backbase/authorization-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Backbase%2Fauthorization-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Backbase%2Fauthorization-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Backbase%2Fauthorization-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Backbase%2Fauthorization-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Backbase","download_url":"https://codeload.github.com/Backbase/authorization-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Backbase%2Fauthorization-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31957536,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-15T14:16:41.267Z","updated_at":"2026-04-18T05:31:10.279Z","avatar_url":"https://github.com/Backbase.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Authorization Server for Mastercard OpenBanking Connect\n\n## Overview\n\nThe Authorization Server is a Spring Security OAuth2 Authorization Server implementation that facilitates the **Account Information Services (AIS)** consent flow for [Mastercard OpenBanking Connect](https://developer.mastercard.com/open-banking-connect/documentation/). It implements the OAuth2 and OpenID Connect (OIDC) protocols to [Exchange the PSU Authorization for Access Consent](https://developer.mastercard.com/open-banking-connect/documentation/aisfeatures/exchange-psu-consent/) using the [Account Information Services API](https://developer.mastercard.com/open-banking-connect/documentation/aisfeatures/overview/).\n\nThis server acts as an intermediary between Backbase's Digital Banking Platform and Mastercard's OpenBanking Connect, handling the complex consent authorization flow required for accessing account information.\n\n## Architecture\n\n### Key Components\n\n```\nauthorization-server\n├── ais/                    # Account Information Service specific components\n│   ├── authentication/     # Custom authentication flow for AIS consents\n│   ├── config/            # AIS and OpenBanking API configuration\n│   ├── model/             # AIS domain models\n│   └── repository/        # AIS consent user repository\n├── security/              # Security configuration and token management\n│   ├── authentication/    # OAuth2 authentication customizations\n│   ├── config/           # Security and OAuth2 server configuration\n│   └── token/            # Custom token claim mapping\n└── validator/            # Redirect URI validation\n```\n\n### Authentication Flow\n\nThe server implements a custom authentication flow for AIS consent:\n\n1. **Consent Initiation** - Client requests authorization\n2. **SCA Redirect** - User redirected to Mastercard's SCA interface\n3. **Consent Authorization** - User authorizes consent at ASPSP\n4. **Callback Processing** - Authorization code exchanged for consent\n5. **Token Issuance** - Access token issued with consent claims\n\n## Features\n\n### 1. OAuth2 Authorization Server\n\n**Standards Compliance:**\n- OAuth 2.0 Authorization Framework (RFC 6749)\n- OpenID Connect 1.0\n- OAuth 2.0 Authorization Code Grant\n- Client Credentials Grant\n- Refresh Token Grant\n\n**Endpoints:**\n- `/oauth2/authorize` - Authorization endpoint\n- `/oauth2/token` - Token endpoint\n- `/oauth2/jwks` or custom JWK set endpoint\n- `/protocol/openid-connect/userinfo` - UserInfo endpoint\n- `/protocol/openid-connect/certs` - JWKS endpoint\n\n### 2. AIS Consent Management\n\n**Consent Initiation** (`AiConsentRedirectEntryPoint`)\n- Creates consent request with Mastercard OpenBanking Connect\n- Configures permissions (default: ALLPSD2)\n- Sets consent validity period\n- Generates SCA redirect URL\n- Includes callback URL with ASPSP identification\n\n**Consent Authorization** (`AiConsentAuthenticationProvider`)\n- Exchanges authorization code for consent\n- Retrieves consent ID from Mastercard\n- Maps consent to configured user\n- Builds authenticated principal with ASPSP and consent claims\n\n**Callback Handling** (`AiConsentCallbackFilter`)\n- Processes OAuth callback from Mastercard SCA\n- Extracts authorization query parameters\n- Triggers consent authentication flow\n\n### 3. Custom Token Claims\n\n**Attribute Claim Mapper** (`AttributeClaimMapper`)\n- Maps user attributes to JWT claims\n- Supports custom claim configuration per client\n- Configurable claim inclusion in:\n  - ID Token\n  - Access Token\n  - UserInfo endpoint response\n\n**Standard Claims:**\n- `sub` - User subject identifier\n- `aspspId` - Account Servicing Payment Service Provider ID\n- `consentId` - Consent identifier from Mastercard\n- `preferred_username` - User's preferred username\n\n### 4. Multi-ASPSP Support\n\nThe server supports multiple ASPSPs with individual configurations:\n- ASPSP-specific permissions\n- Configurable consent validity periods\n- User mapping per ASPSP\n- Fallback to default ASPSP\n\n### 5. Security Features\n\n**Client Authentication Methods:**\n- `client_secret_basic` - HTTP Basic authentication\n- `none` - Public clients (PKCE recommended)\n\n**Token Security:**\n- RSA-signed JWTs (RS256)\n- Dynamically generated JWK Set\n- Configurable token lifetimes\n- Refresh token rotation\n\n**Redirect URI Validation:**\n- Allowlist-based validation\n- Permissive mode for development\n- Protection against open redirects\n\n## Technical Stack\n\n- **Framework:** Spring Boot 2.7.10\n- **Java Version:** 17\n- **Security:** Spring Security OAuth2 Authorization Server 0.4.1\n- **API Generation:** OpenAPI Generator\n- **Distributed Tracing:** Spring Cloud Sleuth\n- **Build Tool:** Maven\n- **Containerization:** Jib\n\n## Configuration\n\n### Application Properties\n\n**Server Configuration:**\n```yaml\nserver:\n  port: 8081\n```\n\n**Mastercard OpenBanking Connect API:**\n```yaml\nmastercard:\n  mcob:\n    api:\n      base-uri: https://developer.mastercard.com/apigwproxy/openbanking/connect/api\n      proxy:\n        enabled: false\n        host: proxy.example.com\n        port: 8080\n    ais:\n      aspsps:\n        - id: 420e5cff-0e2a-4156-991a-f6eeef0478cf  # ASPSP identifier\n          permissions:\n            - ALLPSD2                                # Or specific permissions\n          consent-validity: PT15M                    # ISO-8601 duration\n          available-consents:\n            - user:\n                username: sara\n                roles: \n                  - USER\n```\n\n**Security Configuration:**\n```yaml\nsecurity:\n  authorization:\n    server-configuration:\n      \"[settings.authorization-server.jwk-set-endpoint]\": /protocol/openid-connect/certs\n      \"[settings.authorization-server.oidc-user-info-endpoint]\": /protocol/openid-connect/userinfo\n    public-paths:\n      - /favicon.ico\n      - /actuator/**\n    code-flow:\n      permissive-redirect: true  # Development only\n    client-registration:\n      my-client:\n        secret: \"{noop}secret\"  # Use {bcrypt} in production\n        client-authentication-methods:\n          - client_secret_basic\n        authorization-grant-types:\n          - authorization_code\n          - refresh_token\n        redirect-uris:\n          - https://my-app.example.com/callback\n        scopes:\n          - openid\n          - profile\n        token-configuration:\n          \"[settings.token.claim-mappers]\":\n            - attributeName: aspspId\n              toAccessToken: true\n            - attributeName: consentId\n              toAccessToken: true\n            - attributeName: preferred_username\n              toIdToken: true\n```\n\n### Client Registration\n\nClients are configured in `application.yml` under `security.authorization.client-registration`:\n\n**Example Client (Keycloak Broker):**\n```yaml\nkeycloak-broker-client:\n  secret: \"{noop}secret\"\n  client-authentication-methods:\n    - client_secret_basic\n  authorization-grant-types:\n    - client_credentials\n    - authorization_code\n    - refresh_token\n  redirect-uris:\n    - http://localhost:8180/auth/realms/mastercard/broker/mastercard/endpoint\n  scopes:\n    - openid\n    - profile\n```\n\n**Example Public Client (SPA/Mobile):**\n```yaml\nweb-client:\n  client-authentication-methods:\n    - none  # Public client\n  authorization-grant-types:\n    - authorization_code\n    - refresh_token\n  redirect-uris:\n    - http://host.docker.internal:8080/en/select-context\n  scopes:\n    - openid\n    - profile\n```\n\n## Authentication Flow Details\n\n### 1. Authorization Request\n\nClient initiates authorization:\n```\nGET /oauth2/authorize?\n  response_type=code\u0026\n  client_id=my-client\u0026\n  redirect_uri=https://my-app.example.com/callback\u0026\n  scope=openid profile\u0026\n  state=xyz\u0026\n  aspspId=420e5cff-0e2a-4156-991a-f6eeef0478cf\n```\n\n### 2. Consent Initiation\n\nIf user not authenticated:\n- Server creates consent request with Mastercard\n- Receives SCA redirect URL\n- Redirects user to Mastercard's consent authorization page\n\n### 3. User Authorization\n\nUser authenticates and authorizes consent at ASPSP:\n- Views account information permissions\n- Authorizes or denies access\n- Redirected back with authorization code\n\n### 4. Callback Processing\n\nAuthorization server receives callback:\n```\nGET /ai/consents/callback?\n  authorization=AUTH_CODE\u0026\n  aspspId=420e5cff-0e2a-4156-991a-f6eeef0478cf\n```\n\n- Exchanges authorization for consent\n- Retrieves consent ID\n- Creates authenticated session\n- Redirects to OAuth2 authorization endpoint\n\n### 5. Token Exchange\n\nClient exchanges authorization code for tokens:\n```\nPOST /oauth2/token\nContent-Type: application/x-www-form-urlencoded\n\ngrant_type=authorization_code\u0026\ncode=AUTHORIZATION_CODE\u0026\nredirect_uri=https://my-app.example.com/callback\u0026\nclient_id=my-client\u0026\nclient_secret=secret\n```\n\nResponse:\n```json\n{\n  \"access_token\": \"eyJhbGc...\",\n  \"token_type\": \"Bearer\",\n  \"expires_in\": 3600,\n  \"refresh_token\": \"eyJhbGc...\",\n  \"id_token\": \"eyJhbGc...\",\n  \"scope\": \"openid profile\"\n}\n```\n\n### 6. Token Claims\n\n**Access Token Claims:**\n```json\n{\n  \"sub\": \"sara\",\n  \"aspspId\": \"420e5cff-0e2a-4156-991a-f6eeef0478cf\",\n  \"consentId\": \"e9d77b12-3c4a-4f2e-9c1a-8d9e7f6a5b4c\",\n  \"scope\": \"openid profile\",\n  \"exp\": 1700000000,\n  \"iat\": 1699996400\n}\n```\n\n**ID Token Claims:**\n```json\n{\n  \"sub\": \"sara\",\n  \"preferred_username\": \"sara\",\n  \"aud\": \"my-client\",\n  \"exp\": 1700000000,\n  \"iat\": 1699996400\n}\n```\n\n## API Client Generation\n\nThe server generates Mastercard OpenBanking Connect API clients during build:\n\n**Generated APIs:**\n- `AiConsentsApi` - Consent creation and management\n- `AiConsentsAuthorizationsApi` - Authorization exchange\n\n**Generation Configuration:**\n```xml\n\u003cinputSpec\u003ehttps://static.developer.mastercard.com/content/open-banking-connect/swagger/api-accounts-service.yaml\u003c/inputSpec\u003e\n\u003capiPackage\u003ecom.mastercard.mcob.ais.api\u003c/apiPackage\u003e\n\u003cmodelPackage\u003ecom.mastercard.mcob.ais.model\u003c/modelPackage\u003e\n```\n\n## Build and Run\n\n### Prerequisites\n\n- Java 17 or higher\n- Maven 3.6+\n- Access to Mastercard OpenBanking Connect Sandbox\n\n### Build the Service\n\n```bash\nmvn clean install\n```\n\n### Run Locally\n\n```bash\nmvn spring-boot:run -Dspring-boot.run.profiles=sandbox\n```\n\n### Run with Docker\n\nBuild Docker image:\n```bash\nmvn compile jib:dockerBuild\n```\n\nRun container:\n```bash\ndocker run -p 8081:8081 \\\n  -e SPRING_PROFILES_ACTIVE=sandbox \\\n  authorization-server:1.5.1\n```\n\n## Testing\n\n### Run Unit Tests\n\n```bash\nmvn test\n```\n\n### Test Authorization Flow\n\n1. **Start the server:**\n   ```bash\n   mvn spring-boot:run -Dspring-boot.run.profiles=sandbox\n   ```\n\n2. **Initiate authorization:**\n   ```bash\n   open \"http://localhost:8081/oauth2/authorize?response_type=code\u0026client_id=web-client\u0026redirect_uri=http://host.docker.internal:8080/en/select-context\u0026scope=openid%20profile\u0026state=test123\"\n   ```\n\n3. **Complete consent at Mastercard Sandbox**\n\n4. **Exchange code for token:**\n   ```bash\n   curl -X POST http://localhost:8081/oauth2/token \\\n     -H \"Content-Type: application/x-www-form-urlencoded\" \\\n     -d \"grant_type=authorization_code\" \\\n     -d \"code=AUTHORIZATION_CODE\" \\\n     -d \"redirect_uri=http://host.docker.internal:8080/en/select-context\" \\\n     -d \"client_id=web-client\"\n   ```\n\n### Verify Token\n\nDecode the JWT at [jwt.io](https://jwt.io) to verify claims.\n\n## Monitoring and Operations\n\n### Actuator Endpoints\n\nEnable all actuator endpoints in `application-sandbox.yml`:\n```yaml\nmanagement:\n  endpoints:\n    enabled-by-default: true\n    web:\n      exposure:\n        include: '*'\n```\n\n**Available Endpoints:**\n- `/actuator/health` - Health check\n- `/actuator/info` - Build information\n- `/actuator/httptrace` - HTTP request traces\n- `/actuator/metrics` - Application metrics\n- `/actuator/loggers` - Logger configuration\n\n### Logging\n\n**Default Levels:**\n```yaml\nlogging:\n  level:\n    root: INFO\n    com.backbase.authorization: DEBUG\n    org.springframework.security: DEBUG\n```\n\n## Integration with Backbase\n\n### Token Propagation\n\nThe authorization server issues tokens with custom claims that are consumed by downstream services:\n\n1. **Access Token** includes `aspspId` and `consentId`\n2. **Integration Service** extracts claims from token\n3. **Claims used in Mastercard API calls** for account information\n\n### Example Integration Flow\n\n```\nUser Browser → Authorization Server → Mastercard SCA\n                      ↓\n              [Consent Created]\n                      ↓\n              Access Token (with aspspId, consentId)\n                      ↓\nBackbase Platform → Integration Service → Mastercard AIS API\n```\n\n## Security Considerations\n\n### Production Deployment\n\n**Required Changes:**\n1. **Use encrypted secrets:** Replace `{noop}` with `{bcrypt}`\n2. **Disable permissive redirect:** Set `code-flow.permissive-redirect: false`\n3. **Configure HTTPS:** Use TLS for all endpoints\n4. **Restrict public paths:** Minimize exposed endpoints\n5. **Enable CORS carefully:** Configure specific origins\n6. **Use persistent storage:** Replace in-memory repositories\n7. **Rotate JWK keys:** Implement key rotation strategy\n8. **Set secure token lifetimes:** Balance UX and security\n9. **Enable rate limiting:** Protect against abuse\n10. **Monitor and audit:** Track authorization requests\n\n### Redirect URI Security\n\nThe `AllowedRedirectUriValidator` prevents open redirect attacks:\n- Validates redirect URIs against registered patterns\n- Supports wildcard matching for development\n- Enforces strict validation in production\n\n### Password Encoding\n\nClient secrets support Spring Security password encoders:\n- `{noop}` - Plain text (development only)\n- `{bcrypt}` - BCrypt (recommended for production)\n- `{pbkdf2}` - PBKDF2\n- `{scrypt}` - SCrypt\n- `{sha256}` - SHA-256\n\n## Development Notes\n\n### Adding a New Client\n\n1. Add client configuration to `application.yml`:\n   ```yaml\n   security:\n     authorization:\n       client-registration:\n         my-new-client:\n           secret: \"{bcrypt}$2a$10$...\"\n           # ... other settings\n   ```\n\n2. Configure token claim mappings if needed\n\n3. Register redirect URIs\n\n### Adding Custom Claims\n\n1. Update authentication to include attributes:\n   ```java\n   Map\u003cString, Object\u003e attributes = new HashMap\u003c\u003e();\n   attributes.put(\"customClaim\", value);\n   new AttributesAuthenticationToken(principal, attributes);\n   ```\n\n2. Configure claim mapper in client settings:\n   ```yaml\n   token-configuration:\n     \"[settings.token.claim-mappers]\":\n       - attributeName: customClaim\n         toAccessToken: true\n         toIdToken: false\n         toUserInfo: true\n   ```\n\n### Customizing Consent Flow\n\nModify `AiConsentRedirectEntryPoint` to:\n- Change consent permissions\n- Adjust validity periods\n- Customize callback behavior\n- Add additional ASPSP logic\n\n## Troubleshooting\n\n### Common Issues\n\n**Issue: \"Invalid redirect URI\"**\n- Verify redirect URI matches registered URI exactly\n- Check `code-flow.permissive-redirect` setting\n- Review `AllowedRedirectUriValidator` configuration\n\n**Issue: \"Failed when fetching authorizations\"**\n- Verify Mastercard API credentials\n- Check network connectivity\n- Review proxy configuration if behind corporate firewall\n- Verify ASPSP ID is correct\n\n**Issue: \"Consent expired\"**\n- Check `consent-validity` duration\n- Verify system time synchronization\n- Review token expiration settings\n\n**Issue: \"User not found\"**\n- Verify user mapping in ASPSP configuration\n- Check consent ID returned from Mastercard\n- Review `AiConsentUsersRepository` logic\n\n### Debug Logging\n\nEnable trace logging for troubleshooting:\n```yaml\nlogging:\n  level:\n    com.backbase.authorization: TRACE\n    org.springframework.security: TRACE\n    org.springframework.security.oauth2: TRACE\n```\n\n## Known Limitations\n\n- **In-memory storage** - Not suitable for production clusters\n- **Single JWK key** - No key rotation implemented\n- **Basic user mapping** - Simple user-to-consent association\n- **No consent revocation** - Manual cleanup required\n- **Sandbox only** - Configured for Mastercard sandbox environment\n\n## Future Enhancements\n\n- Persistent authorization storage (database)\n- Dynamic client registration (RFC 7591)\n- Consent revocation API\n- JWK key rotation\n- Enhanced user management\n- Support for PSD2 SCA exemptions\n- Webhook support for consent status updates\n- Multi-factor authentication\n- Session management UI\n\n## Related Components\n\nThis server works in conjunction with:\n- **Mastercard Integration Service** - Consumes tokens for API calls\n- **Backbase Identity** - Can be integrated as identity provider\n- **Keycloak** - Can broker authentication through this server\n\n## References\n\n- [Spring Authorization Server Documentation](https://docs.spring.io/spring-authorization-server/docs/current/reference/html/)\n- [Mastercard OpenBanking Connect Documentation](https://developer.mastercard.com/open-banking-connect/documentation/)\n- [OAuth 2.0 Authorization Framework](https://datatracker.ietf.org/doc/html/rfc6749)\n- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)\n- [PSD2 Regulatory Technical Standards](https://www.eba.europa.eu/regulation-and-policy/payment-services-and-electronic-money/regulatory-technical-standards-on-strong-customer-authentication-and-secure-communication-under-psd2)\n\n## License\n\nThis is a proof-of-concept implementation for integration purposes. Do not use it in production.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbackbase%2Fauthorization-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbackbase%2Fauthorization-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbackbase%2Fauthorization-server/lists"}