openapi: 3.0.0 info: title: Identity Provider API description: >- Use the Identity Provider API to manage Identity providers in the API-M Credential Management partition. version: v1 servers: - description: NGINX Controller API url: 'https://{{CONTROLLER_FQDN}}/api/v1' paths: /security/identity-providers: get: tags: - Identity Providers summary: List Identity Providers description: > Returns a list of all Identity Provider resources. > **Note:** These resources were known as Client Groups in pre-3.x versions of NGINX Controller. operationId: identityProvidersSearch responses: '200': description: >- Successfully retrieved a list of Identity Provider resources. content: application/json: schema: $ref: '#/components/schemas/IdentityProviderList' '400': description: >- Bad input parameter, or possibly a bad URI. Check the input for typos and try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '/security/identity-providers/{identityProviderName}': get: tags: - Identity Providers summary: Get an Identity Provider description: Returns the specified Identity Provider resource. operationId: identityProvidersGet responses: '200': description: >- Successfully returnd the specified Identity Provider resource. content: application/json: schema: $ref: '#/components/schemas/IdentityProvider' '403': description: The request failed due to insufficient privileges. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '404': description: >- The specified Identity Provider resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '500': description: >- The request cannot be processed because of an internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' put: tags: - Identity Providers summary: Upsert an Identity Provider description: > Creates a new Identity Provider, or creates an existing Identity Provider resource. operationId: identityProvidersPut requestBody: content: application/json: schema: $ref: '#/components/schemas/IdentityProvider' examples: IdentityProviderRequest: $ref: '#/components/examples/IdentityProviderRequest' responses: '200': description: >- Successfully updated the specified Identity Provider resource. content: application/json: schema: $ref: '#/components/schemas/IdentityProvider' '201': description: >- Successfully created the requested Identity Provider resource. content: application/json: schema: $ref: '#/components/schemas/IdentityProvider' '202': description: >- Successfully accepted the requested Identity Provider resource and is currently processing it. content: application/json: schema: $ref: '#/components/schemas/IdentityProvider' '400': description: >- Bad input parameter, or possibly a bad URI. Check the input for typos and try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '429': description: > The request to update or create an Identity Provider resource failed due to exceeding request processing threshold. Allow the server to process existing requests, then try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' delete: tags: - Identity Providers summary: Delete an Identity Provider description: Deletes the specified Identity Provider resource. operationId: identityProvidersDelete responses: '202': description: > The Identity Provider resource has been marked for deletion. The resource will be deleted after the publish/cleanup succeeds. content: application/json: schema: $ref: '#/components/schemas/IdentityProvider' '204': description: >- Successfully deleted the specified Identity Provider resource. No content is returned. '400': description: >- Bad input parameter, or possibly a bad URI. Check the input for typos and try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '404': description: >- The specified Identity Provider resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '429': description: > The request to delete an Identity Provider resource failed due to exceeding request processing threshold. Allow the server to process existing requests, then try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '500': description: >- The request cannot be processed because of an internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' parameters: - $ref: '#/components/parameters/identityProviderName' '/security/identity-providers/{identityProviderName}/clients': get: tags: - Identity Provider Clients summary: List Identity Provider Clients description: | Returns a list of all Identity Provider Client resources. operationId: identityProviderClientsSearch responses: '200': description: >- Successfully retrieved a list of Identity Provider Client resources. content: application/json: schema: $ref: '#/components/schemas/IdentityProviderClientList' '400': description: >- Bad input parameter, or possibly a bad URI. Check the input for typos and try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '404': description: >- The specified Identity Provider resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' put: tags: - Identity Provider Clients summary: Create Multiple Identity Provider Clients description: > Creates or updates multiple Identity Provider Client resources. operationId: identityProviderClientsPutList requestBody: content: application/json: schema: $ref: '#/components/schemas/IdentityProviderClientList' examples: IdentityProviderClientListRequest: $ref: >- #/components/examples/IdentityProviderClientListRequest responses: '200': description: >- Successfully upserted the Identity Provider Client resources. content: application/json: schema: $ref: '#/components/schemas/IdentityProviderClientList' '202': description: >- Successfully accepted the requested Identity Provider Client resources and is currently processing it. content: application/json: schema: $ref: '#/components/schemas/IdentityProviderClientList' '400': description: >- Bad input parameter, or possibly a bad URI. Check the input for typos and try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '404': description: >- The specified Identity Provider resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '409': description: >- The Identity Provider Client resource conflicts with another resource. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' parameters: - $ref: '#/components/parameters/identityProviderName' '/security/identity-providers/{identityProviderName}/clients/{identityProviderClientName}': get: tags: - Identity Provider Clients summary: Get an Identity Provider Client description: >- Returns information for the specified Identity Provider Client resource. operationId: identityProviderClientsGet responses: '200': description: >- Successfully returned the specified Identity Provider Client resource. content: application/json: schema: $ref: '#/components/schemas/IdentityProviderClient' '404': description: >- The specified Identity Provider Client resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' put: tags: - Identity Provider Clients summary: Update an Identity Provider Client description: Updates the specified Identity Provider Client resource. operationId: identityProviderClientsPut requestBody: content: application/json: schema: $ref: '#/components/schemas/IdentityProviderClient' examples: IdentityProviderClientRequest: $ref: >- #/components/examples/IdentityProviderClientRequest responses: '200': description: >- Successfully updated the specified Identity Provider Client resource. content: application/json: schema: $ref: '#/components/schemas/IdentityProviderClient' '201': description: >- Successfully created the specified Identity Provider Client resource. content: application/json: schema: $ref: '#/components/schemas/IdentityProviderClient' '202': description: >- Successfully accepted the requested Identity Provider Client resource and is currently processing it. content: application/json: schema: $ref: '#/components/schemas/IdentityProviderClient' '400': description: >- Bad input parameter, or possibly a bad URI. Check the input for typos and try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '404': description: >- The specified Identity Provider resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '429': description: > The request to update or create an Identity Provider Client resource failed due to exceeding request processing threshold. Allow the server to process existing requests, then try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' patch: tags: - Identity Provider Clients summary: Update an Identity Provider Client description: Updates the specified Identity Provider Client resource. operationId: identityProviderClientsPatch requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateIdentityProviderClient' examples: IdentityProviderClientPatchMetadataRequest: $ref: >- #/components/examples/IdentityProviderClientPatchMetadataRequest IdentityProviderClientPatchDesiredStateRequest: $ref: >- #/components/examples/IdentityProviderClientPatchDesiredStateRequest responses: '200': description: >- Successfully updated the specified Identity Provider Client resource. content: application/json: schema: $ref: '#/components/schemas/IdentityProviderClient' '202': description: >- Successfully accepted the request to update an Identity Provider Client resource and is currently processing it. content: application/json: schema: $ref: '#/components/schemas/IdentityProviderClient' '400': description: >- Bad input parameter, or possibly a bad URI. Check the input for typos and try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '404': description: >- The specified Identity Provider Client resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '429': description: > The request to update an Identity Provider Client resource failed due to exceeding request processing threshold. Allow the server to process existing requests, then try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' delete: tags: - Identity Provider Clients summary: Delete an Identity Provider Client description: Deletes the specified Identity Provider Client resource. operationId: identityProviderClientsDelete responses: '202': description: > Identity Provider Client resource has been marked for deletion. The resource will be deleted after the publish/cleanup succeeds. content: application/json: schema: $ref: '#/components/schemas/IdentityProviderClient' '204': description: >- Successfully deleted the specified Identity Provider Client resource. No content is returned. '400': description: >- Bad input parameter, or possibly a bad URI. Check the input for typos and try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '404': description: >- The specified Identity Provider Client resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '429': description: > The request to delete an Identity Provider Client resource failed due to exceeding request processing threshold. Allow the server to process existing requests, then try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' parameters: - $ref: '#/components/parameters/identityProviderName' - $ref: '#/components/parameters/identityProviderClientName' components: schemas: IdentityProviderList: type: object description: Contains a list of Identity Provider resources. properties: items: type: array items: $ref: '#/components/schemas/IdentityProvider' APIKeyIdentityProvider: required: - type type: object description: > Use an API key for authentication. > **Note:** Use of API Key authN is not recommended in production environments. properties: type: type: string enum: - API_KEY JWTIdentityProvider: required: - jwkFile - type type: object description: Use a JWT for authentication. properties: type: type: string enum: - JWT jwkFile: description: > Provide the path to - or URI for - a `.jwk` file to use for authentication. You can also provide the `.jwk` file contents inline. discriminator: propertyName: type mapping: INLINE: '#/components/schemas/JWKInline' REMOTE_FILE: '#/components/schemas/JWKRemoteFile' oneOf: - $ref: '#/components/schemas/JWKInline' - $ref: '#/components/schemas/JWKRemoteFile' IdentityProviderDesiredState: required: - environmentRefs - identityProvider type: object properties: environmentRefs: description: The Enviroment associated with the Identity Provider. type: array items: $ref: '#/components/schemas/ResourceRef' identityProvider: $ref: '#/components/schemas/IdentityProviderData' example: environmentRefs: - ref: /services/environments/env1 identityProvider: type: JWT jwkFile: type: REMOTE_FILE uri: 'https://example.com/keys.jwk' cacheExpire: 10h IdentityProviderCurrentStatus: required: - environmentRefs - identityProvider - state type: object properties: environmentRefs: type: array items: $ref: '#/components/schemas/ResourceRef' state: $ref: '#/components/schemas/ConfigState' identityProvider: $ref: '#/components/schemas/IdentityProviderData' IdentityProvider: required: - desiredState - metadata type: object properties: metadata: $ref: '#/components/schemas/ResourceMeta' currentStatus: $ref: '#/components/schemas/IdentityProviderCurrentStatus' desiredState: $ref: '#/components/schemas/IdentityProviderDesiredState' IdentityProviderData: description: >- The means of authentication used by the Identity Provider (JWT or APIKey). oneOf: - $ref: '#/components/schemas/JWTIdentityProvider' - $ref: '#/components/schemas/APIKeyIdentityProvider' discriminator: propertyName: type mapping: API_KEY: '#/components/schemas/APIKeyIdentityProvider' JWT: '#/components/schemas/JWTIdentityProvider' IdentityProviderClientDesiredState: type: object properties: credential: $ref: '#/components/schemas/IdentityProviderClientCredential' IdentityProviderClientCurrentStatus: type: object properties: state: $ref: '#/components/schemas/ConfigState' credential: $ref: '#/components/schemas/IdentityProviderClientCredential' IdentityProviderClient: type: object properties: metadata: $ref: '#/components/schemas/ResourceMeta' currentStatus: $ref: >- #/components/schemas/IdentityProviderClientCurrentStatus desiredState: $ref: >- #/components/schemas/IdentityProviderClientDesiredState IdentityProviderClientCredential: oneOf: - $ref: '#/components/schemas/IdentityProviderAPIKey' discriminator: propertyName: type mapping: API_KEY: '#/components/schemas/IdentityProviderAPIKey' IdentityProviderClientList: type: object properties: items: type: array items: $ref: '#/components/schemas/IdentityProviderClient' UpdateIdentityProviderClient: type: object properties: metadata: $ref: '#/components/schemas/ResourceMeta' currentStatus: $ref: >- #/components/schemas/IdentityProviderClientCurrentStatus desiredState: $ref: >- #/components/schemas/IdentityProviderClientDesiredState JWK: type: object properties: kty: type: string description: >- The cryptographic algorithm family used with the key, such as "RSA" or "EC". use: type: string description: >- The intended use of the public key, whether for encrypting data or verifying the signature on data. key_ops: type: array items: type: string description: >- The operation(s) for which the key is intended to be used. alg: type: string description: The algorithm intended for use with the key. kid: type: string description: The key ID used to match a specific key. x5u: type: string description: >- The X.509 URL that refers to a resource for an X.509 public key certificate or certificate chain. x5c: type: array items: type: string description: >- The X.509 Certificate Chain of one or more PKIX certificates. The PKIX certificate containing the key value MUST be the first certificate. x5t: type: string description: >- The X.509 Certificate SHA-1 Thumbprint (a.k.a. digest) of the DER encoding of an X.509 certificate. x5t256: type: string description: >- The X.509 Certificate SHA-256 Thumbprint (a.k.a. digest) of the DER encoding of an X.509 certificate. p2s: type: string description: >- The salt input value for PBES2 key encryption, which is used as part of the PBKDF2 salt value. p2c: type: string description: >- The PBKDF2 iteration count for PBES2 key encryption, represented as a positive JSON integer. The iteration count adds computational expense, ideally compounded by the possible range of keys introduced by the salt. A minimum iteration count of 1000 is RECOMMENDED. crv: type: string description: >- The cryptographic curve used for an Elliptic Curve public key. x: type: string description: >- The x coordinate of the point for an Elliptic Curve public key. 'y': type: string description: >- The y coordinate of the point for an Elliptic Curve public key. e: type: string description: The exponent value for an RSA public key. exp: type: string description: The exponent value for an RSA public key. 'n': type: string description: The modulus value for an RSA public key. mod: type: string description: The modulus value for an RSA public key. d: type: string description: >- The private key value for an Elliptic Curve private key OR the private exponent value for an RSA private key. p: type: string description: The first prime factor for an RSA private key. q: type: string description: The second prime factor for an RSA private key. dp: type: string description: >- The Chinese Remainder Theorem (CRT) exponent of the first factor for an RSA private key. dq: type: string description: >- The CRT exponent of the second factor for an RSA private key. qi: type: string description: >- The CRT coefficient of the second factor for an RSA private key. oth: description: >- An array of information about any third and subsequent primes, should they exist. type: array items: type: object properties: r: type: string description: The prime factor. d: type: string description: >- The factor CRT exponent of the corresponding prime factor. t: type: string description: >- The factor CRT coefficient of the corresponding prime factor. iv: type: string description: >- The base64url-encoded representation of the 96-bit Initialization Vector value used for the AES GCM key encryption operation. tag: type: string description: >- The base64url-encoded representation of the 128-bit Authentication Tag value resulting from the AES GCM key encryption operation. k: type: string description: >- The key value of the symmetric (or other single-valued) key. enc: type: string description: The encryption algorithm for JWE. epk: type: object description: >- The ephemeral public key value created by the originator for use in ECDH-ES key agreement algorithms. apu: type: string description: >- The agreement PartyUInfo for ECDH-ES key agreement algorithms, containing information about the producer. apv: type: string description: >- The agreement PartyVInfo for ECDH-ES key agreement algorithms. JWKInline: required: - type - keys type: object properties: type: type: string enum: - INLINE keys: type: array description: | The JSON Web Keys. items: $ref: '#/components/schemas/JWK' example: - k: ZmFudGFzdGljand0 kty: oct kid: 1 description: | Inline contents of a JWK JSON file. JWKRemoteFile: required: - uri - type type: object properties: type: type: string enum: - REMOTE_FILE uri: type: string cacheExpire: pattern: '^[0-9]+[h|m|s]{1}$' type: string description: > The length of time for which to cache the remote file. NGINX will retrieve the file from the source URI when the cache time expires. example: 10h IdentityProviderAPIKey: required: - type type: object properties: type: type: string enum: - API_KEY apiKey: type: string description: > If left empty, a key will automatically be generated. The apikey must contain only alphanumeric characters, underscores, and hyphens. The length of the apikey must be between 8 - 256 characters. example: ADv-2ZheQnL_jVx5klhQ39 SelfLinks: type: object description: > The SelfLinks object contains a link from the resource to itself. This object is used only in responses. properties: rel: type: string example: /api/v1/services/environments/prod description: > `rel` contains the complete path fragment of a URI and can be used to construct a query to the object. ResourceMeta: type: object required: - name properties: name: type: string pattern: >- ^[^A-Z\s\x00-\x1f\x60\x7f\;\*\"\[\]\{\}\\\/%\?:=&\~\^|#<>]+$ minLength: 1 maxLength: 1024 example: resource-name description: > Resource name is a unique identifier for a resource within the context of a namespace. Resource names must conform to [RFC 1738 Section 2.2](https://www.ietf.org/rfc/rfc1738.txt) and have a valid syntax for email addresses. The following rules are enforced: - do not utilize URL encoding; - do not include spaces; - do not use uppercase characters, for example, 'A-Z'; extended character sets are supported; - do not use the following characters: `"`, `*`, `:`, `;`, `/`, `\`, `%`, `?`, `hash`, `=`, `&`, `|`, `~`, `^`, `{`, `}`, `[`, `]`, `<`, `>`; - cannot start or end with an `@` sign; For example: For a collection resource located at `https://controller.example.com/api/v1/services/apps/shopping_@1` the resource name is "shopping_@1". displayName: type: string example: My Display Name description: > `displayName` is a user friendly resource name. It can be used to define a longer, and less constrained, name for a resource. Display names: - are optional (defaults to an empty string if no value is provided), - do not have to be unique, - cannot be assigned by the server. description: type: string example: >- This is a sample description string. It provides information about the resource. description: > `description` is a free-form text property. You can use it to provide information that helps to identify the resource. Descriptions: - are optional (defaults to an empty string if no value is provided), - do not have to be unique, - cannot be assigned by the server. kind: type: string example: - description: > Kind is a string representation of an API resource's data type. It is assigned by the server and cannot be changed. When creating a `kind`, the server uses hyphens to connect word segments; singleton and collection item resources are not pluralized. uid: type: string format: uuid example: d290f1ee-6c54-4b01-90e6-d701748f0851 description: > Unique Identifier (UID) UID is a unique identifier in time and space for a resource. When you create a resource, the server assigns a UID to the resource. Refer to [IETF RFC 4122](https://tools.ietf.org/html/rfc4122) for more information. tags: type: array items: type: string example: - production_public - dev - new_app - us-west-1 - emea description: > You can assign `tags` to a resource as a way to help map, scope, and organize resources. The system uses tag selectors to specify selection criteria that match resources that have particular tags. ref: type: string example: /services/environments/prod description: > The `ref` field contains a reference to another NGINX Controller resource. links: $ref: '#/components/schemas/SelfLinks' createTime: type: string format: date-time example: '2019-07-29T09:12:33.001Z' description: > A timestamp that represents the server time when the resource was created. Create time is not guaranteed to be set in "happens-before" order across separate operations. In JSON format, `create_time` type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt). For example: 2018-04-01T01:30:15.01Z Create Time is assigned by the server and cannot be changed. updateTime: type: string format: date-time example: '2019-07-29T10:12:33.001Z' description: > A timestamp that represents the server time when the resource was last modified. Resources that have never been updated do not have an `update_time` stamp. The default value for resources that have never been updated is the local language-specific equivalent of "null". In JSON format, `update_time` type is encoded as a string as described in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt). NamedLinks: allOf: - $ref: '#/components/schemas/SelfLinks' - type: object description: > Contains information about the object being referred to. These are generally details -- like the object name and display name -- that are useful to a consumer of the API that performs further processing. This object is only present in responses. properties: name: type: string example: production description: | The name of the linked resource. displayName: type: string example: Production Environment description: A user friendly resource name. ResourceRef: type: object required: - ref properties: ref: type: string example: /services/environments/prod description: | A reference to another NGINX Controller resource. links: $ref: '#/components/schemas/NamedLinks' ConfigStateTally: type: object properties: isConfigured: type: boolean description: The configuration operation is complete. isConfiguring: type: boolean description: >- The configuration of the resource, or of its child(ren), is in process. isError: type: boolean description: >- An error occurred while configuring the resource or its child(ren). isDeleting: type: boolean description: >- A delete operation is in progress for the resource or its child(ren). total: type: integer description: >- The total number of resources to which the configuration operation applies. configured: type: integer description: >- The number of resources that have a complete and valid configuration. configuring: type: integer description: >- The number of resources that are in the process of being configured. error: type: integer description: >- The number of resources that have encountered an error during the configuration process. deleting: type: integer description: >- The number of resources that are in the process of being deleted. ConfigCondition: type: object properties: type: type: string description: The condition type. message: type: string description: >- A human-readable message that provides additional information about the configuration operation. ConfigState: type: object description: > A representation of the resource's current configuration state that comprises the status of the resource itself (`selfConfigState`) and any child resources (`childrenConfigState`). The conditions array provides additional information during configuration changes. properties: selfConfigState: $ref: '#/components/schemas/ConfigStateTally' childrenConfigState: $ref: '#/components/schemas/ConfigStateTally' conditions: type: array items: $ref: '#/components/schemas/ConfigCondition' ErrorDetail: type: object required: - description properties: description: type: string example: >- Error doing : . This can lead to . Try to resolve the issue. description: > A detailed error message returned by the server. These messages contain the following information, where applicable: - What happened. - Why it happened. - What the consequences are (if any). - Recommended action to take to resolve the issue. ErrorModel: type: object required: - message - code properties: message: type: string example: Error doing . description: > A human-readable message, in English, that describes the error. code: type: integer example: 1234567 description: > A numeric error code that can be used to identify errors for support purposes. details: type: array items: $ref: '#/components/schemas/ErrorDetail' parameters: identityProviderName: name: identityProviderName in: path description: The name of the Identity Provider. required: true style: simple explode: false schema: type: string identityProviderClientName: name: identityProviderClientName in: path description: The name of the Identity Provider Client. required: true style: simple explode: false schema: type: string examples: IdentityProviderRequest: value: metadata: name: resource-name displayName: My Display Name description: >- This is a sample description string. It provides information about the resource. tags: - production_public - dev - new_app - us-west-1 - emea desiredState: environmentRefs: - ref: /services/environments/dev identityProvider: type: API_KEY IdentityProviderClientListRequest: value: items: - metadata: name: resource-name displayName: My Display Name description: >- This is a sample description string. It provides information about the resource. tags: - production_public - dev - new_app - us-west-1 - emea desiredState: credential: type: API_KEY apiKey: ADv2ZheQnLjVx5klhQ39 IdentityProviderClientRequest: value: metadata: name: resource-name displayName: My Display Name description: >- This is a sample description string. It provides information about the resource. tags: - production_public - dev - new_app - us-west-1 - emea desiredState: credential: type: API_KEY apiKey: ADv2ZheQnLjVx5klhQ39 IdentityProviderClientPatchMetadataRequest: value: metadata: name: resource-name description: >- This is a sample description string. It provides information about the resource. IdentityProviderClientPatchDesiredStateRequest: value: desiredState: credential: type: API_KEY apiKey: ADv2ZheQnLjVx5klhQ39