From a3add7822299eb2a4bc5b64ba0afe03c5eaf1ac2 Mon Sep 17 00:00:00 2001 From: Gerard Snaauw Date: Fri, 20 Sep 2024 09:36:49 +0200 Subject: [PATCH] Mark user-flow and openid4vci-flow experimental --- auth/api/iam/generated.go | 8 +- docs/_static/auth/v2.yaml | 151 +++++++++++++++++++------------------- 2 files changed, 79 insertions(+), 80 deletions(-) diff --git a/auth/api/iam/generated.go b/auth/api/iam/generated.go index 47614d684..1389246e7 100644 --- a/auth/api/iam/generated.go +++ b/auth/api/iam/generated.go @@ -554,13 +554,13 @@ type ServerInterface interface { // Create a DPoP proof as specified by RFC9449 for a given access token. It is to be used as HTTP header when accessing resources. // (POST /internal/auth/v2/{kid}/dpop) CreateDPoPProof(ctx echo.Context, kid string) error - // Start the Oid4VCI authorization flow. + // EXPERIMENTAL Start the Oid4VCI authorization flow. // (POST /internal/auth/v2/{subjectID}/request-credential) RequestOpenid4VCICredentialIssuance(ctx echo.Context, subjectID string) error // Start the authorization flow to get an access token from a remote authorization server. // (POST /internal/auth/v2/{subjectID}/request-service-access-token) RequestServiceAccessToken(ctx echo.Context, subjectID string) error - // Start the authorization code flow to get an access token from a remote authorization server when user context is required. + // EXPERIMENTAL Start the authorization code flow to get an access token from a remote authorization server when user context is required. // (POST /internal/auth/v2/{subjectID}/request-user-access-token) RequestUserAccessToken(ctx echo.Context, subjectID string) error // Used by resource owners (the browser) to initiate the authorization code flow. @@ -1759,13 +1759,13 @@ type StrictServerInterface interface { // Create a DPoP proof as specified by RFC9449 for a given access token. It is to be used as HTTP header when accessing resources. // (POST /internal/auth/v2/{kid}/dpop) CreateDPoPProof(ctx context.Context, request CreateDPoPProofRequestObject) (CreateDPoPProofResponseObject, error) - // Start the Oid4VCI authorization flow. + // EXPERIMENTAL Start the Oid4VCI authorization flow. // (POST /internal/auth/v2/{subjectID}/request-credential) RequestOpenid4VCICredentialIssuance(ctx context.Context, request RequestOpenid4VCICredentialIssuanceRequestObject) (RequestOpenid4VCICredentialIssuanceResponseObject, error) // Start the authorization flow to get an access token from a remote authorization server. // (POST /internal/auth/v2/{subjectID}/request-service-access-token) RequestServiceAccessToken(ctx context.Context, request RequestServiceAccessTokenRequestObject) (RequestServiceAccessTokenResponseObject, error) - // Start the authorization code flow to get an access token from a remote authorization server when user context is required. + // EXPERIMENTAL Start the authorization code flow to get an access token from a remote authorization server when user context is required. // (POST /internal/auth/v2/{subjectID}/request-user-access-token) RequestUserAccessToken(ctx context.Context, request RequestUserAccessTokenRequestObject) (RequestUserAccessTokenResponseObject, error) // Used by resource owners (the browser) to initiate the authorization code flow. diff --git a/docs/_static/auth/v2.yaml b/docs/_static/auth/v2.yaml index 7fc0c44b4..12bef8c2d 100644 --- a/docs/_static/auth/v2.yaml +++ b/docs/_static/auth/v2.yaml @@ -1,12 +1,9 @@ openapi: 3.0.0 info: - title: Auth v2 API (experimental) + title: Auth v2 API version: 2.0.0 servers: - url: http://localhost:8081 - description: For internal-facing endpoints. - - url: http://localhost:8080 - description: For public-facing endpoints. paths: /internal/auth/v2/{subjectID}/request-service-access-token: post: @@ -48,8 +45,9 @@ paths: /internal/auth/v2/{subjectID}/request-user-access-token: post: operationId: requestUserAccessToken - summary: Start the authorization code flow to get an access token from a remote authorization server when user context is required. + summary: EXPERIMENTAL Start the authorization code flow to get an access token from a remote authorization server when user context is required. description: | + This API is still EXPERIMENTAL. Initiates an OAuth2 flow to request an access token from a remote authorization server. This call will initiate an OpenID4VP flow. The user must be authorized by the calling system and provided in the preauthorized_user field. The user's ID must be stable across sessions, as it's used to select the right ID Wallet. @@ -85,6 +83,78 @@ paths: $ref: '#/components/schemas/RedirectResponseWithID' default: $ref: '../common/error_response.yaml' + /internal/auth/v2/{subjectID}/request-credential: + post: + operationId: requestOpenid4VCICredentialIssuance + summary: EXPERIMENTAL Start the Oid4VCI authorization flow. + description: | + This API is still EXPERIMENTAL. + Initiates an Oid4VCI flow to request an VC from a Credential Issuer. + + error returns: + * 400 - one of the parameters has the wrong format or an OAuth error occurred + * 424 - the issuer does not fulfill the right requirements to issue the requested VC(s) + * 412 - the organization wallet does not contain the correct credentials + tags: + - auth + parameters: + - name: subjectID + in: path + required: true + description: Subject ID of the wallet owner at this node. + schema: + type: string + example: 90BC1AE9-752B-432F-ADC3-DD9F9C61843C + requestBody: + required: true + content: + application/json: + schema: + required: + - issuer + - authorization_details + - redirect_uri + - wallet_did + properties: + wallet_did: + type: string + description: The DID to which the Verifiable Credential must be issued. Must be owned by the given subject. + example: did:web:example.com + issuer: + type: string + description: | + The OAuth Authorization Server's identifier, that issues the Verifiable Credentials, as specified in RFC 8414 (section 2), + used to locate the OAuth2 Authorization Server metadata. + example: did:web:issuer.example.com + authorization_details: + type: array + items: + type: object + description: | + The request parameter authorization_details defined in Section 2 of [RFC9396] MUST be used to convey the details about the Credentials the Wallet wants to obtain. + See the RFC9396/OpenID4VCI for the format of an authorization_details object, and consult the Credential Issuer for requestable credentials. + example: | + [ + { + "type": "openid_credential", + "credential_configuration_id": "UniversityDegreeCredential" + } + ] + redirect_uri: + type: string + description: | + The URL to which the user-agent will be redirected after the authorization request. + example: https://my-xis.example.com/callback + responses: + '200': + description: | + Successful request. Responds with a redirect_uri for the user and a session_id for correlation. + content: + application/json: + schema: + $ref: '#/components/schemas/RedirectResponse' + default: + $ref: '../common/error_response.yaml' /internal/auth/v2/accesstoken/{sessionID}: get: operationId: retrieveAccessToken @@ -233,77 +303,6 @@ paths: $ref: "#/components/schemas/DPoPValidateResponse" default: $ref: '../common/error_response.yaml' - /internal/auth/v2/{subjectID}/request-credential: - post: - operationId: requestOpenid4VCICredentialIssuance - summary: Start the Oid4VCI authorization flow. - description: | - Initiates an Oid4VCI flow to request an VC from a Credential Issuer. - - error returns: - * 400 - one of the parameters has the wrong format or an OAuth error occurred - * 424 - the issuer does not fulfill the right requirements to issue the requested VC(s) - * 412 - the organization wallet does not contain the correct credentials - tags: - - auth - parameters: - - name: subjectID - in: path - required: true - description: Subject ID of the wallet owner at this node. - schema: - type: string - example: 90BC1AE9-752B-432F-ADC3-DD9F9C61843C - requestBody: - required: true - content: - application/json: - schema: - required: - - issuer - - authorization_details - - redirect_uri - - wallet_did - properties: - wallet_did: - type: string - description: The DID to which the Verifiable Credential must be issued. Must be owned by the given subject. - example: did:web:example.com - issuer: - type: string - description: | - The OAuth Authorization Server's identifier, that issues the Verifiable Credentials, as specified in RFC 8414 (section 2), - used to locate the OAuth2 Authorization Server metadata. - example: did:web:issuer.example.com - authorization_details: - type: array - items: - type: object - description: | - The request parameter authorization_details defined in Section 2 of [RFC9396] MUST be used to convey the details about the Credentials the Wallet wants to obtain. - See the RFC9396/OpenID4VCI for the format of an authorization_details object, and consult the Credential Issuer for requestable credentials. - example: | - [ - { - "type": "openid_credential", - "credential_configuration_id": "UniversityDegreeCredential" - } - ] - redirect_uri: - type: string - description: | - The URL to which the user-agent will be redirected after the authorization request. - example: https://my-xis.example.com/callback - responses: - '200': - description: | - Successful request. Responds with a redirect_uri for the user and a session_id for correlation. - content: - application/json: - schema: - $ref: '#/components/schemas/RedirectResponse' - default: - $ref: '../common/error_response.yaml' components: schemas: cnf: