Add examples for CAMARA Security and Interoperability Profile

[Elisabeth-Ericsson]

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)

[shilpa-padgaonkar]

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.

[mhfoo]

Would a OpenAPI Specification (YAML file) describing the endpoints be a better fit?

[AxelNennker]

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

[AxelNennker]

@Elisabeth-Ericsson Would it be OK for you changing the title of this issue and rephrase the "into"?

[mhfoo]

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]

@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,

[AxelNennker]

I added an examples file and put one example in https://github.com/AxelNennker/IdentityAndConsentManagement/blob/icm_examples/documentation/CAMARA-ICM-examples.md

[Elisabeth-Ericsson]

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: https://github.com/AxelNennker/IdentityAndConsentManagement/pull/4

[AxelNennker]

In https://github.com/AxelNennker/IdentityAndConsentManagement/pull/4#issuecomment-2095247501 @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.

[AxelNennker]

Created a PR to make it easier to review https://github.com/camaraproject/IdentityAndConsentManagement/pull/148

[jpengar]

@AxelNennker #148 fixes this issue, doesn't it? I think we can close it, right?