v2.yaml

openapi: 3.0.0
info:
  title: Auth v2 API
  version: 2.0.0
servers:
  - url: http://localhost:8081
paths:
  /internal/auth/v2/{subjectID}/request-service-access-token:
    post:
      operationId: requestServiceAccessToken
      summary: Start the authorization flow to get an access token from a remote authorization server.
      description: |
        Initiates an OAuth2 flow to request an access token from a remote authorization server.
        It'll initiate a s2s (RFC021) flow.

        error returns:
        * 400 - one of the parameters has the wrong format, an OAuth error occurred, or the http client calling the authorizer returned an error due to incorrect input
        * 412 - the organization wallet does not contain the correct credentials or doesn't support the right DID methods
        * 502 - the authorizer returned an error
        * 503 - the authorizer could not be reached
      tags:
        - auth
      parameters:
        - name: subjectID
          in: path
          required: true
          description: Subject of the requester, a wallet owner at this node.
          schema:
            type: string
            example: 90BC1AE9-752B-432F-ADC3-DD9F9C61843C
        - name: Cache-Control
          in: header
          required: false
          description: |
            Access tokens are cached by the Nuts node, specify Cache-Control: no-cache to bypass the cache.
            This forces the Nuts node to request a new access token from the authorizer.
            
            A valid use case for this is when the Resource Server rejects the access token with 401 Unauthorized.
            It could be that the Authorization Server lost the access token due to a server restart,
            in combination with (non-recommended) usage of in-memory session storage.
            The local Nuts node then still considers the token valid, while the Authorization Server does not.
            
            Note that this should not be used under normal circumstances, as it will increase round trip time and load on both the requester and authorizer.
          schema:
            type: string
            example: no-cache
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceAccessTokenRequest'
      responses:
        '200':
          description: Successful request. Responds with an access token as described in rfc6749 section 5.1.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        default:
          $ref: '../common/error_response.yaml'
  /internal/auth/v2/{subjectID}/request-user-access-token:
    post:
      operationId: requestUserAccessToken
      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.
        
        error returns:
        * 400 - one of the parameters has the wrong format or an OAuth error occurred
        * 412 - the organization wallet does not contain the correct credentials
        * 503 - the authorizer could not be reached or returned an error
      tags:
        - auth
      parameters:
        - name: subjectID
          in: path
          required: true
          description: Subject of the requester, a wallet owner at this node.
          schema:
            type: string
            example: 90BC1AE9-752B-432F-ADC3-DD9F9C61843C
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserAccessTokenRequest'
      responses:
        '200':
          description: |
            Successful request. Responds with a redirect_uri for the user and a token for the calling application.
            The token can be used by the calling application to get the status of the session.
          content:
            application/json:
              schema:
                $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
      summary: Get the access token from the Nuts node that was requested through /request-user-access-token.
      description: |
        If the OAuth2 flow has completed, this call will return the access token. 
        After returning the access token, the token used to retrieve the access token is no longer valid.
        If the flow hasn't completed yet, the response will contain the 'pending' status value.
        Therefore this API can be used to poll for the status of the OAuth2 flow.
      tags:
        - auth
      parameters:
        - name: sessionID
          in: path
          required: true
          description: This ID is given to the calling application as response to the request-user-access-token call.
          schema:
            type: string
            example: eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp
      responses:
        '200':
          description: |
            Successful request. Responds with an access token as described in rfc6749 section 5.1 when available.
            If the OAuth2 flow hasn't completed yet, the response will only contain the 'pending' status value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        default:
          $ref: '../common/error_response.yaml'
  /internal/auth/v2/accesstoken/introspect:
    post:
      operationId: introspectAccessToken
      summary: |
        Introspection endpoint to retrieve information from an Access Token as described by RFC7662.
        It returns fields derived from the credentials that were used during authentication.
      tags:
        - auth
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/TokenIntrospectionRequest"
      responses:
        '200':
          description: |
            An Introspection response as described in RFC7662 section 2.2.
            The 'active' field indicates whether the token should be considered valid or not.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenIntrospectionResponse"
        '401':
          description: |
            This is returned when an OAuth2 Client is unauthorized to talk to the introspection endpoint.
            Note: introspection of an invalid or malformed token returns a 200 where with field 'active'=false
  /internal/auth/v2/accesstoken/introspect_extended:
    post:
      operationId: introspectAccessTokenExtended
      summary: |
        Introspection endpoint to retrieve information from an Access Token as described by RFC7662.
        It returns the same information as the non-extended API call, but with the Presentation Definitions,
        Presentation Submissions and Verifiable Presentations added.
      tags:
        - auth
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/TokenIntrospectionRequest"
      responses:
        '200':
          description: |
            An Introspection response as described in RFC7662 section 2.2.
            The 'active' field indicates whether the token should be considered valid or not.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExtendedTokenIntrospectionResponse"
        '401':
          description: |
            This is returned when an OAuth2 Client is unauthorized to talk to the introspection endpoint.
            Note: introspection of an invalid or malformed token returns a 200 where with field 'active'=false
  /internal/auth/v2/dpop/{kid}:
    post:
      operationId: createDPoPProof
      summary: Create a DPoP proof as specified by RFC9449 for a given access token. It is to be used as HTTP header when accessing resources.
      tags:
        - auth
      parameters:
        - name: kid
          in: path
          required: true
          description: The kid used to create the DPoP proof returned by the access token request.
          # we use the content hack so no unescaping happens in the generated code. This way we can handle web:did keys with port numbers.
          content:
            plain/text:
              schema:
                type: string
                example: did:web:example.com#1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DPoPRequest"
      responses:
        '200':
          description: A response containing the DPoP proof as specified by RFC9449
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DPoPResponse"
        '401':
          description: This is returned when an OAuth2 Client is unauthorized to talk to the DPoP endpoint.
  /internal/auth/v2/dpop/validate:
    post:
      operationId: validateDPoPProof
      summary: Handle some of the validation of a DPoP proof as specified by RFC9449.
      description: |
        Handle some of the validation of a DPoP proof as specified by RFC9449.
        Full validation as specified by RFC9449 is the responsibility of the resource server.
        This is a convenience API where the the following is validated:
        * The DPoP proof is a valid JWT
        * The http method in the DPoP proof is the same as the http method in the request
        * The URL in the DPoP proof is the same as the URL in the request (fragment and query parameters are ignored)
        * The thumbprint given (returned from token introspection) is the same as the thumbprint of the public key used to sign the DPoP proof
        * The ath field in the DPoP proof matches the hash of the access token
        * The jti field in the DPoP proof is unique
      tags:
        - auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DPoPValidateRequest"
      responses:
        '200':
          description: A response containing the validity of the DPoP proof header for the access token and HTTP request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DPoPValidateResponse"
        default:
          $ref: '../common/error_response.yaml'
components:
  schemas:
    cnf:
      description: The 'confirmation' claim is used in JWTs to proof the possession of a key.
      required:
        - jkt
      properties:
        jkt:
          type: string
          description: JWK thumbprint
    DPoPRequest:
      type: object
      required:
        - htm
        - token
        - htu
      properties:
        htm:
          type: string
          description: The HTTP method for which the DPoP proof is requested.
          example: "POST"
        token:
          type: string
          description: The access token for which the DPoP proof is requested.
          example: "eyJhbGciOi"
        htu:
          type: string
          description: The URL for which the DPoP proof is requested. Query params and fragments are ignored during validation.
          example: "https://example.com/resource"
    DPoPResponse:
      type: object
      required:
        - dpop
      properties:
        dpop:
          type: string
          description: The DPoP proof as specified by https://datatracker.ietf.org/doc/html/rfc9449 for resource requests
    DPoPValidateRequest:
      type: object
      required:
        - dpop_proof
        - method
        - thumbprint
        - token
        - url
      properties:
        dpop_proof:
          type: string
          description: The DPoP Proof as specified by https://datatracker.ietf.org/doc/html/rfc9449 for resource requests
          example: "eyJhbGciOi..lgtla"
        method:
          type: string
          description: The HTTP method against which the DPoP proof is validated.
          example: "POST"
        thumbprint:
          type: string
          description: The thumbprint of the public key used to sign the DPoP proof. Base64url encoded, no padding.
          example: "jlkhnp87453slfhansdhf"
        token:
          type: string
          description: The access token against which the DPoP proof is validated.
          example: "eyJhbGciOi"
        url:
          type: string
          description: The URL against which the DPoP proof is validated. Query params and fragments are ignored during validation.
          example: "https://example.com/resource"
    DPoPValidateResponse:
      type: object
      required:
        - valid
      properties:
        reason:
          type: string
          description: The reason why the DPoP Proof header is invalid.
        valid:
          type: boolean
          description: True if the DPoP Proof header is valid for the access token and HTTP request, false if it is not.
    ServiceAccessTokenRequest:
      type: object
      description: Request for an access token for a service.
      required:
        - authorization_server
        - scope
      properties:
        authorization_server:
          description: |
            The OAuth Authorization Server's identifier as specified in RFC 8414 (section 2),
            used to locate the OAuth2 Authorization Server metadata.
          type: string
          example: https://example.com/oauth2
        scope:
          type: string
          description: The scope that will be the service for which this access token can be used.
          example: eOverdracht-sender
        id_token:
          type: string
          description: |
            An optional ID Token (JWT) that represents the end-user.
            This ID token is included in the Verifiable Presentation that is used to request the access token.
            It currently only supports Dezi ID tokens.
        credentials:
          type: array
          description: |
            Additional credentials to present (if required by the authorizer), in addition to those in the requester's wallet.
            They must be in the form of a Verifiable Credential in JSON form.
            The serialized form (JWT or JSON-LD) in the resulting Verifiable Presentation depends on the capability of the authorizing party.
            A typical use case is to provide a self-attested credential to convey information about the user that initiated the request.
            
            The following credential fields are automatically filled (when not present), and may be omitted:
            - issuer, credentialSubject.id (MUST be omitted; filled with the DID of the requester)
            - issuanceDate (filled with the current date/time)
            - id (filled with a UUID)
            - proof/signature (MUST be omitted; integrity protection is covered by the VP's proof/signature)
          items:
            $ref: '#/components/schemas/VerifiableCredential'
          example: [
            {
              "@context": [
                "https://www.w3.org/2018/credentials/v1",
                "https://nuts.nl/credentials/v1"
              ],
              "type": ["VerifiableCredential", "NutsEmployeeCredential"],
              "credentialSubject": {
                "name": "John Doe",
                "roleName": "Janitor",
                "identifier": "123456"
              }
            }
          ]
        token_type:
          type: string
          description: "The type of access token that is preferred, default: DPoP"
          default: DPoP
          enum: [ Bearer, DPoP ]
    UserAccessTokenRequest:
      type: object
      description: Request for an access token for a user.
      required:
        - authorization_server
        - redirect_uri
        - scope
      properties:
        authorization_server:
          description: |
            The OAuth Authorization Server's identifier as specified in RFC 8414 (section 2),
            used to locate the OAuth2 Authorization Server metadata.
          type: string
          example: https://example.com/oauth2
        scope:
          type: string
          description: The scope that will be the service for which this access token can be used.
          example: eOverdracht-sender
        token_type:
          type: string
          description: "The type of access token that is prefered. Supported values: [Bearer, DPoP], default: DPoP"
          enum:
            - Bearer
            - DPoP
        redirect_uri:
          type: string
          description: |
            The URL to which the user-agent will be redirected after the authorization request.
            This is the URL of the calling application. 
            The OAuth2 flow will finish at the /callback URL of the node and the node will redirect the user to this redirect_uri.
        preauthorized_user:
          $ref: '#/components/schemas/UserDetails'
    VerifiablePresentation:
      $ref: '../common/ssi_types.yaml#/components/schemas/VerifiablePresentation'
    RedirectResponse:
      type: object
      required:
        - redirect_uri
      properties:
        redirect_uri:
          type: string
          description: |
            The URL to which the user-agent will be redirected after the authorization request.
          example: "https://example.com/callback"
    RedirectResponseWithID:
      type: object
      required:
        - redirect_uri
        - session_id
      properties:
        redirect_uri:
          type: string
          description: The URL to which the user-agent will be redirected after the authorization request.
          example: "https://example.com/callback"
        session_id:
          type: string
          description: The session ID that can be used to retrieve the access token by the calling application.
          example: "eyJhbGciOiJSUzI1NiIsI"
    UserDetails:
      type: object
      description: |
        Claims about the authorized user.
      required:
        - name
        - id
        - role
      properties:
        name:
          type: string
          description: Human-readable name of the user.
          example: "John Doe"
        id:
          type: string
          description: Machine-readable identifier, uniquely identifying the user in the issuing system.
          example:
            - "jdoe"
            - "123456"
            - "jdoe@example.com"
        role:
          type: string
          description: Role of the user.
          example: "Verpleegkundige niveau 4"
    VerifiableCredential:
      $ref: '../common/ssi_types.yaml#/components/schemas/VerifiableCredential'
    TokenResponse:
      type: object
      description: |
        Token Responses are made as defined in (RFC6749)[https://datatracker.ietf.org/doc/html/rfc6749#section-5.1].
        With an additional field 'expires_at' used for cached tokens to recalculate 'expires_in'.
        The field 'dpop_kid' is added from (RFC9449)[https://datatracker.ietf.org/doc/html/rfc9449].
      required:
        - access_token
        - token_type
      properties:
        access_token:
          type: string
          description: |
            The access token issued by the authorization server.
          example: "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp..sHQ"
        dpop_kid:
          type: string
          description: |
            The kid of the DPoP key that is used to sign dpop headers.
          example: "did:web:example.com:resource-owner#key-1"
        token_type:
          type: string
          description: |
            The type of the token issued as described in [RFC6749].
          example: "Bearer"
        scope:
          type: string
        status:
          type: string
          description: |
            The status of the access token request. Can be 'pending' or 'active'.
            If the status is 'pending', the access token is not yet available.
            Only used when the access token is requested through /request-user-access-token.
          enum: [ pending, active ]
        expires_in:
          type: integer
          description: |
            The lifetime in seconds of the access token.
          example: 3600
        expires_at:
          type: integer
          description: |
              The expiration time of the access token in seconds since UNIX epoch.
          example: 1640995200
      example:
        {
          "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp..sHQ",
          "token_type": "Bearer",
          "expires_in": 3600,
        }
    PresentationDefinition:
      description: |
        A presentation definition is a JSON object that describes the desired verifiable credentials and presentation formats.
        Specified at https://identity.foundation/presentation-exchange/spec/v2.0.0/
      type: object
    PresentationSubmission:
      description: |
        A presentation submission is a JSON object that describes the mapping between the required verifiable credentials listed in the presentation definition and the supplied verifiable presentation.
        Specified at https://identity.foundation/presentation-exchange/spec/v2.0.0/
      type: object
    TokenIntrospectionRequest:
      description: >
        Token introspection request as described in RFC7662 section 2.1

        Alongside the defined properties, it can return values (additionalProperties) from the Verifiable Credentials that resulted from the Presentation Exchange.
      required:
        - token
      properties:
        token:
          type: string
      example: token=spnhVHZ4IFVvuNrpflVaB1A7P3A2xZ7G_a8gF_SHMynYSA
    TokenIntrospectionResponse:
      description: Token introspection response as described in RFC7662 section 2.2
      required:
        - active
      additionalProperties: { }
      properties:
        active:
          type: boolean
          description: True if the token is active, false if the token is expired, malformed etc. Required per RFC7662
        cnf:
          $ref: '#/components/schemas/cnf'
        iss:
          type: string
          description: Issuer URL of the authorizer.
          example: https://example.com/oauth2/authorizer
        aud:
          type: string
          description: RFC7662 - Service-specific string identifier or list of string identifiers representing the intended audience for this token, as defined in JWT [RFC7519].
          example: "https://target_token_endpoint"
        client_id:
          type: string
          description: The client identity the access token was issued to. Since the Verifiable Presentation is used to grant access, the client_id reflects the client_id in the access token request.
          example: https://example.com/oauth2/client
        exp:
          type: integer
          description: Expiration date in seconds since UNIX epoch
        iat:
          type: integer
          description: Issuance time in seconds since UNIX epoch
        scope:
          type: string
          description: granted scopes
    ExtendedTokenIntrospectionResponse:
      allOf:
        - $ref: '#/components/schemas/TokenIntrospectionResponse'
        - properties:
            presentation_definitions:
              $ref: '#/components/schemas/RequiredPresentationDefinitions'
            presentation_submissions:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/PresentationSubmission'
              description: |
                Mapping of Presentation Definition IDs that were fulfilled to Presentation Submissions.
            vps:
              type: array
              items:
                $ref: '#/components/schemas/VerifiablePresentation'
    RequiredPresentationDefinitions:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/PresentationDefinition'
      description: |
        Presentation Definitions, as described in Presentation Exchange specification, fulfilled to obtain the access token
        The map key is the wallet owner (user/organization)
  securitySchemes:
    jwtBearerAuth:
      type: http
      scheme: Bearer

security:
  - { }
  - jwtBearerAuth: [ ]