Skip to content

Commit 185674a

Browse files
simonredfernsimonredfern
committed
Docfix: Auth Docs in Resource Docs which will be imported into Glossary
etc.
1 parent 10d7e87 commit 185674a

4 files changed

Lines changed: 147 additions & 421 deletions

File tree

‎obp-api/src/main/scala/code/api/ResourceDocs1_4_0/OpenAPI31JSONFactory.scala‎

Lines changed: 110 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,108 @@ import code.util.Helper.MdcLoggable
5252
*/
5353
object OpenAPI31JSONFactory extends MdcLoggable {
5454

55+
// =====================================================================================
56+
// Authentication descriptions — SOURCE OF TRUTH
57+
// These methods are the canonical documentation for OBP authentication methods.
58+
// The Glossary and other docs import from here. (DRY)
59+
// If you need to change authentication documentation, change it here.
60+
// =====================================================================================
61+
62+
def directLoginDescription(hostname: String): String =
63+
s"""Direct Login is a simple authentication process for trusted environments and testing.
64+
|
65+
|### Step 1: Get your Consumer Key
66+
|
67+
|Register your application at ${hostname}/consumer-registration to obtain a consumer_key.
68+
|
69+
|### Step 2: Obtain a token
70+
|
71+
|Send a POST request with your credentials in the DirectLogin header:
72+
|
73+
| POST ${hostname}/obp/v6.0.0/my/logins/direct
74+
| Content-Type: application/json
75+
| DirectLogin: username=YOUR_USERNAME, password=YOUR_PASSWORD, consumer_key=YOUR_CONSUMER_KEY
76+
|
77+
|The body should be left empty.
78+
|
79+
|A successful response returns a JSON object containing a token:
80+
|
81+
| {"token": "your-token-string"}
82+
|
83+
|### Step 3: Use the token in subsequent API calls
84+
|
85+
|Include the token in the DirectLogin header on all subsequent requests:
86+
|
87+
| GET ${hostname}/obp/v6.0.0/my/banks
88+
| DirectLogin: token=your-token-string
89+
|
90+
|### Parameters
91+
|
92+
|Parameter names and values are case sensitive. Each parameter must appear only once per request.
93+
|
94+
|- **username** - The name of the user to authenticate.
95+
|- **password** - The password of the user.
96+
|- **consumer_key** - The application identifier obtained during registration.
97+
|
98+
|### Notes
99+
|
100+
|- The header name is **DirectLogin** (case insensitive for HTTP/1.1, must be lower case for HTTP/2).
101+
|- Direct Login is intended for hackathons, testing, and trusted environments.
102+
|- For production use with third-party applications, use OAuth2 / OIDC instead.""".stripMargin
103+
104+
def oAuth2Description(hostname: String): String =
105+
s"""OAuth2 / OpenID Connect (OIDC) is the recommended authentication method for production use.
106+
|
107+
|OBP supports the OAuth2 Authorization Code flow for user-facing applications and the
108+
|Client Credentials flow for application-only (machine-to-machine) access.
109+
|
110+
|### Authorization Code Flow (3-legged)
111+
|
112+
|Use this flow when your application needs to act on behalf of a user.
113+
|
114+
|1. Register your application at ${hostname}/consumer-registration to obtain a client_id and client_secret.
115+
|2. Redirect the user to the authorization URL with your client_id and redirect_uri.
116+
|3. After the user authenticates and consents, they are redirected back with an authorization code.
117+
|4. Exchange the authorization code for an access token at the token endpoint.
118+
|5. Use the access token as a Bearer token in the Authorization header:
119+
|
120+
| GET ${hostname}/obp/v6.0.0/my/banks
121+
| Authorization: Bearer your-access-token
122+
|
123+
|### Client Credentials Flow (2-legged / Application Only)
124+
|
125+
|Use this flow for endpoints with authMode ApplicationOnly or UserOrApplication.
126+
|The application authenticates itself using its client_id and client_secret without a user login.
127+
|
128+
| POST <OIDC_provider_token_endpoint>
129+
| Content-Type: application/x-www-form-urlencoded
130+
|
131+
| grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET
132+
|
133+
|The response contains a Bearer token to use in subsequent API calls.
134+
|
135+
|### Notes
136+
|
137+
|- The authorization and token endpoint URLs depend on the OIDC provider configured for this OBP instance.
138+
|- Token expiry and refresh behaviour depend on the OIDC provider configuration.
139+
|- OAuth2 / OIDC is the recommended method for production deployments.""".stripMargin
140+
141+
def gatewayLoginDescription(hostname: String): String =
142+
s"""Gateway Login allows a gateway (e.g. API Gateway) to authenticate on behalf of a user.
143+
|
144+
|The gateway sends a JWT in the Authorization header. The JWT is signed with a shared secret
145+
|between the gateway and OBP. This method does not require a separate token-obtaining step —
146+
|the JWT is sent directly with each API request.
147+
|
148+
| GET ${hostname}/obp/v6.0.0/my/banks
149+
| Authorization: GatewayLogin token="your-jwt-token"
150+
|
151+
|### Notes
152+
|
153+
|- Gateway Login is intended for trusted infrastructure, not end-user applications.
154+
|- The JWT must be signed with the pre-shared secret configured on the OBP instance.
155+
|- Contact your OBP administrator for gateway integration details.""".stripMargin
156+
55157
// OpenAPI 3.1 Root Object
56158
case class OpenAPI31Json(
57159
openapi: String = "3.1.0",
@@ -396,27 +498,27 @@ object OpenAPI31JSONFactory extends MdcLoggable {
396498
// Extract schemas from all request/response bodies
397499
val schemas = extractSchemas(resourceDocs)
398500

399-
// Create security schemes
501+
// Create security schemes — descriptions come from the methods defined at the top of this object
400502
val securitySchemes = Map(
401503
"DirectLogin" -> SecuritySchemeJson(
402504
`type` = "apiKey",
403-
description = Some("Direct Login token authentication"),
404-
name = Some("Authorization"),
505+
description = Some(directLoginDescription(hostname)),
506+
name = Some("DirectLogin"),
405507
in = Some("header")
406508
),
407509
"GatewayLogin" -> SecuritySchemeJson(
408-
`type` = "apiKey",
409-
description = Some("Gateway Login token authentication"),
510+
`type` = "apiKey",
511+
description = Some(gatewayLoginDescription(hostname)),
410512
name = Some("Authorization"),
411513
in = Some("header")
412514
),
413515
"OAuth2" -> SecuritySchemeJson(
414516
`type` = "oauth2",
415-
description = Some("OAuth2 authentication"),
517+
description = Some(oAuth2Description(hostname)),
416518
flows = Some(OAuthFlowsJson(
417519
authorizationCode = Some(OAuthFlowJson(
418-
authorizationUrl = Some("/oauth/authorize"),
419-
tokenUrl = Some("/oauth/token"),
520+
authorizationUrl = Some(s"${hostname}/oauth/authorize"),
521+
tokenUrl = Some(s"${hostname}/oauth/token"),
420522
scopes = Map.empty
421523
))
422524
))

‎obp-api/src/main/scala/code/api/ResourceDocs1_4_0/SwaggerJSONFactory.scala‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -91,16 +91,18 @@ object SwaggerJSONFactory extends MdcLoggable {
9191
directLogin: DirectLoginJson ,
9292
gatewayLogin: GatewayLoginJson
9393
)
94+
// NOTE: For full authentication documentation, see the securitySchemes in OpenAPI31JSONFactory.scala
95+
// which is the source of truth. These Swagger 2.0 definitions are kept for backward compatibility.
9496
case class DirectLoginJson(
9597
`type`: String = "apiKey",
96-
description: String = "https://github.com/OpenBankProject/OBP-API/wiki/Direct-Login", // TODO replace with Glossary link
98+
description: String = "Direct Login authentication. POST to /obp/v6.0.0/my/logins/direct with header 'DirectLogin: username=YOUR_USERNAME, password=YOUR_PASSWORD, consumer_key=YOUR_CONSUMER_KEY' to obtain a token. Then use header 'DirectLogin: token=YOUR_TOKEN' on subsequent requests. See the OpenAPI 3.1 spec for full details.",
9799
in: String = "header",
98-
name: String = "Authorization"
100+
name: String = "DirectLogin"
99101
)
100-
102+
101103
case class GatewayLoginJson(
102104
`type`: String = "apiKey",
103-
description: String = "https://github.com/OpenBankProject/OBP-API/wiki/Gateway-Login", // TODO replace with Glossary link
105+
description: String = "Gateway Login authentication. The gateway sends a JWT in the Authorization header signed with a pre-shared secret. See the OpenAPI 3.1 spec for full details.",
104106
in: String = "header",
105107
name: String = "Authorization"
106108
)

0 commit comments

Comments
 (0)