applying indentation using leveloffsets

server_admin/topics/assembly-managing-clients.adoc

@@ -0,0 +1,19 @@
+
+[id="assembly-managing-clients_{context}"]
+== Managing Clients
+
+[role="_abstract"]
+Clients are entities that can request authentication of a user.  Clients come in two forms.
+The first type of client is an application that wants
+to participate in single-sign-on.  These clients just want {project_name} to provide security for them.  The other type
+of client is one that is requesting an access token so that it can invoke other services on behalf of the authenticated user.
+This section discusses various aspects around configuring clients and various ways to do it.
+
+include::clients/assembly-client-oidc.adoc[leveloffset=2]
+include::clients/saml/proc-creating-saml-client.adoc[leveloffset=2]
+include::clients/saml/idp-initiated-login.adoc[leveloffset=3]
+include::clients/saml/proc-using-an-entity-descriptor.adoc[leveloffset=3]
+include::clients/con-client-links.adoc[leveloffset=2]
+include::clients/con-protocol-mappers.adoc[leveloffset=2]
+include::clients/proc-generating-client-adapter-config.adoc[leveloffset=2]
+include::clients/con-client-scopes.adoc[leveloffset=2]

server_admin/topics/assembly-managing-users.adoc

@@ -1,4 +1,5 @@
 
+[id="assembly-managing-users_{context}"]
 ==  Managing Users
 
 From the Admin Console, you have a wide range of actions you can perform to manage users.

server_admin/topics/assembly-roles-groups.adoc

@@ -6,12 +6,12 @@ A role typically applies to one type of user. For example, an organization may i
 
 There is a global namespace for roles and each client also has its own dedicated namespace where roles can be defined. 
 
-include::roles-groups/proc-creating-realm-roles.adoc[]
-include::roles-groups/con-client-roles.adoc[]
-include::roles-groups/proc-converting-composite-roles.adoc[]
-include::roles-groups/proc-assigning-role-mappings.adoc[]
-include::roles-groups/con-default-roles.adoc[]
-include::roles-groups/con-role-scope-mappings.adoc[]
-include::roles-groups/proc-managing-groups.adoc[]
-include::roles-groups/con-comparing-groups-roles.adoc[]
-include::roles-groups/proc-specifying-default-groups.adoc[]
+include::roles-groups/proc-creating-realm-roles.adoc[leveloffset=2]
+include::roles-groups/con-client-roles.adoc[leveloffset=2]
+include::roles-groups/proc-converting-composite-roles.adoc[leveloffset=2]
+include::roles-groups/proc-assigning-role-mappings.adoc[leveloffset=2]
+include::roles-groups/proc-using-default-roles.adoc[leveloffset=2]
+include::roles-groups/con-role-scope-mappings.adoc[leveloffset=2]
+include::roles-groups/proc-managing-groups.adoc[leveloffset=2]
+include::roles-groups/con-comparing-groups-roles.adoc[leveloffset=3]
+include::roles-groups/proc-specifying-default-groups.adoc[leveloffset=3]

server_admin/topics/clients.adoc

@@ -1,19 +0,0 @@
-[[_clients]]
-
-== Managing Clients
-
-[role="_abstract"]
-Clients are entities that can request authentication of a user.  Clients come in two forms.
-The first type of client is an application that wants
-to participate in single-sign-on.  These clients just want {project_name} to provide security for them.  The other type
-of client is one that is requesting an access token so that it can invoke other services on behalf of the authenticated user.
-This section discusses various aspects around configuring clients and various ways to do it.
-
-include::clients/client-oidc.adoc[]
-include::clients/saml/proc-creating-saml-client.adoc[]
-include::clients/saml/idp-initiated-login.adoc[]
-include::clients/saml/proc-using-an-entity-descriptor.adoc[]
-include::clients/client-link.adoc[]
-include::clients/con-protocol-mappers.adoc[]
-include::clients/proc-generating-client-adapter-config.adoc[]
-include::clients/con-client-scopes.adoc[]

server_admin/topics/clients/assembly-client-oidc.adoc

@@ -0,0 +1,17 @@
+
+[id="assembly-oidc-clients_{context}"]
+= OIDC Clients
+[role="_abstract"]
+xref:con-oidc_{context}[OpenID Connect] is the recommended protocol to secure applications.  It was designed from the ground up to be web friendly and it works best with HTML5/JavaScript applications.
+
+include::oidc/proc-creating-oidc-client.adoc[leveloffset=3]
+
+include::oidc/con-basic-settings.adoc[leveloffset=3]
+
+include::oidc/con-advanced-settings.adoc[leveloffset=3]
+
+include::oidc/con-confidential-client-credentials.adoc[leveloffset=3]
+
+include::oidc/proc-using-a-service-account.adoc[leveloffset=3]
+
+include::oidc/con-audience.adoc[leveloffset=3]

server_admin/topics/clients/client-oidc.adoc

@@ -7,4 +7,8 @@ xref:con-oidc_{context}[OpenID Connect] is the recommended protocol to secure ap
 include::proc-creating-oidc-client.adoc[]
 include::con-basic-settings.adoc[]
 include::con-advanced-settings.adoc[]
+=======
+>>>>>>> ee3211e6... applying indentation using leveloffsets
+
+>>>>>>> 25f32ee4... applying indentation using leveloffsets
 include::oidc/con-audience.adoc[]

server_admin/topics/clients/con-client-links.adoc

@@ -1,5 +1,6 @@
 
-=== Client Links
+[id="con-client-links_{context}"]
+= Client Links
 [role="_abstract"]
 To link from one client to another, {project_name} provides a redirect endpoint: `/realms/realm_name/clients/\{client-id}/redirect`.
 

server_admin/topics/clients/con-client-scopes.adoc

@@ -1,7 +1,7 @@
 [id="con-client-scopes_{context}"]
 
 [[_client_scopes]]
-=== Client Scopes
+= Client Scopes
 
 [role="_abstract"]
 Use {project_name} to define a shared client configuration in an entity called a _client scope_. A _client scope_ configures <<_protocol-mappers, protocol mappers>> and <<_role_scope_mappings, role scope mappings>> for multiple clients.
@@ -10,7 +10,7 @@ Client scopes also support the OAuth 2 *scope* parameter. Client applications us
 
 include::proc-creating-client-scopes.adoc[]
 
-==== Protocol
+== Protocol
 When you create a client scope, choose the *Protocol*. Clients linked in the same scope must have the same protocol.
 
 Each realm has a set of pre-defined built-in client scopes in the menu.
@@ -50,7 +50,7 @@ When the *phone* client scope is linked to a client, the client automatically in
 
 Built-in client scopes contain the protocol mappers as defined in the specification. You are free to edit client scopes and create, update, or remove any protocol mappers or role scope mappings.
 
-==== Consent related settings
+== Consent related settings
 Client scopes contain options related to the consent screen. Those options are useful if the linked client if *Consent Required* is enabled on the client.
 
 Display On Consent Screen::
@@ -60,7 +60,7 @@ Consent Screen Text::
   The text displayed on the consent screen when this client scope is added to a client when consent required defaults to the name of client scope. The value for this text can be customised by specifying a substitution variable with *${var-name}* strings. The customised value is  configured within the property files in your theme. See the  link:{developerguide_link}[{developerguide_name}] for more information on customisation.
 
 [[_client_scopes_linking]]
-==== Link Client Scope with the Client
+== Link Client Scope with the Client
 Linking between a client scope and a client is configured in the *Client Scopes* tab of the client. Two ways of linking between client scope and client are available.
 
 Default Client Scopes::
@@ -69,7 +69,7 @@ This setting is applicable to the OpenID Connect and SAML clients. Default clien
 Optional Client Scopes::
 This setting is applicable only for OpenID Connect clients. Optional client scopes are applied when issuing tokens for this client but only when requested by the *scope* parameter in the OpenID Connect authorization request.
 
-===== Example
+=== Example
 For this example, assume the client has *profile* and *email* linked as default client scopes, and *phone* and *address* linked as optional client scopes. The client uses the value of the scope parameter when sending a request to the OpenID Connect authorization endpoint.
 
 [source,bash,subs=+attributes]
@@ -80,10 +80,10 @@ scope=openid phone
 The scope parameter contains the string, with the scope values divided by spaces. The value *openid* is the meta-value used for all OpenID Connect requests. The token will contain mappers and role scope mappings from the default client scopes *profile* and *email* as well as *phone*, an optional client scope requested by the scope parameter.
 
 [[_client_scopes_evaluate]]
-==== Evaluating Client Scopes
+== Evaluating Client Scopes
 include::proc-evaluating-client-scopes.adoc[]
 
-==== Client Scopes Permissions
+== Client Scopes Permissions
 
 When issuing tokens to a user, the client scope applies only if the user is permitted to use it.
 
@@ -91,10 +91,10 @@ When a client scope does not have any role scope mappings defined, each user is
 
 If a user is not permitted to use the client scope, no protocol mappers or role scope mappings will be used when generating tokens. The client scope will not appear in the _scope_ value in the token.
 
-==== Realm Default Client Scopes
+== Realm Default Client Scopes
 include::proc-updating-default-scopes.adoc[]
 
-==== Scopes explained
+== Scopes explained
 Client scope::
 Client scopes are entities in {project_name} that are configured at the realm level and can be linked to clients. Client scopes are referenced by their name when a request is sent to the {project_name} authorization endpoint with a corresponding value of the *scope* parameter. See the <<_client_scopes_linking, client scopes linking>> section for more details.
 

server_admin/topics/clients/con-protocol-mappers.adoc

@@ -1,7 +1,7 @@
 [id="con-protocol-mappers_{context}"]
 [[_protocol-mappers]]
 
-=== OIDC Token and SAML Assertion Mappings
+= OIDC Token and SAML Assertion Mappings
 
 [role="_abstract"]
 Applications receiving ID tokens, access tokens, or SAML assertions may require different roles and user metadata. 
@@ -33,7 +33,7 @@ You can use most OIDC mappers to control where the claim gets placed. You opt to
 
 include::proc-creating-mappers.adoc[]
 
-==== Priority order
+== Priority order
 
 Mapper implementations have _priority order_. _Priority order_ is not the configuration property of the mapper. It is the property of the concrete implementation of the mapper.
 
@@ -45,7 +45,7 @@ For example, to compute the roles which will be included with a token:
 . Process a JavaScript script that uses the roles and audiences already available in the token.
 
 [[_protocol-mappers_oidc-user-session-note-mappers]]
-==== OIDC User Session Note Mappers
+== OIDC User Session Note Mappers
 
 User session details are defined using mappers and are automatically included when you use or enable a feature on a client. Click *Add builtin* to include session details.
 
@@ -60,7 +60,7 @@ Service account sessions provide the following details:
 * *clientAddress*: The remote host IP of the service account's authenticated device.
 * *clientHost*: The remote host name of the service account's authenticated device.
 
-==== Script Mapper
+== Script Mapper
 
 Use the *Script Mapper* to map claims to tokens by running user-defined JavaScript code. For more details about deploying scripts to the server, see link:{developerguide_jsproviders_link}[{developerguide_jsproviders_name}].
 

server_admin/topics/clients/oidc/con-advanced-settings.adoc

@@ -1,5 +1,5 @@
 [id="con-advanced-settings_{context}"]
-==== Advanced Settings
+= Advanced Settings
 [role="_abstract"]
 When you click _Advanced Settings_, additional fields are displayed.
 

server_admin/topics/clients/oidc/con-audience.adoc

@@ -1,8 +1,6 @@
-[id="con_audience_{context}"]
 
-[[_audience]]
-
-==== Audience Support
+[id="con-audience_{context}"]
+= Audience Support
 [role="_abstract"]
 Typically, the environment where {project_name} is deployed consists of a set of _confidential_ or _public_ client applications that use {project_name} for authentication.
 
@@ -48,7 +46,7 @@ If the client wants to invoke the trusted service later, it must obtain another
 ----
 Use this value to invoke the *<trusted service>*.
 
-===== Setup
+== Setup
 
 When setting up audience checking:
 
@@ -57,7 +55,7 @@ When setting up audience checking:
 * Ensure that access tokens issued by {project_name} contain all necessary audiences. Audiences can be added using the client roles as described in the <<_audience_resolve, next section>> or hardcoded as described in <<_audience_hardcoded, below>>.
 
 [[_audience_resolve]]
-===== Automatically add audience
+== Automatically add audience
 
 An _Audience Resolve_ protocol mapper is defined in the default client scope _roles_. The mapper checks for clients that have at least one client role available for the current token. The client ID of each client is then added as an audience, which is useful if your service (usually bearer-only) clients rely on client roles.
 
@@ -86,7 +84,7 @@ If you need the client itself as an audience, see the
 ====
 
 [[_audience_hardcoded]]
-===== Hardcoded audience
+== Hardcoded audience
 
 When your service relies on realm roles or does not rely on the roles in the token at all, it can be useful to use a hardcoded audience. A hardcoded audience is a protocol mapper, that will add the client ID of the specified service client as an audience to the token.
 You can use any custom value, for example a URL, if you want to use a different audience than the client ID.

server_admin/topics/clients/oidc/con-basic-settings.adoc

@@ -1,5 +1,5 @@
 [id="con-basic-settings_{context}"]
-==== Basic Settings
+= Basic Settings
 [role="_abstract"]
 
 When you create an OIDC client, you see the following fields on the *Settings* tab.

server_admin/topics/clients/oidc/con-confidential-client-credentials.adoc

@@ -1,8 +1,7 @@
 [id="con-confidential-client-credentials_{context}"]
 
 [[_client-credentials]]
-
-==== Confidential Client Credentials
+= Confidential Client Credentials
 [role="_abstract"]
 If the <<_access-type, access type>> of the client is set to *confidential*, the credentials of the client must be configured under the *Credentials* tab.
 
@@ -26,8 +25,8 @@ To use the *Signed JWT* credential type, a private key and certificate must be g
 image:{project_images}/generate-client-keys.png[]
 
 . Select the archive format you want to use.
-. Enter a key password.
-. Enter a store password.
+. Enter a *key password*.
+. Enter a *store password*.
 . Click *Generate and Download*.
 
 When you generate the keys, {project_name} will store the certificate and you download the private key and certificate for your client.

server_admin/topics/clients/oidc/proc-creating-oidc-client.adoc

@@ -1,5 +1,5 @@
 [id="proc-creating-oidc-client_{context}"]
-==== Creating an OpenID Connect Client
+= Creating an OpenID Connect Client
 [role="_abstract"]
 To protect an application that uses the OpenID connect protocol, you create a client.
 

server_admin/topics/clients/oidc/proc-using-a-service-account.adoc

@@ -1,22 +1,24 @@
 [id="proc-using-service-account_{context}"]
 
 [[_service_accounts]]
-==== Using a Service Account
+= Using a Service Account
 [role="_abstract"]
 Each OIDC client has a built-in _service account_. Use this _service account_ to obtain an access token.
 
 .Prerequisites
 
 .Procedure
-. Select your client in {project_name}.
-. Click on the *Settings* tab.
-. Set the <<_access-type, Access Type>> of your client is set to *confidential*.
-. Toggle *Service Accounts Enabled* to ON.
+. Click *Clients* in the menu.  
+. Select your client.
+. Click the *Settings* tab.
+. Set the <<_access-type, Access Type>> of your client to *confidential*.
+. Toggle *Service Accounts Enabled* to *ON*.
 . Click *Save*.
 . Configure your <<_client-credentials, client credentials>>.
-. Click on the *Scope* tab.
-. Verify that you have roles or toggle *Full Scope Allowed* to ON.
-. On the *Service Account Roles* tab, configure the roles available to this service account for your client.
+. Click the *Scope* tab.
+. Verify that you have roles or toggle *Full Scope Allowed* to *ON*.
+. Click the *Service Account Roles* tab
+. Configure the roles available to this service account for your client.
 
 Roles from access tokens are the intersection of:
 

server_admin/topics/clients/proc-generating-client-adapter-config.adoc

@@ -2,7 +2,7 @@
 
 [[_client_installation]]
 
-=== Generating Client Adapter Config
+= Generating Client Adapter Config
 [role="_abstract"]
 
 {project_name} can generate configuration files that you can use to install a client adapter in your application's deployment environment. A number of adapter types are supported for OIDC and SAML.

server_admin/topics/clients/saml/idp-initiated-login.adoc

@@ -1,5 +1,5 @@
 
-==== IDP Initiated Login
+= IDP Initiated Login
 [role="_abstract"]
 IDP Initiated Login is a feature that allows you to set up an endpoint on the {project_name} server that will log you into a specific application/client.
 In the *Settings* tab for your client, you need to specify the *IDP Initiated SSO URL Name*.

server_admin/topics/clients/saml/proc-creating-saml-client.adoc

@@ -1,6 +1,6 @@
 [id="proc-creating-saml-client_{context}"]
 
-=== SAML Clients
+= Creating a SAML Client
 [role="_abstract"]
 {project_name} supports <<_saml,SAML 2.0>> for registered applications.
 POST and Redirect bindings are supported. You can choose to require client signature validation. You can have the server sign and/or encrypt responses as well.

server_admin/topics/clients/saml/proc-using-an-entity-descriptor.adoc

@@ -1,6 +1,6 @@
 [id="proc-using-an-entity-descriptors_{context}"]
 
-==== Using an entity descriptor to create a client
+= Using an entity descriptor to create a client
 [role="_abstract"]
 Instead of registering a SAML 2.0 client manually, you can import the client using a standard SAML Entity Descriptor XML file.
 

server_admin/topics/roles-groups/con-client-roles.adoc

@@ -1,5 +1,5 @@
 [id="con-client-roles_{context}"]
 
-=== Client Roles
+= Client Roles
 [role="_abstract"]
 Client roles are namespaces dedicated to clients. Each client gets its own namespace. Client roles are managed under the *Roles* tab for each client. You interact with this UI the same way you do for realm-level roles.

server_admin/topics/roles-groups/con-comparing-groups-roles.adoc

@@ -1,6 +1,6 @@
 [id="con-comparing-groups-roles_{context}"]
 
-==== Groups compared to Roles
+= Groups Compared to Roles
 [role="_abstract"]
 Groups and roles have some similarities and differences. In {project_name}, groups are a collection of users to which you apply roles and attributes. Roles define types of users and applications assign permissions and access control to roles.
 

server_admin/topics/roles-groups/con-role-scope-mappings.adoc

@@ -2,7 +2,7 @@
 
 [[_role_scope_mappings]]
 
-=== Role Scope Mappings
+= Role Scope Mappings
 [role="_abstract"]
 On creation of an OIDC access token or SAML assertion, the user role mappings become claims within the token or assertion.  Applications use these claims to make access decisions on the resources controlled by the application.  {project_name} digitally signs access tokens and applications re-use them to invoke remotely secured REST services.  However, these tokens have an associated risk. An attacker can obtain these tokens and use their permissions to compromise your networks. To prevent this situation, use _Role Scope Mappings_.
 

server_admin/topics/roles-groups/proc-assigning-role-mappings.adoc

@@ -1,8 +1,8 @@
 [id="proc-assigning-role-mappings_{context}"]
 
-=== User Role Mappings
+= Asssiging Role Mappings
 [role="_abstract"]
-You can assign User role mappings to a user through the *Role Mappings* tab for that user.
+You can assign role mappings to a user through the *Role Mappings* tab for that user.
 
 .Procedure
 . Click *Users* in the menu.

server_admin/topics/roles-groups/proc-converting-composite-roles.adoc

@@ -2,15 +2,15 @@
 
 [[_composite-roles]]
 
-=== Composite Roles
+= Converting a role to a composite role
 [role="_abstract"]
-Any realm or client level role can be a _composite role_. A _composite role_ is a role that has one or more additional roles associated with it. When a composite role is mapped to a user, the user gains the roles associated with the composite role.  This inheritance is recursive so users also inherit any composite of composites. However, we recommend that composite roles are not overused.
+Any realm or client level role can become a _composite role_. A _composite role_ is a role that has one or more additional roles associated with it. When a composite role is mapped to a user, the user gains the roles associated with the composite role.  This inheritance is recursive so users also inherit any composite of composites. However, we recommend that composite roles are not overused.
 
-To convert a role to a composite role:
+.Procedure
 
 . Click *Roles* in the menu.
-. Click the role to access the roles detail page.
-. Toggle *Composite Roles* to ON.
+. Click the role that you want to convert.
+. Toggle *Composite Roles* to *ON*.
 
 .Composite Role
 image:{project_images}/composite-role.png[]

server_admin/topics/roles-groups/proc-creating-realm-roles.adoc

@@ -1,13 +1,11 @@
 [id="proc-creating-realm-roles_{context}"]
 
-=== Realm Roles
+= Creating a Realm Role
 [role="_abstract"]
 Realm-level roles are a namespace for defining your roles. To see the list of roles, click *Roles* in the menu.
 
 image:{project_images}/roles.png[]
 
-To create a role:
-
 .Procedure
 . Click *Add Role*.
 . Enter a *Role Name*.

server_admin/topics/roles-groups/proc-managing-groups.adoc

@@ -1,5 +1,5 @@
 [id="proc-managing-groups_{context}"]
-=== Groups
+= Groups
 [role="_abstract"]
 Groups in {project_name} manage a common set of attributes and role mappings for each user. Users can be members of any number of groups and inherit the attributes and role mappings assigned to each group.
 

server_admin/topics/roles-groups/proc-specifying-default-groups.adoc

@@ -1,13 +1,13 @@
 [id="proc-specifying-default-groups_{context}"]
 
-==== Default Groups
+= Using Default Groups
 [role="_abstract"]
 To automatically assign group membership to any users who is created or who is imported through <<_identity_broker, Identity Brokering>>, you use default groups.
 
-To specify default groups:
-
 . Click *Groups* in the menu.
 . Click the *Default Groups* tab.
 
 .Default Groups
 image:{project_images}/default-groups.png[]
+
+This screenshot shows that some _default groups_ already exist.

server_admin/topics/roles-groups/proc-using-default-roles.adoc

@@ -1,10 +1,14 @@
-[id="con-default-roles_{context}"]
+[id="proc-using-default-roles_{context}"]
 
 [[_default_roles]]
-==== Default Roles
+= Using Default Roles
 [role="_abstract"]
 Use default roles to automatically assign user role mappings when a user is created or imported through <<_identity_broker, Identity Brokering>>.
-To specify default roles, click *Roles* in the menu and click the *Default Roles* tab.
+
+.Procedure
+
+. Click *Roles* in the menu
+. Click the *Default Roles* tab.
 
 .Default Roles
 image:{project_images}/default-roles.png[]

server_admin/topics/sso-protocols/oidc.adoc

@@ -57,7 +57,7 @@ to provide a client secret when they exchange the temporary codes for tokens.  _
 _Public_ clients are perfectly fine so long as HTTPS is strictly enforced and you are very strict about what redirect URIs are registered for the
 client.  HTML5/JavaScript clients always have to be _public_ clients because there is no way to transmit the client secret to them in a secure
 manner.  Again, this is ok so long as you use HTTPS and strictly enforce redirect URI registration.  This guide goes more detail
-into this in the <<_clients, Managing Clients>> chapter.
+into this in the xref:assembly-managing-clients_{context}[Managing Clients] chapter.
 
 {project_name} also supports the optional https://datatracker.ietf.org/doc/html/rfc7636[Proof Key for Code Exchange] specification.
 

server_admin/topics/threat/audience-limit.adoc

@@ -3,4 +3,4 @@
 
 In environments where the level of trust among services is low, it is a good practice to limit the audiences on the token. The
 motivation behind this is described in the https://datatracker.ietf.org/doc/html/rfc6819#section-5.1.5.5[OAuth2 Threat Model] document and
-more details are in the <<_audience, Audience Support section>>.
+more details are in the <<_audience, Audience Support section>>.