Add examples for CAMARA Security and Interoperability Profile
Elisabeth-Ericsson opened this issue · 11 comments
Problem description
The document CAMARA Security and Interoperability Profile aims at provide a comprehensive guide for developers and operators, ensuring consistent implementation and adherence to standardized security measures across the CAMARA ecosystem. As of today it describes some restrictions on options available in OIDC and CIBA. However it lacks examples on token request/responses for the different flows OIDC Authorization Code Flow, CIBA flow and Client Credential Flow. Meaningful examples are key for a good developer experience.
Expected action
Enhance the document CAMARA Security and Interoperability Profile by adding at least one example for token request/response per flow type.
Additional context
The document to be enhanced is not yet part of the main documentation branch, but included in pull request #121; (https://github.com/camaraproject/IdentityAndConsentManagement/pull/121/files?short_path=eecd267#diff-eecd267efc7f8abc6037bc5c8260494fb16093ab6c884c259cebf790af48087b)
Would prefer if this is done in a separate (supporting) document, and this way we don't have to worry about not bloating up the profile doc.
Would a OpenAPI Specification (YAML file) describing the endpoints be a better fit?
Would a OpenAPI Specification (YAML file) describing the endpoints be a better fit?
Although OIDC and OAuth2 are older then openapi, I assume that somebody already wrote an OIDC/OAuth2 yaml file.
I did not look for it. We could certainly give that approach a try.
Here is an example of a yaml file with an example it the API spec.
https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/api-with-examples.yaml#L16
I guess it depends on the developer's familiarity with openyaml whether this is a good approach.
Or whether the e.g. OIDC method of writing examples is helping developers more.
(copied from https://openid.net/specs/openid-connect-core-1_0.html#RequestParameter)
https://server.example.com/authorize?
response_type=code%20id_token
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&scope=openid
&state=af0ifjsldkj
&nonce=n-0S6_WzA2Mj
&request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImsyYmRjIn0.ew0KICJpc3MiOiA
iczZCaGRSa3F0MyIsDQogImF1ZCI6ICJodHRwczovL3NlcnZlci5leGFtcGxlLmN
vbSIsDQogInJlc3BvbnNlX3R5cGUiOiAiY29kZSBpZF90b2tlbiIsDQogImNsaWV
udF9pZCI6ICJzNkJoZFJrcXQzIiwNCiAicmVkaXJlY3RfdXJpIjogImh0dHBzOi8
vY2xpZW50LmV4YW1wbGUub3JnL2NiIiwNCiAic2NvcGUiOiAib3BlbmlkIiwNCiA
ic3RhdGUiOiAiYWYwaWZqc2xka2oiLA0KICJub25jZSI6ICJuLTBTNl9XekEyTWo
iLA0KICJtYXhfYWdlIjogODY0MDAsDQogImNsYWltcyI6IA0KICB7DQogICAidXN
lcmluZm8iOiANCiAgICB7DQogICAgICJnaXZlbl9uYW1lIjogeyJlc3NlbnRpYWw
iOiB0cnVlfSwNCiAgICAgIm5pY2tuYW1lIjogbnVsbCwNCiAgICAgImVtYWlsIjo
geyJlc3NlbnRpYWwiOiB0cnVlfSwNCiAgICAgImVtYWlsX3ZlcmlmaWVkIjogeyJ
lc3NlbnRpYWwiOiB0cnVlfSwNCiAgICAgInBpY3R1cmUiOiBudWxsDQogICAgfSw
NCiAgICJpZF90b2tlbiI6IA0KICAgIHsNCiAgICAgImdlbmRlciI6IG51bGwsDQo
gICAgICJiaXJ0aGRhdGUiOiB7ImVzc2VudGlhbCI6IHRydWV9LA0KICAgICAiYWN
yIjogeyJ2YWx1ZXMiOiBbInVybjptYWNlOmluY29tbW9uOmlhcDpzaWx2ZXIiXX0
NCiAgICB9DQogIH0NCn0.nwwnNsk1-ZkbmnvsF6zTHm8CHERFMGQPhos-EJcaH4H
h-sMgk8ePrGhw_trPYs8KQxsn6R9Emo_wHwajyFKzuMXZFSZ3p6Mb8dkxtVyjoy2
GIzvuJT_u7PkY2t8QU9hjBcHs68PkgjDVTrG1uRTx0GxFbuPbj96tVuj11pTnmFC
UR6IEOXKYr7iGOCRB3btfJhM0_AKQUfqKnRlrRscc8Kol-cSLWoYE9l5QqholImz
jT_cMnNIznW9E7CDyWXTsO70xnB4SkG6pXfLSjLLlxmPGiyon_-Te111V8uE83Il
zCYIb_NMXvtTIVc1jpspnTSD7xMbpL-2QgwUsAlMGzw
@Elisabeth-Ericsson Would it be OK for you changing the title of this issue and rephrase the "into"?
Understand there is an intention by GSMA to certify these endpoints, and I think a YAML representation, with request/response examples in the YAML would be a better fit.
@Elisabeth-Ericsson Would it be OK for you changing the title of this issue and rephrase the "into"?
Sure, will do, I will change it to "for". Then we can decide whether we provide the examples in a separate document.
However, examples are usually picking a use case for illustration and are not a fully generic YAML spec.
So I vote for proper examples having request/response pairs for client credential, authcode flow and CIBA flow matching the descriptions given in the CAMARA Security and Interoperability Profile. To be able to reference, I also recommend to introduce chapter numbering into the OIDC Security profile,
I added an examples file and put one example in
https://github.com/AxelNennker/IdentityAndConsentManagement/blob/icm_examples/documentation/CAMARA-ICM-examples.md
Thank you so much for the examples, they are very helpfull.
I opened a new pull request on the example file to extend a bit: AxelNennker#4
In AxelNennker#4 (comment)
@mhfoo says:
I believe the RFC9101 request object examples should have the following claims, as per RFC7519:
exp: Expiration Time Claim
nbf: Not Before Claim
iat: Issued At Claim
jti: JWT ID Claim
Copying @mhfoo s comment here because I would like having "examples"-related comments in this issue.
Responding to that comment: Yes, that is probably true. I copied the example from https://www.rfc-editor.org/rfc/rfc9101.html#section-4 and changed what needed to be changed to demonstrate purpose.
I'll create a PR for the examples which makes it easier to review and make suggestions.
Created a PR to make it easier to review
#148
@AxelNennker #148 fixes this issue, doesn't it? I think we can close it, right?