apnf-man-platform-openapi-auth.yaml

openapi: 3.0.3
info:
  title: API for the MAN authentication endpoint
  version: 1.0.0
  license:
    name: CC-BY-SA-4.0
    url: https://creativecommons.org/licenses/by-sa/4.0/legalcode
  contact:
    email: api-support@metaswitch.com
    url: https://www.metaswitch.com/
  description: |
    # API for the MAN authentication endpoint

    This is the OpenAPI specification for the authentication endpoint, as provided by APNF under the CC-BY-SA-4.0 license,
    and edited by Metaswitch (a Microsoft company) under the same license. These edits remove some response parameters and
    response codes from the APNF version for Metaswitch's client-side use-case, and make minor adjustments
    to the arrangement of fields (commented in-line) and descriptions for compatibility with the Swagger OpenAPI tool.

    There follows information retained from the original API definition.

    # Introduction

    Welcome to the APNF MAN platform authentication API reference.
    The API listed in this document shall be used by MAN platform API clients
    to get access tokens required for authenticating against any MAN platform non-public APIs.
    The API relies on OpenID Connect to generate the API access tokens, which will be valid for a
    limited time period once they are generated.

    ## API Authentication Process

    Except for its BPCO module, the MAN platform requires clients to be authenticated for accessing its APIs.
    The authentication process relies on OAuth 2.0 protocol, where an access token needs to be passed to the API request as a JSON Web TOKEN
    using a Bearer `Authorization` header.

    ```
    Authorization: Bearer <JWT>
    ```

    An access token needs therefore first to be created using this API in order to be passed to any other MAN platform API call.
    Once created, an access token is valid for 5 minutes.

    ## Prerequisites

    Before requesting any access token, clients first need to create an API credential using the MAN platform UI.
    API credentials indeed provide the `client_id` and `client_request` properties which are needed when calling the access token generation API.

    ## Rate Limiting

    No rate limiting is applied to this API.


    # References

    Additional API references are also available, covering other MAN platform functionalities:
    - **MAN Platform GCO API Reference**, listing the MAN platform GCO (Gestionnaires des Certificats Opérateurs) module APIs, to manage service provider data in the MAN platform, including STI certificates.
    - **MAN Platform BPCO API Reference**, listing APIs published as part of the BPCO (Base Publique des Certificats Opérateurs), the MAN platform public access service used to access STI certificates.

    # History

    **1.5.0** - 2023/09/27
    - Clarify access token lifetime
    - Include in `Description` section rate limiting logic
    - Add CC-BY-SA-4.0 license

    **1.3.0** - 2023/06/16
    - Add `servers` entries for VABF and Preproduction platforms
    - Update `client_assertion` value in example request body
    - Update `access_token` value in example response body
    - Describe format of the `access_token` generated in the response

    **1.2.0** - 2023/05/04
    - Replace `token_type` response 'bearer' value to 'Bearer'
    - Update response body required properties and add `refresh_expires_in` and `scope` properties
    - Add 405 error case
    - Update `error_description` example value for 400 error case

    **1.1.0** - 2023/01/18
    - Update API URL to prefix path with *auth/*
    - Update `aud` property description to add *auth/* in its possible values and use a reference to the document `servers.url` property
tags:
  - name: Access Tokens
paths:
  /auth/realms/{realm}/protocol/openid-connect/token:
    post:
      summary: Generate an access token from an API credential
      tags:
        - Access Tokens
      parameters:
        - name: realm
          in: path
          description: Realm to manage users, credentials, identity providers & access to protected MAN resources
          required: true
          schema:
            type: string
            enum:
              - MAN
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                    - client_credentials
                  description: The type of authorization flow. Shall be set to `client_credentials`
                client_assertion_type:
                  type: string
                  enum:
                    - urn:ietf:params:oauth:client-assertion-type:jwt-bearer
                  description: The format of the assertion. Its value must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.
                client_assertion:
                  type: string
                  description: |
                    The assertion being used to authenticate the client :

                    A JSON Web Signature Compact Serialization, represented as the following concatenation:
                    ```
                    BASE64URL(UTF8(JWS Protected Header)) || '.' ||
                    BASE64URL(JWS Payload) || '.' ||
                    BASE64URL(JWS Signature)
                    ```
                    resulting in
                    ```
                    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
                    .eyJzdWIi[...omitted for brevity...]
                    .fpLTE3dS[...omitted for brevity...]
                    ```
                    ###### JWS Protected Header
                    ```
                    {
                      "typ":"JWT",
                      "alg":"HS256"
                    }
                    ```
                    **JWS Payload**
                    ```
                    {
                      "sub":(Subject),
                      "iss":(Issuer),
                      "aud":(Audience),
                      "jti":(JWT ID),
                      "exp":(Expiration Time)
                    }
                    ```
                    where
                    * __Subject__ and __Issuer__ MUST match the `client_id` property of an API credential created from the MAN platform.
                    * __Audience__ MUST match a value among :
                      * the __issuer url__: <AUTH_API_URL>/auth/realms/{realm}
                      * the __token endpoint url__: <AUTH_API_URL>/auth/realms/{realm}/protocol/openid-connect/token

                      where <AUTH_API_URL> must be replaced by the `servers.url` property defined in this document corresponding to the platform you call the method.
                    * __JWT ID__ MUST be unique (not reusable before expiration)
                    * __Expiration Time__ MUST be a numeric value representing the number of seconds since January 1, 1970 (midnight UTC/GMT), and defining the expiration time on or after which the token MUST NOT be accepted for processing.

                    **JWS Signature**
                    ```
                    HMACSHA256(
                      BASE64URL(UTF8(JWS Protected Header)) || '.' ||
                      BASE64URL(JWS Payload) ,
                      (Symmetric Key)
                    )
                    ```
                    where
                    * __Symmetric Key__ MUST match the `client_secret` property of the API credential associated with the `client_id` property used for the `Subject` and `Issuer` parameters.
                  example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL3Nzby52YWJmLm1hbi1wbGF0ZWZvcm1lLmZyL2F1dGgvcmVhbG1zL01BTiIsImV4cCI6MTY4MzcwODMzMSwiaXNzIjoic3BjMDAtY3JlZC0xIiwianRpIjoiYjJiZjNhYWItYzA5NS00ZWIwLWEwYjItYjNhZGNjM2MzYTBlIiwic3ViIjoic3BjMDAtY3JlZC0xIn0.EKJArLh/CjiysHHeHSIO9JOP7/fziRs1eqWkUvSH2bg
              required:
                - grant_type
                - client_assertion_type
                - client_assertion
      responses:
        '200':
          description: Successful token response with access token
          headers:
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            Content-Length:
              $ref: '#/components/headers/Content-Length'
            Pragma:
              $ref: '#/components/headers/Pragma'
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: JSON Web Token that must be passed as is to MAN platform GCO API requests to authenticate them.
                  expires_in:
                    type: integer
                    description: The lifetime in seconds of the access token.
                  not-before-policy:
                    type: integer
                    description: All tokens issued before this timestamp become invalid. The default value is 0. Only a platform malfunction may generate the change of this value.
                  refresh_expires_in:
                    type: integer
                    description: Refresh token lifetime. Always set to 0.
                  scope:
                    type: string
                    description: Token scope. Always empty.
                  token_type:
                    type: string
                    enum:
                      - Bearer
                    description: The token type. Shall be set to `Bearer`.
                required:
                  - access_token
                  - expires_in
                  - not-before-policy
                  - refresh_expires_in
                  - scope
                  - token_type
              example:
                access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImwybXEtLUtPQ0h3dlZtczhIQVRnRnY5ZFM2MFpqb3ZtR3p6T3NFOVo2UFUifQ.eyJleHAiOjE2ODM3MDgxMDEsImlhdCI6MTY4MzcwNzgwMSwianRpIjoiNDU3ZWZhMjktMGIyMC00Njc4LWI0OTgtMDc0ZjJmZDhhM2JjIiwiaXNzIjoiaHR0cHM6Ly92YWJmLm1hbi1wbGF0ZWZvcm1lLmZyL2F1dGgvcmVhbG1zL01BTiIsInN1YiI6Ijk0MzY2NzU4LWUyOWQtNDgxNy05MTVjLThlYTgyNTAzZjI0ZSIsInR5cCI6IkJlYXJlciIsImF6cCI6InNwYzAwLWNyZWQtMSIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJNQU5BR0VSIl19LCJzY29wZSI6IiIsImdyb3Vwc191dWlkIjp7Ii9wcm92aWRlcnMvU1BDMDAiOiI1YTMwOWZmYy1lZjBlLTExZWQtYTA1Yi0wMjQyYWMxMjAwMDMifSwiY2xpZW50SG9zdCI6IjI1NS4yNTUuMjU1LjI1NSIsImNsaWVudElkIjoic3BjMDAtY3JlZC0xIiwicHJvdmlkZXJfc3RhdHVzIjoiRU5BQkxFRCIsImNsaWVudEFkZHJlc3MiOiIyNTUuMjU1LjI1NS4yNTUifQ.Ov0VrQsuZruSPVbMBSmMIGnjw9cajfxjSH8Y3EZ7FjM
                expires_in: 60
                not-before-policy: 0
                refresh_expires_in: 0
                token_type: Bearer
                scope: ''
        '400':
          description: Token error response
          headers:
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            Content-Length:
              $ref: '#/components/headers/Content-Length'
            Pragma:
              $ref: '#/components/headers/Pragma'
          content:
            application/json:
              schema:
                # Differs from the original APNF API document (but not in function).
                # See comment in components -> schemas container. 
                $ref: '#/components/schemas/ErrorBadRequest'
              example:
                error: invalid_client
                error_description: Invalid client credentials
        '401':
          description: Unauthorized access (e.g. client misconfigured for client credentials flow)
          headers:
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            Content-Length:
              $ref: '#/components/headers/Content-Length'
            Pragma:
              $ref: '#/components/headers/Pragma'
          content:
            application/json:
              schema:
                # Differs from the original APNF API document (but not in function).
                # See comment in components -> schemas container. 
                $ref: '#/components/schemas/ErrorUnauthorized'
              example:
                error: invalid_request
                error_description: Client not enabled to retrieve service account
        '403':
          description: Forbidden access (e.g. realm disabled)
          headers:
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            Content-Length:
              $ref: '#/components/headers/Content-Length'
            Pragma:
              $ref: '#/components/headers/Pragma'
          content:
            application/json:
              schema:
                # Differs from the original APNF API document (but not in function).
                # See comment in components -> schemas container. 
                $ref: '#/components/schemas/ErrorForbidden'
              example:
                error: access_denied
                error_description: Realm not enabled
        '404':
          description: Resource not found (e.g. realm not found)
          headers:
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            Content-Length:
              $ref: '#/components/headers/Content-Length'
            Pragma:
              $ref: '#/components/headers/Pragma'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Realm does not exist
        '500':
          description: Unexpected error occured
          headers:
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            Content-Length:
              $ref: '#/components/headers/Content-Length'
            Pragma:
              $ref: '#/components/headers/Pragma'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: unknown_error
        '503':
          description: Service unavailable or under maintenance
          headers:
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            Content-Length:
              $ref: '#/components/headers/Content-Length'
            Pragma:
              $ref: '#/components/headers/Pragma'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: service_unavailable
components:
  headers:
    Cache-Control:
      description: Control caching in browsers and shared caches
      schema:
        type: string
        enum:
          - no-store
    Content-Length:
      description: Size of the message body, in bytes
      schema:
        type: integer
    Pragma:
      description: Cache-Control backwards compatibility with HTTP/1.0 cache
      schema:
        type: string
        enum:
          - no-cache
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
      required:
        - error
    # The following three error formats have been refactored into their own schema
    # definitions as the Swagger openapi-generator could not generate the Rust
    # bindings in the original format. This API document should be functionally
    # equivalent to the original.
    ErrorBadRequest:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            error:
              enum:
                - invalid_client
                - invalid_request
                - unauthorized_client
                - unsupported_grant_type
    ErrorUnauthorized:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            error:
              enum:
                - invalid_request
                - unauthorized_client
    ErrorForbidden:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            error:
              enum:
                - access_denied
                - invalid_request