OPAL ‐ OPA ‐ Federation Design
- SSA : Software Statement Assertion -- a JWT issued by the Bank and bundled in the mobile application binary. This JWT is presented when the device performs client registration and provides metadata about the software that enables automated provisioning.
- Access Token : A reference or value token (JWT) returned to the client, whose JSON payload may include standard and extension claims. For access tokens which are used to calling a Bank API, DPoP access tokens mitigate the risk of token leakage.
- id_token: Identity Assertion obtained after the code flow.
- Client Update Token: This is a one-time-use reference token returned to the client after DCR, enabling the client to update its own data, e.g. perform key rotation.
- Transaction Token: A token that aligns with this proposed OAuth Draft that provides a fine-grain token to share information available across microservices.
In OAuth, the scope claim values of the access token are frequently used to convey the extent of access granted to the client. Which scopes a client can obtain during DCR is determined by the presented SSA. The required scopes for an API are defined in the OpenAPI metadata using the security and oauth2 schema. Note in the example below how the endpoint URL and HTTP method are used for course grain access control.
/api/v1/account:
get:
security:
- oauth2:
- https://bank.tld/account.read
- https://bank.tld/account.admin
Policies are defined using the Rego language, which are evaluated by a local OPA authorization service. Because OPA requires all data and policies in memory, the OPAL server is used to stream realtime updates to OPAL clients in a fanout pub-sub topology, which update the local OPA instances via the OPA bundles API.
Dynamic Client Registration ("DCR") is key to security. Each device has its own unique client registration record--it's own client_id, it's own registered public key. By registering a public key, the client can authenticate using an asymmetric secret. It's also possible to user proof of possession tokens, mitigating the risk of a leaked token. Also during DCR, we can verify the integrity of the software--that the Mobile Bank App calling our API has not been modified--by comparing the checksum of the software installed on the device with the checksum available on the Play Store / App Store.
title Mobile Bank Security - Dynamic Client Registration
actor Person
participant Device
participant App
participant App Server
participant Play Integrity API
participant Google Play server
participant Auth Server
database Identity Store
Person->Device: 1. Open App
Device->App:
App->Play Integrity API: 2. requestIntegrityToken(nonce)
Play Integrity API->App: 3. token
App->App Server: 4. token
App Server->Google Play server: 5. decrypt and verify token
Google Play server->App Server: 6. token payload
App Server->App: 7. integrity verdict
App->Auth Server: 8. DCR Request:\nSSA, Attestation (integrity verdict as claim)\nPublic key
Auth Server->Auth Server: 9. Validate SSA
Auth Server<->Auth Server: 10. Validate attested integrity verdict \n (using interception script)
Auth Server<->Identity Store: 11. Create client record
Auth Server->App: 12. client_id\nclient update token
App->App: 13. Ready for User\nIdentity Enrollment
After the Mobile Bank App instance has performed DCR on the person's device, we need to identify the Person and enroll credentials for subsequent authentication. To do this, Mobile Bank App will make multiple calls to the Authorization Challenge endpoint until a code is returned, per the OAuth 2.0 for First-Party Native Applications draft. Authentication, registration and stepped-up flows are specified by the client using the acr parameter of the Authorization Challenge request. Each acr is mapped to a Gluu Flex interception script. Once the Mobile Bank App obtains a code, it will present it at the /token endpoint along with JWT private key client authentication to obtain an access token.
title Mobile Bank Security - Resource Owner Interaction
actor Person
participant Device
participant App
participant Auth Server
database Identity Store
participant API GW
participant PDP
participant Bank API
Person->Device: 1. Open App
loop Register | Authenticate | Step-up
App->Device: 2. Login screen
Person->App: 3. Do something
App<->Auth Server: /authz-challenge
end
Auth Server->App: code
App<->Auth Server: /token
App->API GW: call endpoint
API GW->API GW: validate\nclient creds
API GW->API GW: validate\naccess token
API GW<->PDP: Authorize scopes
alt success
API GW<->Bank API: get content
API GW->App: resource
end
alt fail
API GW->App: Error Code
end
The API Gateway is the policy enforcement point. It relies on a local OPA server, running as a sidecar to make the policy decision.
As client tokens are short lived, the Mobile Bank App can just delete the local copy of the token.