[RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing DITA errors in configuration/declarative-configuration-using.adoc

configuration/declarative-configuration-using.adoc

@@ -7,28 +7,36 @@ include::modules/common-attributes.adoc[]
 toc::[]
 
 [role="_abstract"]
-
 With declarative configuration, you can update configurations by storing them in files in repositories and apply them to the system. Declarative configuration is useful, for example, if you are using a GitOps workflow. You can currently use declarative configuration in {rh-rhacs-first} for authentication and authorization resources such as authentication providers, roles, permission sets, and access scopes.
 
-To use declarative configuration, you create YAML files that contain configuration information about authentication and authorization resources. These files, or configurations, are added to {product-title-short} by using a mount point during Central installation. See the installation documentation in the "Additional resources" section for more information on configuring mount points when installing {product-title-short}.
+//Declarative configuration overview
+include::modules/declarative-configuration-overview.adoc[leveloffset=+1]
 
-The configuration files used with declarative configuration are stored in config maps or secrets, depending on the type of resource. Store configurations for authentication providers in a secret for greater security. You can store other configurations in config maps.
+//Restrictions for resources created from declarative configuration
+include::modules/declarative-configuration-restrictions.adoc[leveloffset=+1]
 
-A single config map or secret can contain more than one configuration of multiple resource types. This allows you to limit the number of volume mounts for the Central instance.
+//Creating declarative configurations
+include::modules/declarative-configuration-resource-create.adoc[leveloffset=+1]
 
-[id="restrictions-declarative-config-resources"]
-== Restrictions for resources created from declarative configuration
+//Declarative configuration examples
+include::modules/declarative-configuration-examples.adoc[leveloffset=+1]
 
-Because resources can reference other resources (for example, a role can reference both a permission set and access scope), the following restrictions for references apply:
+include::modules/declarative-config-example-auth-provider.adoc[leveloffset=+2]
 
-* A declarative configuration can only reference a resource that is either also created declaratively or a system {product-title-short} resource; for example, a resource such as the `Admin` or `Analyst` system role or permission set.
-* All references between resources use names to identify the resource; therefore, all names within the same resource type must be unique.
-* Resources created from declarative configuration can only be modified or deleted by altering the declarative configuration files. You cannot change these resources by using the {product-title-short} portal or the API.
+include::modules/declarative-config-example-short-lived-token.adoc[leveloffset=+2]
 
-include::modules/declarative-configuration-resource-create.adoc[leveloffset=+1]
+[role="_additional-resources"]
+.Additional resources
+* xref:../operating/manage-user-access/configure-short-lived-access.adoc#configure-short-lived-access_configure-short-lived-access[Configuring short-lived access]
+* xref:../integration/integrate-using-short-lived-tokens.adoc#integrate-using-short-lived-tokens[Integrating {product-title-short} using short-lived tokens]
 
-include::modules/declarative-configuration-examples.adoc[leveloffset=+1]
+include::modules/declarative-config-example-permission-set.adoc[leveloffset=+2]
+
+include::modules/declarative-config-example-access-scope.adoc[leveloffset=+2]
+
+include::modules/declarative-config-example-role.adoc[leveloffset=+2]
 
+//Troubleshooting declarative configuration
 include::modules/declarative-configuration-troubleshooting.adoc[leveloffset=+1]
 
 [role="_additional-resources"]

modules/declarative-config-example-access-scope.adoc

@@ -0,0 +1,38 @@
+// Module included in the following assemblies:
+//
+// * configuration/declarative-configuration-using.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="declarative-config-example-access-scope_{context}"]
+= Declarative configuration access scope example
+
+[role="_abstract"]
+Example YAML configuration for creating an access scope by using declarative configuration.
+
+[source,yaml]
+----
+name: A sample access scope
+description: A sample access scope created declaratively
+rules:
+    included:
+        - cluster: secured-cluster-A
+          namespaces:
+            - namespaceA
+        - cluster: secured-cluster-B
+    clusterLabelSelectors:
+        - requirements:
+          - key: kubernetes.io/metadata.name
+            operator: IN
+            values:
+            - production
+            - staging
+            - environment
+----
+
+where:
+
+--
+`rules.included.cluster`:: Specifies a cluster where the access scope includes only specific namespaces.
+`rules.included.cluster`:: Specifies a cluster where the access scope includes all namespaces.
+`rules.clusterLabelSelectors.requirements.operator`:: Specifies the Operator to use for the label selection. Valid values are `IN`, `NOT_IN`, `EXISTS`, and `NOT_EXISTS`.
+--

modules/declarative-config-example-auth-provider.adoc

@@ -0,0 +1,75 @@
+// Module included in the following assemblies:
+//
+// * configuration/declarative-configuration-using.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="declarative-config-example-auth-provider_{context}"]
+= Declarative configuration authentication provider example
+
+[role="_abstract"]
+Example YAML configuration for creating an authentication provider by using declarative configuration.
+
+[source,yaml]
+----
+name: A sample auth provider
+minimumRole: Analyst
+uiEndpoint: central.custom-domain.com:443
+extraUIEndpoints:
+    - central-alt.custom-domain.com:443
+groups:
+    - key: email
+      value: example@example.com
+      role: Admin
+    - key: groups
+      value: reviewers
+      role: Analyst
+requiredAttributes:
+    - key: org_id
+      value: "12345"
+claimMappings:
+    - path: org_id
+      value: my_org_id
+oidc:
+    issuer: sample.issuer.com
+    mode: auto
+    clientID: CLIENT_ID
+    clientSecret: CLIENT_SECRET
+clientSecret: CLIENT_SECRET
+iap:
+    audience: audience
+saml:
+    spIssuer: sample.issuer.com
+    metadataURL: sample.provider.com/metadata
+saml:
+    spIssuer: sample.issuer.com
+    cert: |
+    ssoURL: saml.provider.com
+    idpIssuer: idp.issuer.com
+userpki:
+    certificateAuthorities: |
+    certificate
+openshift:
+    enable: true
+----
+
+where:
+
+--
+`minimumRole`:: Specifies the minimum role that the system assigns by default to any user logging in. If left blank, the value is `None`.
+`uiEndpoint`:: Specifies the user interface endpoint of your Central instance.
+`extraUIEndpoints`:: Specifies whether your Central instance exposes different endpoints.
+`groups`:: Specifies the specific roles to map users based on their attributes.
+`groups.key`:: Specifies the key that can be any claim the authentication provider returns.
+`groups.role`:: Specifies the role that the system gives to the users. You can use a default role or a declaratively-created role.
+`requiredAttributes`:: Specifies whether the authentication provider requires the returned attributes, for example, if the audience limits to a specific organization or group. This is optional.
+`claimMappings`:: Specifies whether to map the claims the identity provider returns to custom claims. This is optional.
+`oidc`:: Specifies whether to configure the system to use OpenID Connect (OIDC) as an authentication method.
+`oidc.issuer`:: Specifies the expected issuer for the token.
+`oidc.mode`:: Specifies the OIDC callback mode. Possible values are `auto`, `post`, `query`, and `fragment`. The preferred value is `auto`.
+`iap`:: Specifies whether to configure the system to use Google Identity-Aware Proxy (IAP) as an authentication method.
+`saml`:: Specifies whether to configure the system to use Security Assertion Markup Language (SAML) 2.0 dynamic or static configuration as an authentication method.
+`saml.cert`:: Specifies the certificate in Privacy Enhanced Mail (PEM) format.
+`userpki.certificateAuthorities`:: Specifies whether to configure the system for authentication with user certificates.
+`userpki.certificate`:: Specifies the certificate in PEM format.
+`openshift`:: Specifies whether to configure the system for OpenShift Auth authentication providers.
+--

modules/declarative-config-example-permission-set.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+//
+// * configuration/declarative-configuration-using.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="declarative-config-example-permission-set_{context}"]
+= Declarative configuration permission set example
+
+[role="_abstract"]
+Example YAML configuration for creating a permission set by using declarative configuration.
+
+[source,yaml]
+----
+name: A sample permission set
+description: A sample permission set created declaratively
+resources:
+- resource: Integration
+  access: READ_ACCESS
+- resource: Administration
+  access: READ_WRITE_ACCESS
+----
+
+where:
+
+--
+`resources.resource`:: Specifies a full list of supported resources. For more information, go to *Access Control* -> *Permission Sets*.
+`resources.access`:: Specifies that the access can be either `READ_ACCESS` or `READ_WRITE_ACCESS`.
+--

modules/declarative-config-example-role.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// * configuration/declarative-configuration-using.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="declarative-config-example-role_{context}"]
+= Declarative configuration role example
+
+[role="_abstract"]
+Example YAML configuration for creating a role by using declarative configuration.
+
+[source,yaml]
+----
+name: A sample role
+description: A sample role created declaratively
+permissionSet: A sample permission set
+accessScope: Unrestricted
+----
+
+where:
+
+--
+`permissionSet`:: Specifies the name of the permission set; can be either one of the system permission sets or a declaratively-created permission set.
+`accessScope`:: Specifies the name of the access scope; can be either one of the system access scopes or a declaratively-created access scope.
+--

modules/declarative-config-example-short-lived-token.adoc

@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//
+// * configuration/declarative-configuration-using.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="declarative-config-example-short-lived-token_{context}"]
+= Declarative configuration short-lived token example
+
+[role="_abstract"]
+Example YAML configuration for creating a short-lived token configuration by using declarative configuration.
+
+[source,yaml]
+----
+issuer: https://token.actions.githubusercontent.com
+type: GITHUB_ACTION
+tokenExpirationDuration: 20m
+mappings:
+  - key: sub
+    value: repos:stackrox:stackrox
+    role: Analyst
+----
+
+where:
+
+--
+`issuer`:: Specifies the expected issuer for the token to exchange against a short-lived one.
+`type`:: Specifies the configuration type. See "Configuring short-lived access" and "Integrating {product-title-short} using short-lived access tokens" for more information.
+`tokenExpirationDuration`:: Specifies the token lifetime in the *XhYmZs* format. The lifetime cannot be longer than 24 hours.
+`mappings`:: Specifies the roles to which the system maps users, based on their attributes.
+`mappings.key`:: Specifies that the key can be any claim the issuer returns.
+`mappings.role`:: Specifies the role that the system gives to the users. You can use a default role or a declaratively-created one.
+--