From b7eed5a1b07d6b5f72a9613f85394ccf719079b3 Mon Sep 17 00:00:00 2001 From: malithie Date: Mon, 2 Dec 2024 16:25:50 +0530 Subject: [PATCH] Add api docs for rule metadata. --- .../docs/apis/restapis/rule-metadata.yaml | 369 +++++++++++++++++ .../docs/apis/rule-metadata-rest-api.md | 5 + en/asgardeo/mkdocs.yml | 1 + .../docs/apis/restapis/rule-metadata.yaml | 378 ++++++++++++++++++ .../next/docs/apis/rule-metadata-rest-api.md | 5 + en/identity-server/next/mkdocs.yml | 1 + 6 files changed, 759 insertions(+) create mode 100644 en/asgardeo/docs/apis/restapis/rule-metadata.yaml create mode 100644 en/asgardeo/docs/apis/rule-metadata-rest-api.md create mode 100644 en/identity-server/next/docs/apis/restapis/rule-metadata.yaml create mode 100644 en/identity-server/next/docs/apis/rule-metadata-rest-api.md diff --git a/en/asgardeo/docs/apis/restapis/rule-metadata.yaml b/en/asgardeo/docs/apis/restapis/rule-metadata.yaml new file mode 100644 index 0000000000..665cad186b --- /dev/null +++ b/en/asgardeo/docs/apis/restapis/rule-metadata.yaml @@ -0,0 +1,369 @@ +openapi: 3.0.1 +info: + title: Asgardeo Rule Metadata REST API + description: "The Rule Metadata API provides the essential metadata required to configure rules dynamically based on the flow context. \nThe metadata retrieved by this API is designed to support rule configuration in the user interface (UI) by delivering information about each configurable field, the set of applicable comparison operators (e.g., equals, contains) for each field, and lists of possible values or options for fields.\n" + contact: + name: WSO2 + url: https://wso2.com/identity-and-access-management/ + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: v1 +servers: + - url: 'https://api.asgardeo.io/t/{organization-name}/api/server/v1' +security: +- OAuth2: [] +paths: + /rules/metadata: + get: + tags: + - Metadata + summary: Get metadata for rule configuration. + description: |+ + This API provides a list of fields, associated metadata, and applicable operators for each field based on the specified flow type. This information is used to populate the UI for rule configuration. + + Scope (Permission) required: ``internal_rule_metadata_view`` + + operationId: getExpressionMeta + parameters: + - name: flow + in: query + description: | + Specifies the flow to retrieve rule metadata. This ensures that the metadata returned is relevant to the given flow. + + Note: At present, only the 'preIssueAccessToken' flow is supported. + required: true + style: form + explode: true + schema: + type: string + enum: + - preIssueAccessToken + - prePasswordUpdate + - preProfileUpdate + - preLogin + - postLogin + - inLogin + - preRegistration + - inRegistration + - inPasswordExpiry + responses: + "200": + description: Applicable fields and operators + content: + application/json: + schema: + $ref: '#/components/schemas/ExpressionMeta' + examples: + preIssueAccessToken: + summary: Sample response for pre-issue access token flow + value: + - field: + name: application + displayName: application + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: reference + valueReferenceAttribute: id + valueDisplayAttribute: name + links: + - href: /applications?offset=0&limit=10 + method: GET + rel: values + - href: /applications?filter=name+eq+*&limit=10 + method: GET + rel: filter + - field: + name: grantType + displayName: grant type + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: string + values: + - name: authorization_code + displayName: authorization code + - name: password + displayName: password + - name: refresh_token + displayName: refresh token + - name: client_credentials + displayName: client credentials + - name: urn:ietf:params:oauth:grant-type:token-exchange + displayName: token exchange + prePasswordUpdate: + summary: Sample response for pre-password update flow + value: + - field: + name: initiator + displayName: initiator + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: string + values: + - name: user + displayName: user + - name: admin + displayName: admin + - name: application + displayName: application + - field: + name: flow + displayName: flow + dependentFileds: + - initiator + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: string + values: + - name: reset + displayName: reset + - name: update + displayName: update + inLogin: + summary: Sample response for login flow + value: + - field: + name: role + displayName: user.role + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: reference + valueReferenceAttribute: id + valueDisplayAttribute: name + links: + - href: /scim2/Roles?offset=0&limit=10 + method: GET + rel: values + - href: /scim2/Roles?filter=name+eq+*&limit=10 + method: GET + rel: filter + - field: + name: group + displayName: user.group + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: reference + valueReferenceAttribute: id + valueDisplayAttribute: name + links: + - href: /scim2/Groups?offset=0&limit=10 + method: GET + rel: values + - href: /scim2/Groups?filter=name+eq+*&limit=10 + method: GET + rel: filter + - field: + name: email + displayName: user.email + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + - name: startsWith + displayName: starts with + - name: endsWith + displayName: ends with + - name: contains + displayName: contains + value: + inputType: input + valueType: string + "400": + description: Bad Request + "401": + description: Unauthorized + "500": + description: Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codeSamples: + - lang: Curl + source: | + curl --location 'https://api.asgardeo.io/t/{organization-name}/api/server/v1/rules/metadata?flow=preIssueAccessToken' \ + --header 'Authorization: Bearer {bearer_token}' +components: + schemas: + ExpressionMeta: + type: array + description: Represents the metadata for rule expressions. It includes field definitions and associated operators. + items: + $ref: '#/components/schemas/FieldDefinition' + FieldDefinition: + type: object + properties: + field: + $ref: '#/components/schemas/Field' + operators: + type: array + description: | + Specifies the list of valid operators that can be applied to this field in rule expressions. Each operator defines a comparison or matching condition (e.g., \"equals\", \"contains\", \"greaterThan\") that determines how the field's value will be evaluated within a rule. + items: + $ref: '#/components/schemas/Operator' + value: + $ref: '#/components/schemas/Value' + Field: + type: object + properties: + name: + type: string + description: Name of the field. This is an immutable attribute and uniquely identifies the field allowed in the rule. + example: role + displayName: + type: string + description: Display name of the field. Use as a user friendly label of the field to show in UI. + example: user.role + dependantFields: + type: array + description: Lists the names of fields on which this field depends for its display or selection in the next expression. + example: [] + items: + type: string + Value: + type: object + properties: + inputType: + type: string + description: | + Defines how the field should be presented and populated in the rule configuration UI. This property indicates whether the field allows direct user input or if the values are selected from predefined options. Possible types include: + + - "input": Allows for direct user entry, such as text or numeric input. + - "options": Provides a list of selectable values, often fetched from an external data source, enabling users to pick from predefined choices. + enum: + - input + - options + valueType: + type: string + description: | + Specifies the expected data type for the field’s value within a rule expression. This property defines how the field's value should be interpreted when used in rule conditions. Possible types include: + - "string": Text value. + - "number": Numerical value. + - "boolean": True or false. + - "date": Date value. + - "reference": A reference to an external identifier, often used with options-type fields to indicate that the value is an ID or a unique attribute from related data." + enum: + - string + - number + - boolean + - date + - reference + valueReferenceAttribute: + type: string + description: "The key attribute in the options data (e.g., 'id') used to represent the option's selected value in rule expressions. Only available when 'valueType' is 'reference'." + example: id + valueDisplayAttribute: + type: string + description: "The attribute to show as the label for each option in the dropdown (e.g., 'name') when listing options. Only available when 'valueType' is 'reference'." + example: name + links: + type: array + description: Endpoints to retrieve or search for options dynamically. Included only when 'valueType' is 'reference'. + example: + - href: /scim2/roles?offset=0&limit=10 + method: GET + rel: values + - href: /scim2/roles/.search + method: GET + rel: filter + items: + $ref: '#/components/schemas/Link' + values: + type: array + description: "List of selectable values for options fields when 'valueType' is 'string', 'number', 'boolean', or 'date'." + items: + $ref: '#/components/schemas/ValueObject' + Operator: + type: object + properties: + name: + type: string + description: Name of the operator. The immutable identifier of the operator referenced within the rule expression. + displayName: + type: string + description: Display name of the operator. Use as a user friendly label of the operator to show in UI. + ValueObject: + type: object + properties: + name: + type: string + description: The name that uniquely identifies the option. + displayName: + type: string + description: The display name for the option. + Link: + type: object + properties: + href: + type: string + description: Url of the endpoint. + method: + type: string + description: Http method. + enum: + - GET + rel: + type: string + description: Indicates the endpoint’s relation to retrieving or filtering field values. + enum: + - values + - filter + Error: + type: object + properties: + code: + type: string + description: Error code + example: RMS-00000 + message: + type: string + description: Error message. + example: Some error message. + description: + type: string + description: Detailed error description. + example: Some error description. + traceId: + type: string + description: Trace identifier to refer at troubleshooting logs to troubleshoot the problem. + example: e0fbcfeb-3617-43c4-8dd0-7b7d38e13047 + securitySchemes: + OAuth2: + type: oauth2 + flows: + authorizationCode: + authorizationUrl: 'https://api.asgardeo.io/t/{org-name}/oauth2/authorize' + tokenUrl: 'https://api.asgardeo.io/t/{org-name}/oauth2/token' + scopes: + read: internal_rule_metadata_view diff --git a/en/asgardeo/docs/apis/rule-metadata-rest-api.md b/en/asgardeo/docs/apis/rule-metadata-rest-api.md new file mode 100644 index 0000000000..3ead0563dd --- /dev/null +++ b/en/asgardeo/docs/apis/rule-metadata-rest-api.md @@ -0,0 +1,5 @@ +--- +template: templates/redoc.html +--- + + \ No newline at end of file diff --git a/en/asgardeo/mkdocs.yml b/en/asgardeo/mkdocs.yml index 845eda7e4a..b67603c44a 100644 --- a/en/asgardeo/mkdocs.yml +++ b/en/asgardeo/mkdocs.yml @@ -409,6 +409,7 @@ nav: - Organization management API: apis/organization-management.md - Password expiring users identification API: apis/password-expiring-users-identification.md - Role management (SCIM 2.0) API: apis/roles.md + - Rule Metadata API: apis/rule-metadata-rest-api.md - User management: - SCIM 2.0 API: - SCIM 2.0 API: apis/scim2/index.md diff --git a/en/identity-server/next/docs/apis/restapis/rule-metadata.yaml b/en/identity-server/next/docs/apis/restapis/rule-metadata.yaml new file mode 100644 index 0000000000..2fc73a4665 --- /dev/null +++ b/en/identity-server/next/docs/apis/restapis/rule-metadata.yaml @@ -0,0 +1,378 @@ +openapi: 3.0.1 +info: + title: WSO2 Identity Server Rule Metadata REST API + description: "The Rule Metadata API provides the essential metadata required to configure rules dynamically based on the flow context. \nThe metadata retrieved by this API is designed to support rule configuration in the user interface (UI) by delivering information about each configurable field, the set of applicable comparison operators (e.g., equals, contains) for each field, and lists of possible values or options for fields.\n" + contact: + name: WSO2 + url: https://wso2.com/identity-and-access-management/ + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: v1 +servers: +- url: "https://{server-url}/t/{tenant-domain}/api/server/v1" + variables: + tenant-domain: + default: carbon.super + server-url: + default: localhost:9443 +security: +- OAuth2: [] +- BasicAuth: [] +paths: + /rules/metadata: + get: + tags: + - Metadata + summary: Get metadata for rule configuration. + description: |+ + This API provides a list of fields, associated metadata, and applicable operators for each field based on the specified flow type. This information is used to populate the UI for rule configuration. + + Scope (Permission) required: ``internal_rule_metadata_view`` + + operationId: getExpressionMeta + parameters: + - name: flow + in: query + description: | + Specifies the flow to retrieve rule metadata. This ensures that the metadata returned is relevant to the given flow. + + Note: At present, only the 'preIssueAccessToken' flow is supported. + required: true + style: form + explode: true + schema: + type: string + enum: + - preIssueAccessToken + - prePasswordUpdate + - preProfileUpdate + - preLogin + - postLogin + - inLogin + - preRegistration + - inRegistration + - inPasswordExpiry + responses: + "200": + description: Applicable fields and operators + content: + application/json: + schema: + $ref: '#/components/schemas/ExpressionMeta' + examples: + preIssueAccessToken: + summary: Sample response for pre-issue access token flow + value: + - field: + name: application + displayName: application + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: reference + valueReferenceAttribute: id + valueDisplayAttribute: name + links: + - href: /applications?offset=0&limit=10 + method: GET + rel: values + - href: /applications?filter=name+eq+*&limit=10 + method: GET + rel: filter + - field: + name: grantType + displayName: grant type + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: string + values: + - name: authorization_code + displayName: authorization code + - name: password + displayName: password + - name: refresh_token + displayName: refresh token + - name: client_credentials + displayName: client credentials + - name: urn:ietf:params:oauth:grant-type:token-exchange + displayName: token exchange + prePasswordUpdate: + summary: Sample response for pre-password update flow + value: + - field: + name: initiator + displayName: initiator + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: string + values: + - name: user + displayName: user + - name: admin + displayName: admin + - name: application + displayName: application + - field: + name: flow + displayName: flow + dependentFileds: + - initiator + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: string + values: + - name: reset + displayName: reset + - name: update + displayName: update + inLogin: + summary: Sample response for login flow + value: + - field: + name: role + displayName: user.role + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: reference + valueReferenceAttribute: id + valueDisplayAttribute: name + links: + - href: /scim2/Roles?offset=0&limit=10 + method: GET + rel: values + - href: /scim2/Roles?filter=name+eq+*&limit=10 + method: GET + rel: filter + - field: + name: group + displayName: user.group + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: reference + valueReferenceAttribute: id + valueDisplayAttribute: name + links: + - href: /scim2/Groups?offset=0&limit=10 + method: GET + rel: values + - href: /scim2/Groups?filter=name+eq+*&limit=10 + method: GET + rel: filter + - field: + name: email + displayName: user.email + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + - name: startsWith + displayName: starts with + - name: endsWith + displayName: ends with + - name: contains + displayName: contains + value: + inputType: input + valueType: string + "400": + description: Bad Request + "401": + description: Unauthorized + "500": + description: Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codeSamples: + - lang: Curl + source: | + curl --location 'https://localhost:9443/api/server/v1/rules/metadata?flow=preIssueAccessToken' \ + --header 'Authorization: Basic YWRtaW46YWRtaW4=' +components: + schemas: + ExpressionMeta: + type: array + description: Represents the metadata for rule expressions. It includes field definitions and associated operators. + items: + $ref: '#/components/schemas/FieldDefinition' + FieldDefinition: + type: object + properties: + field: + $ref: '#/components/schemas/Field' + operators: + type: array + description: | + Specifies the list of valid operators that can be applied to this field in rule expressions. Each operator defines a comparison or matching condition (e.g., \"equals\", \"contains\", \"greaterThan\") that determines how the field's value will be evaluated within a rule. + items: + $ref: '#/components/schemas/Operator' + value: + $ref: '#/components/schemas/Value' + Field: + type: object + properties: + name: + type: string + description: Name of the field. This is an immutable attribute and uniquely identifies the field allowed in the rule. + example: role + displayName: + type: string + description: Display name of the field. Use as a user friendly label of the field to show in UI. + example: user.role + dependantFields: + type: array + description: Lists the names of fields on which this field depends for its display or selection in the next expression. + example: [] + items: + type: string + Value: + type: object + properties: + inputType: + type: string + description: | + Defines how the field should be presented and populated in the rule configuration UI. This property indicates whether the field allows direct user input or if the values are selected from predefined options. Possible types include: + + - "input": Allows for direct user entry, such as text or numeric input. + - "options": Provides a list of selectable values, often fetched from an external data source, enabling users to pick from predefined choices. + enum: + - input + - options + valueType: + type: string + description: | + Specifies the expected data type for the field’s value within a rule expression. This property defines how the field's value should be interpreted when used in rule conditions. Possible types include: + - "string": Text value. + - "number": Numerical value. + - "boolean": True or false. + - "date": Date value. + - "reference": A reference to an external identifier, often used with options-type fields to indicate that the value is an ID or a unique attribute from related data." + enum: + - string + - number + - boolean + - date + - reference + valueReferenceAttribute: + type: string + description: "The key attribute in the options data (e.g., 'id') used to represent the option's selected value in rule expressions. Only available when 'valueType' is 'reference'." + example: id + valueDisplayAttribute: + type: string + description: "The attribute to show as the label for each option in the dropdown (e.g., 'name') when listing options. Only available when 'valueType' is 'reference'." + example: name + links: + type: array + description: Endpoints to retrieve or search for options dynamically. Included only when 'valueType' is 'reference'. + example: + - href: /scim2/roles?offset=0&limit=10 + method: GET + rel: values + - href: /scim2/roles/.search + method: GET + rel: filter + items: + $ref: '#/components/schemas/Link' + values: + type: array + description: "List of selectable values for options fields when 'valueType' is 'string', 'number', 'boolean', or 'date'." + items: + $ref: '#/components/schemas/ValueObject' + Operator: + type: object + properties: + name: + type: string + description: Name of the operator. The immutable identifier of the operator referenced within the rule expression. + displayName: + type: string + description: Display name of the operator. Use as a user friendly label of the operator to show in UI. + ValueObject: + type: object + properties: + name: + type: string + description: The name that uniquely identifies the option. + displayName: + type: string + description: The display name for the option. + Link: + type: object + properties: + href: + type: string + description: Url of the endpoint. + method: + type: string + description: Http method. + enum: + - GET + rel: + type: string + description: Indicates the endpoint’s relation to retrieving or filtering field values. + enum: + - values + - filter + Error: + type: object + properties: + code: + type: string + description: Error code + example: RMS-00000 + message: + type: string + description: Error message. + example: Some error message. + description: + type: string + description: Detailed error description. + example: Some error description. + traceId: + type: string + description: Trace identifier to refer at troubleshooting logs to troubleshoot the problem. + example: e0fbcfeb-3617-43c4-8dd0-7b7d38e13047 + securitySchemes: + BasicAuth: + type: http + scheme: basic + OAuth2: + type: oauth2 + flows: + authorizationCode: + authorizationUrl: https://localhost:9443/oauth2/authorize + tokenUrl: http://localhost:9763/oauth2/token + scopes: + read: internal_rule_metadata_view diff --git a/en/identity-server/next/docs/apis/rule-metadata-rest-api.md b/en/identity-server/next/docs/apis/rule-metadata-rest-api.md new file mode 100644 index 0000000000..922e18f65d --- /dev/null +++ b/en/identity-server/next/docs/apis/rule-metadata-rest-api.md @@ -0,0 +1,5 @@ +--- +template: templates/redoc.html +--- + + \ No newline at end of file diff --git a/en/identity-server/next/mkdocs.yml b/en/identity-server/next/mkdocs.yml index 2e3366785f..914554cd7d 100644 --- a/en/identity-server/next/mkdocs.yml +++ b/en/identity-server/next/mkdocs.yml @@ -784,6 +784,7 @@ nav: - Role management: - Roles v2 API: apis/roles-v2-rest-api.md - Roles v1 API (deprecated): apis/roles-v1-rest-api.md + - Rule Metadata API: apis/rule-metadata-rest-api.md - Server management: - Configuration management: - Configuration management API: apis/use-the-configuration-management-rest-apis.md