openapi: 3.0.1 info: title: IAM Firewall API Specification description: This specification describes the endpoints of the IAM Firewall Service. version: 0-SNAPSHOT servers: - url: http://localhost description: local development host tags: - name: IAM Console - Application Firewall description: Management functions for application firewall configurations in IAM Console paths: /firewall/v1/applications/{application-expression}/firewall-rules: get: tags: - IAM Console - Application Firewall summary: Get application firewall rules description: Read application firewall rules by application expression operationId: getApplicationFirewallRules parameters: - $ref: "#/components/parameters/application-expression" responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/ApplicationFirewallRuleV1" application/x-ndjson: schema: type: array items: $ref: "#/components/schemas/ApplicationFirewallRuleV1" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" security: - iam-console-token: [] put: tags: - IAM Console - Application Firewall summary: Upsert application firewall rules description: Create or replace a application firewall rules for an application operationId: upsertApplicationFirewallRules parameters: - $ref: "#/components/parameters/application-expression" - $ref: "#/components/parameters/returnUpdated" requestBody: content: application/json: schema: type: array items: $ref: "#/components/schemas/ApplicationFirewallRuleInV1" application/x-ndjson: schema: type: array items: $ref: "#/components/schemas/ApplicationFirewallRuleInV1" responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/ApplicationFirewallRuleV1" application/x-ndjson: schema: type: array items: $ref: "#/components/schemas/ApplicationFirewallRuleV1" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" security: - iam-console-token: [] delete: tags: - IAM Console - Application Firewall summary: Delete application firewall rules description: Removes application firewall rules by application expression operationId: deleteApplicationFirewallRules parameters: - $ref: "#/components/parameters/application-expression" responses: "204": description: The request is processed and no content was returned "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" security: - iam-console-token: [] /firewall/v1/applications/{application-expression}/firewall-rules/{application-firewall-rule-key}: get: tags: - IAM Console - Application Firewall summary: Get application firewall rule description: Read application firewall rule by its application expression and application firewall rule key operationId: getApplicationFirewallRule parameters: - $ref: "#/components/parameters/application-expression" - $ref: "#/components/parameters/application-firewall-rule-key" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ApplicationFirewallRuleV1" application/x-ndjson: schema: $ref: "#/components/schemas/ApplicationFirewallRuleV1" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" security: - iam-console-token: [] put: tags: - IAM Console - Application Firewall summary: Upsert application firewall rule description: Create or replace an application firewall rule by its application expression and application firewall rule key operationId: upsertApplicationFirewallRule parameters: - $ref: "#/components/parameters/application-expression" - $ref: "#/components/parameters/application-firewall-rule-key" - $ref: "#/components/parameters/returnUpdated" requestBody: content: application/json: schema: $ref: "#/components/schemas/ApplicationFirewallRuleInWithoutKeyV1" required: true responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ApplicationFirewallRuleV1" "204": $ref: "#/components/responses/NoContent" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" security: - iam-console-token: [] delete: tags: - IAM Console - Application Firewall summary: Delete application firewall rule description: Removes an application firewall rule by application expression and application firewall rule key operationId: deleteApplicationFirewallRule parameters: - $ref: "#/components/parameters/application-expression" - $ref: "#/components/parameters/application-firewall-rule-key" responses: "204": description: The request is processed and no content was returned "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" security: - iam-console-token: [] components: schemas: ApplicationFirewallAuthorizedRoleInV1: required: - key type: object properties: key: maxLength: 64 minLength: 1 pattern: "^[a-zA-Z0-9-_.]{1,64}$" type: string description: "The identifier of a role, also know as 'roleKey'" example: ADMINISTRATOR description: An authorized role that is allowed passage ApplicationFirewallAuthorizedRoleV1: required: - key type: object properties: key: type: string description: "The identifier of a role, also know as 'roleKey'" example: ADMINISTRATOR description: An authorized role that is allowed passage ApplicationFirewallRuleInV1: required: - key - status type: object properties: key: maxLength: 64 minLength: 1 pattern: "^[a-zA-Z0-9-_.]{1,64}$" type: string description: An application firewall rule identifier example: firewall-rule-1 name: maxLength: 64 type: string description: "A name, usually for an entity" example: John Doe description: maxLength: 4096 type: string description: "A description, usually for an entity" example: "Lorem ipsum dolor sit amet, consectetur adipiscing elit." status: type: string description: The initial status of this rule enum: - ENABLED - DISABLED authorizationKeys: maxItems: 5 minItems: 0 type: array description: Details allowed firewall authorization keys that may be used to pass the firewall items: maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\\ b-[0-9a-fA-F]{12}$" type: string description: An application firewall authorization key that may be passed via the firewall security header 'APPLICATION-FIREWALL-KEY' to allow passage. example: bb1b93ae-5e47-4dbc-ad74-8e684b33c0cc authorizedRoles: maxItems: 100 minItems: 0 type: array description: Eligible roles that will allow passage items: $ref: "#/components/schemas/ApplicationFirewallAuthorizedRoleInV1" unprotectedServices: maxItems: 100 minItems: 0 type: array description: Details which services and their respective permissions that may be called without any firewall restriction items: $ref: "#/components/schemas/ApplicationFirewallUnprotectedServiceInV1" description: Defines a firewall rule for an application. If no match could be made for a permission then the rule will DENY the request. Regular access checks still apply when checking if the caller is allowed to call respective endpoint/permission. ApplicationFirewallRuleInWithoutKeyV1: required: - status type: object properties: name: maxLength: 64 type: string description: "A name, usually for an entity" example: John Doe description: maxLength: 4096 type: string description: "A description, usually for an entity" example: "Lorem ipsum dolor sit amet, consectetur adipiscing elit." status: type: string description: The initial status of this rule enum: - ENABLED - DISABLED authorizationKeys: maxItems: 5 minItems: 0 type: array description: Details allowed firewall authorization keys that may be used to pass the firewall items: maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\\ b-[0-9a-fA-F]{12}$" type: string description: An application firewall authorization key that may be passed via the firewall security header 'APPLICATION-FIREWALL-KEY' to allow passage. example: bb1b93ae-5e47-4dbc-ad74-8e684b33c0cc authorizedRoles: maxItems: 100 minItems: 0 type: array description: Eligible roles that will allow passage items: $ref: "#/components/schemas/ApplicationFirewallAuthorizedRoleInV1" unprotectedServices: maxItems: 100 minItems: 0 type: array description: Details which services and their respective permissions that may be called without any firewall restriction items: $ref: "#/components/schemas/ApplicationFirewallUnprotectedServiceInV1" description: Defines a firewall rule for an application. If no match could be made for a permission then the rule will DENY the request. Regular access checks still apply when checking if the caller is allowed to call respective endpoint/permission. ApplicationFirewallRuleV1: required: - applicationId - changeId - createdAt - createdBy - key - lastModifiedAt - lastModifiedBy - status type: object properties: applicationId: type: string description: The globally unique identifier for an application example: demo-app-6825aa29225146801209ca85 key: type: string description: An application firewall rule identifier name: type: string description: "A name, usually for an entity" example: John Doe description: type: string description: "A description, usually for an entity" example: "Lorem ipsum dolor sit amet, consectetur adipiscing elit." status: type: string description: Declares if this rule is enforced or not authorizationKeys: type: array description: Details allowed firewall authorization keys that may be used to pass the firewall items: type: string description: An application firewall authorization key that may be passed via the firewall security header 'APPLICATION-FIREWALL-KEY' to allow passage. authorizedRoles: type: array description: Eligible roles that will allow passage items: $ref: "#/components/schemas/ApplicationFirewallAuthorizedRoleV1" unprotectedServices: type: array description: Details which services and their respective permissions that may be called without any firewall restriction items: $ref: "#/components/schemas/ApplicationFirewallUnprotectedServiceV1" createdAt: type: string description: UTC date time when entity was created. This string is formatted according to RFC3339. format: date-time createdBy: type: string description: The globally unique identifier for an actor example: user-6825a22e225146801209c9fe lastModifiedAt: type: string description: UTC date time when entity was modified. This string is formatted according to RFC3339. format: date-time lastModifiedBy: type: string description: The globally unique identifier for an actor example: user-6825a22e225146801209c9fe changeId: type: string description: Text representation of changeId sequence number example: "7380283282446876762" description: Defines a firewall rule for an application. If no match could be made for a permission then the rule will DENY the request. Regular access checks still apply when checking if the caller is allowed to call respective endpoint/permission. ApplicationFirewallUnprotectedServiceInV1: required: - serviceDefinitionKey - serviceDefinitionSource type: object properties: serviceDefinitionSource: type: string description: The service definition source describes the origin of the definition enum: - APPLICATION - CATALOG serviceDefinitionKey: maxLength: 64 minLength: 1 pattern: "^[a-zA-Z0-9-_.]{1,64}$" type: string description: Identifies a service definition by its key example: exercise-tracking-service unprotectedPermissions: maxItems: 100 minItems: 0 type: array description: An array of permissions that will be ignored by the firewall for the given service. If the list is empty/null then all permissions are unprotected by the firewall items: maxLength: 64 minLength: 1 pattern: "^[a-zA-Z0-9-_.]{1,64}$" type: string description: Identifies a permission definition by its key for a service example: read description: Details which services that may be called for a given service without or partial firewall restriction ApplicationFirewallUnprotectedServiceV1: required: - serviceDefinitionKey - serviceDefinitionSource type: object properties: serviceDefinitionSource: type: string description: The service definition source describes the origin of the definition serviceDefinitionKey: type: string description: Identifies a service definition by its key unprotectedPermissions: type: array description: An array of permissions that will be ignored by the firewall for the given service. If the list is empty/null then all permissions are unprotected by the firewall items: type: string description: Identifies a permission definition by its key for a service description: Details which services that may be called for a given service without or partial firewall restriction ErrorDetailV1: type: object properties: field: type: string description: A reference to a field or parameter which cannot be processed. value: type: string description: The value which could not be processed. message: type: string description: A human readable message of error. Intended for developers. description: 'Additional information about the error ' ErrorV1: required: - errorId - occurredAt type: object properties: errorId: type: string description: "An error identifier for the request, to be provided in troubleshooting." code: type: string description: |- An error code which describes this error. Documented per service and endpoint. See respective ErrorCodeRegistry DTO for possible error codes. message: type: string description: A human readable message of error. Intended for developers. details: type: array description: Additional information about the error which can be used in troubleshooting. items: $ref: "#/components/schemas/ErrorDetailV1" occurredAt: type: string description: The timestamp when the error occurred. This string is formatted according to RFC3339. format: date-time IamFirewallErrorCodeRegistryV1: type: object properties: upsertApplicationFirewallRules: type: string enum: - INPUT_MALFORMED - AUTHENTICATION_FAILED - AUTHENTICATION_EXPIRED - AUTHENTICATION_REVOKED - AUTHENTICATION_INVALID_APPLICATION - AUTHORIZATION_MISSING_PERMISSION - IAM_APPLICATION_NOT_FOUND - IAM_FIREWALL_AUTH_KEY_LIMIT_EXCEEDED - IAM_ROLE_NOT_FOUND - IAM_SERVICE_NOT_FOUND - IAM_SERVICE_PERMISSION_NOT_FOUND upsertApplicationFirewallRule: type: string enum: - INPUT_MALFORMED - AUTHENTICATION_FAILED - AUTHENTICATION_EXPIRED - AUTHENTICATION_REVOKED - AUTHENTICATION_INVALID_APPLICATION - AUTHORIZATION_MISSING_PERMISSION - IAM_APPLICATION_NOT_FOUND - IAM_FIREWALL_AUTH_KEY_LIMIT_EXCEEDED - IAM_ROLE_NOT_FOUND - IAM_SERVICE_NOT_FOUND - IAM_SERVICE_PERMISSION_NOT_FOUND getApplicationFirewallRule: type: string enum: - INPUT_MALFORMED - AUTHENTICATION_FAILED - AUTHENTICATION_EXPIRED - AUTHENTICATION_REVOKED - AUTHENTICATION_INVALID_APPLICATION - AUTHORIZATION_MISSING_PERMISSION - IAM_APPLICATION_NOT_FOUND - IAM_FIREWALL_RULE_NOT_FOUND getApplicationFirewallRules: type: string enum: - INPUT_MALFORMED - AUTHENTICATION_FAILED - AUTHENTICATION_EXPIRED - AUTHENTICATION_REVOKED - AUTHENTICATION_INVALID_APPLICATION - AUTHORIZATION_MISSING_PERMISSION - IAM_APPLICATION_NOT_FOUND deleteApplicationFirewallRule: type: string enum: - INPUT_MALFORMED - AUTHENTICATION_FAILED - AUTHENTICATION_EXPIRED - AUTHENTICATION_REVOKED - AUTHENTICATION_INVALID_APPLICATION - AUTHORIZATION_MISSING_PERMISSION - IAM_APPLICATION_NOT_FOUND deleteApplicationFirewallRules: type: string enum: - INPUT_MALFORMED - AUTHENTICATION_FAILED - AUTHENTICATION_EXPIRED - AUTHENTICATION_REVOKED - AUTHENTICATION_INVALID_APPLICATION - AUTHORIZATION_MISSING_PERMISSION - IAM_APPLICATION_NOT_FOUND description: |- This entry describes possible error codes that may be returned by their respective operation. These can be used to apply logic upon receiving an error response. responses: NoContent: description: The request is processed and no content was returned BadRequest: description: "The request is malformed, see error data for additional information" content: application/json: schema: $ref: "#/components/schemas/ErrorV1" Unauthorized: description: The request did not have valid authentication credentials content: application/json: schema: $ref: "#/components/schemas/ErrorV1" Forbidden: description: The requester is not authorized to perform this action content: application/json: schema: $ref: "#/components/schemas/ErrorV1" NotFound: description: The resource could not be found content: application/json: schema: $ref: "#/components/schemas/ErrorV1" Conflict: description: "The request could not be processed due to a conflict in state,\ \ see error data for additional information" content: application/json: schema: $ref: "#/components/schemas/ErrorV1" parameters: application-expression: name: application-expression in: path required: true schema: pattern: "^[a-zA-Z0-9-_.]{1,64}$" type: string description: "Used to identify a specific applicationId. The available options\ \ are: \n* '{applicationId}' - direct applicationId reference" application-firewall-rule-key: name: application-firewall-rule-key in: path required: true schema: type: string description: An application firewall rule identifier returnUpdated: name: returnUpdated in: query description: To return the entity after successful update or not schema: type: boolean default: false securitySchemes: iam-console-token: type: http scheme: bearer bearerFormat: IAM issued jwt token for the IAM console application