Initial content for Number Verify

code/API_definitions/CAMARA_numberVerify.yaml

@@ -0,0 +1,313 @@
+openapi: 3.0.0
+info:
+  title: CAMARA numberVerify
+  description: Number Verify service based on Mobile Connect Verified MSISDN specification
+  version: 0.1.0
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+  contact:
+    name: Support
+    email: support@example.com
+    url: https://support.example.com
+externalDocs:
+  description: GSMA Mobile Connect Verified MSISDN specification
+  url: https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.54-Mobile-Connect-Verified-MSISDN-Definition-and-Technical-Requirements-1.0.pdf
+servers:
+  - url: https://{countryServer}.{domain}
+    variables:
+      countryServer:
+        default: api.server
+        description: a server specific to country where API is delivered
+      domain:
+        default: com
+        description: a domain where server is delivered
+    description: API server providing CAMARA APIs
+tags:
+  - name: Verified MSISDN
+    description: Standard Number Verify service based on Mobile Connect Verified MSISDN
+paths:
+  /authorize:
+    get:
+      tags:
+        - Verified MSISDN
+      externalDocs:
+        description: Mobile Connect Device Initiated OIDC profile
+        url: https://www.gsma.com/identity/wp-content/uploads/2022/11/IDY.01-v3.0.pdf
+      security:
+        - openId: [mc_vm_match,mc_vm_match_hash]
+      summary: Authorize request for MC Verified MSISDN service
+      parameters:
+        - name: response_type
+          in: query
+          required: true
+          schema:
+            type: string
+            enum:
+              - code
+        - name: client_id
+          in: query
+          schema:
+            type: string
+            format: uuid
+          description: client_id provided by MNO for mc vm match api consumption
+          example: '{client_id}'
+        - name: version
+          in: query
+          required: true
+          schema:
+            type: string
+            enum:
+              - mc_v2.1
+        - name: redirect_uri
+          in: query
+          required: true
+          schema:
+            type: string
+            format: uri
+          example: http://localhost
+        - name: state
+          in: query
+          required: true
+          schema:
+            type: string
+          example: teststate
+        - name: nonce
+          in: query
+          required: true
+          schema:
+            type: string
+          example: '123456'
+        - name: acr_values
+          in: query
+          required: true
+          schema:
+            type: integer
+            enum:
+              - 2
+              - 3
+          example: '2'
+      responses:
+        '302':
+          description: /authorize endpoint process the reqest and returns either success or error on redirect
+          content:
+            application/json:
+              schema:
+                oneOf:
+                 - $ref: '#/components/schemas/oidc_token_response'
+                 - $ref: '#/components/responses/302redirectError'
+                type: object
+        '400':
+          description: invalid request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/serverError'
+  /token:
+    post:
+      tags:
+        - Verified MSISDN
+      summary: Token
+      security:
+        - basicAuth: []
+      parameters:
+        - name: grant_type
+          in: query
+          required: true
+          schema:
+            type: string
+            enum:
+              - authorization_code
+        - name: code
+          in: query
+          required: true
+          schema:
+            type: string
+            format: uuid
+          example: jUQqqE-mawjwzscVbp00BRrdVWKU6qw78fklU1MSl9A
+        - name: redirect_uri
+          in: query
+          required: true
+          schema:
+            type: string
+            format: uri
+          example: http://localhost
+      responses:
+        '400':
+          description: invalid request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/serverError'
+        '401':
+          description: access denied or invalid request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/serverError'
+        '500':
+          description: internal error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/serverError'
+        '503':
+          description: service unavailable
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/serverError'
+
+  /openid/userinfo:
+    post:
+      tags:
+        - Verified MSISDN
+      summary: User Info
+      security:
+        - bearerAuth: []
+      requestBody:
+        description: delivers end user input for phone number verification
+        required: true
+        content:
+          application/json:
+            schema:
+              oneOf:
+                - $ref: '#/components/schemas/mc_vm_match_resource_request'
+                - $ref: '#/components/schemas/mc_vm_match_hash_resource_request'
+      responses:
+        '200':
+          description: success - tokens returned
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/mc_vm_match_response'
+        '400':
+          description: bad request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/serverError'
+
+security:
+  - openId:
+    - mc_vm_match
+    - mc_vm_match_hash
+
+components:
+  securitySchemes:
+    openid:
+      type: openIdConnect
+      openIdConnectUrl: https://example.com/.well-known/openid-configuration
+    bearerAuth:
+      type: http
+      scheme: bearer
+    basicAuth:
+      type: http
+      scheme: basic  
+  responses:
+    accessDenied:
+      description: request cannot be completed due to bad request
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/serverError'
+    302redirectError:
+      description: error message returned on redirect
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/redirectError'
+  schemas:
+    mc_vm_match_resource_request:
+      type: object
+      properties:
+        mc_claims:
+          type: object
+          properties:
+            device_msisdn:
+              type: string
+              description: country code (with leading +) and phone number
+              pattern: '^[\+]?[(]?[0-9]{3}[)]?[-\s\.]?[0-9]{3}[-\s\.]?[0-9]{4,6}$'
+              example: '+4915164818763'
+          required:
+            - device_msisdn
+    mc_vm_match_hash_resource_request:
+      type: object
+      properties:
+        mc_claims:
+          type: object
+          properties:
+            device_msisdn_hash:
+              type: string
+              description: SHA256 hash
+          required:
+            - device_msisdn_hash
+    mc_vm_match_response:
+      type: object
+      properties:
+        sub:
+          type: string
+          format: uuid
+        device_msisdn_verified:
+          type: boolean
+      required:
+        - device_msisdn_verified
+        - sub
+    oidc_auth_response:
+      type: object
+      properties:
+        code:
+          type: string
+          format: uuid
+        state:
+          type: string
+          description: if state is present in auhtorization request, response must match it
+          example: teststate
+      required:
+        - code
+        - state
+    oidc_token_response:
+      type: object
+      properties:
+        access_token:
+          type: string
+          format: uuid
+        token_type:
+          type: string
+          enum:
+            - bearer
+        id_token:
+          type: string
+          format: jwt
+          description: contains auth information of the device namely sub parameter
+          example: eyJraWQiOiJVZ1JmNEk4WWw2cGo0NHRnZGx3WUJ3PT0iLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiS3BIWlpGb2hFRUZzbUMwQW9iV1BBUSIsInN1YiI6IjlmZTkxNzE4LWI2NmEtNGE3Zi1hYTgxLTU1YWEwZjA0YmViMCIsImF1ZCI6WyIwZDMzM2IzOS05NmNhLTRhZTMtYTcxNS03NGRkZGRjY2M0MWEiLCIwZDMzM2IzOS05NmNhLTRhZTMtYTcxNS03NGRkZGRjY2M0MWEiXSwiYWNyIjoiMiIsImF6cCI6IjBkMzMzYjM5LTk2Y2EtNGFlMy1hNzE1LTc0ZGRkZGNjYzQxYSIsImF1dGhfdGltZSI6MTY2Nzk5NDMwMiwiYW1yIjpbIlNFQU1fT0siXSwiaXNzIjoibW9iaWxlY29ubmVjdC9pc3N1ZXIiLCJleHAiOjE2Njc5OTYzNTgsImlhdCI6MTY2Nzk5NDM1OCwibm9uY2UiOiIxMjM0NTYifQ==.aRJkQjoF4yOBYJ7hXkkDbdoMAWCfKqCx0JwxTcTMXPXTZI4njuaqOvLCQbwN-HTHbfUWp0_VOUovW3dyvao45C36zhiDaSl8RYLw2CuBEeL1471GmWPr-ivkNTTosFC855GHa8I4yiAUnrWnhv2jfiGISNZi2Tkm6Dl_yNAC17P44gAhnh8FTd_FbLJyOaOtaE7cKrgvAvipeqP0wIT-mAVNUhrU3PmmxcxNWZaY8dEE6WKWhbwHQZ5Juq8ikxT84dOGjn7IxxFdRgPpYgsNHta8tYPnc_6jY6jnnEHB8Utpkrl0fyNPDD2wp5dBk9F2lzppdcG-ZJEAZrP22nBf7g
+        expires_in:
+          type: integer
+          example: 500
+      required:
+        - access_token
+        - token_type
+        - id_token
+        - expires_in
+    serverError:
+      type: object
+      properties:
+        error_description:
+          type: string
+          example: Mandatory parameter code is invalid
+        error:
+          type: string
+          example: invalid_request
+      required:
+        - error
+        - error_description
+    redirectError:
+      type: object
+      properties:
+        error_description:
+          type: string
+          example: Mandatory parameter code is invalid
+        error:
+          type: string
+          example: invalid_request
+