diff --git a/server_admin/topics/clients/con-client-scopes.adoc b/server_admin/topics/clients/con-client-scopes.adoc index 2a9074f161..d36e6a43cb 100644 --- a/server_admin/topics/clients/con-client-scopes.adoc +++ b/server_admin/topics/clients/con-client-scopes.adoc @@ -6,77 +6,77 @@ [role="_abstract"] {project_name} allows you to define a shared client configuration in an entity called a _client scope_. This entity allows you to configure <<_protocol-mappers, protocol mappers>> and <<_role_scope_mappings, role scope mappings>> for multiple clients. -Client scopes also support the OAuth 2 `scope` parameter. This parameter allows client applications to request more or fewer claims or roles in the access token, depending on the requirement of the application. +Client scopes also support the OAuth 2 *scope* parameter. This parameter allows client applications to request more or fewer claims or roles in the access token, depending on the requirement of the application. include::proc-creating-client-scopes.adoc[] ==== Protocol -When you create a client scope, you must choose the `Protocol`. Clients linked in the same scope must have the same protocol. +When you create a client scope, you must 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. -* SAML protocol: The `role_list`. This scope contains one protocol mapper for the roles list in the SAML assertion. +* SAML protocol: The *role_list*. This scope contains one protocol mapper for the roles list in the SAML assertion. * OpenID Connect protocol: There are several client scopes: -** `roles` +** *roles* + -This scope is not defined in the OpenID Connect specification and is not added automatically to the `scope` claim in the access token. This scope has mappers, which are used to add the roles of the user to the access token and +This scope is not defined in the OpenID Connect specification and is not added automatically to the *scope* claim in the access token. This scope has mappers, which are used to add the roles of the user to the access token and add audiences for clients that have at least one client role. This is described in more detail in the <<_audience_resolve, Audience section>>. + -** `web-origins` +** *web-origins* + -This scope is also not defined in the OpenID Connect specification and not added to the `scope` claimin the access token. This scope is used to add allowed web origins to the access token `allowed-origins` claim. +This scope is also not defined in the OpenID Connect specification and not added to the *scope* claimin the access token. This scope is used to add allowed web origins to the access token *allowed-origins* claim. + -** `microprofile-jwt` +** *microprofile-jwt* + -This scope handles claims defined in the https://wiki.eclipse.org/MicroProfile/JWT_Auth[MicroProfile/JWT Auth Specification]. This scope defines a user property mapper for the `upn` claim and a realm role mapper for the `groups` claim. These mappers can be changed so different properties can be used to create the MicroProfile/JWT specific claims. +This scope handles claims defined in the https://wiki.eclipse.org/MicroProfile/JWT_Auth[MicroProfile/JWT Auth Specification]. This scope defines a user property mapper for the *upn* claim and a realm role mapper for the *groups* claim. These mappers can be changed so different properties can be used to create the MicroProfile/JWT specific claims. + -** `offline_access` +** *offline_access* + This scope is used in cases when clients need to obtain offline tokens. More details on offline tokens is available in the <<_offline-access, Offline Access section>> and in the https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess[OpenID Connect specification]. + -** `profile` -** `email` -** `address` -** `phone` +** *profile* +** *email* +** *address* +** *phone* -The client scopes `profile`, `email`, `address` and `phone` are defined in the https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims[OpenID Connect specification]. These scopes do not have any role scope mappings defined but they do have protocol mappers defined. These mappers correspond to the claims defined in the OpenID Connect specification. +The client scopes *profile*, *email*, *address* and *phone* are defined in the https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims[OpenID Connect specification]. These scopes do not have any role scope mappings defined but they do have protocol mappers defined. These mappers correspond to the claims defined in the OpenID Connect specification. -For example, when you open the `phone` client scope and open the `Mappers` tab, you will see the protocol mappers which correspond to the claims defined in the specification for the scope `phone`. +For example, when you open the *phone* client scope and open the *Mappers* tab, you will see the protocol mappers which correspond to the claims defined in the specification for the scope *phone*. .Client Scope Mappers image:{project_images}/client-scopes-phone.png[] -When the `phone` client scope is linked to a client, the client automatically inherits all the protocol mappers defined in the `phone` client scope. Access tokens issued for this client contain the phone number information about the user, assuming that the user has a defined phone number. +When the *phone* client scope is linked to a client, the client automatically inherits all the protocol mappers defined in the *phone* client scope. Access tokens issued for this client contain the phone number information about the user, assuming that the user has a defined phone number. 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 -Client scopes contain options related to the consent screen. Those options are useful if the linked client if the `Consent Required` switch is enabled on the client. +Client scopes contain options related to the consent screen. Those options are useful if the linked client if the *Consent Required* switch is enabled on the client. Display On Consent Screen:: - If this switch is set to ON, and the scope is added to a client that requires consent, the text specified in `Consent Screen Text` will be displayed on the consent screen. This text is shown when the user is authenticated and before the user is redirected from {project_name} to the client. If this switch is OFF, this client scope will not be displayed on the consent screen. + If this switch is set to ON, and the scope is added to a client that requires consent, the text specified in *Consent Screen Text* will be displayed on the consent screen. This text is shown when the user is authenticated and before the user is redirected from {project_name} to the client. If this switch is OFF, this client scope will not be displayed on the consent screen. 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. + 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 -Linking between a client scope and a client is configured in the `Client Scopes` tab of the client. There are 2 ways of linking between client scope and client. +Linking between a client scope and a client is configured in the *Client Scopes* tab of the client. There are 2 ways of linking between client scope and client. Default Client Scopes:: This is applicable to the OpenID Connect and SAML clients. Default client scopes are applied when issuing OpenID Connect tokens or SAML assertions for a client. The client will inherit Protocol Mappers and Role Scope Mappings that are defined on the client scope. For the OpenID Connect Protocol, the Mappers and Role Scope Mappings are always applied, regardless of the value used for the scope parameter in the OpenID Connect authorization request. Optional Client Scopes:: -This 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. +This 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 -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. +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. -``` +*** 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. +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 @@ -95,14 +95,14 @@ include::proc-updating-default-scopes.adoc[] ==== 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. +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. Role scope mapping:: -Available under the `Scope` tab of a client or client scope. Role scope mapping allows you to limit the roles which can be used in the access tokens. See the <<_role_scope_mappings, Role Scope Mappings section>> for more details. +Available under the *Scope* tab of a client or client scope. Role scope mapping allows you to limit the roles which can be used in the access tokens. See the <<_role_scope_mappings, Role Scope Mappings section>> for more details. ifeval::[{project_community}==true] Authorization scopes:: -The `Authorization Scope` covers the actions that can be perfoemdd in the application. See the link:{authorizationguide_link}[Authorization Services Guide] for more details. +The *Authorization Scope* covers the actions that can be perfoemdd in the application. See the link:{authorizationguide_link}[Authorization Services Guide] for more details. endif::[] diff --git a/server_admin/topics/clients/con-protocol-mappers.adoc b/server_admin/topics/clients/con-protocol-mappers.adoc index 9366c509e8..892e8b8daa 100644 --- a/server_admin/topics/clients/con-protocol-mappers.adoc +++ b/server_admin/topics/clients/con-protocol-mappers.adoc @@ -12,7 +12,7 @@ Applications receiving ID tokens, access tokens, or SAML assertions may require * Pull user metadata into a token or assertion. * Rename roles. -You can do this in the `Mappers` tab in the Admin Console +You can do this in the *Mappers* tab in the Admin Console .Mappers Tab image:{project_images}/mappers-oidc.png[] @@ -20,16 +20,16 @@ image:{project_images}/mappers-oidc.png[] New clients do not have built-in mappers but they can inherit some mappers from client scopes. See the <<_client_scopes, client scopes section>> for more details. Protocol mappers map items (such as an email address, for example) to -a specific claim in the identity and access token. The function of a mapper should be self explanatory from its name. You can add pre-configured mappers by clicking the `Add Builtin` button. +a specific claim in the identity and access token. The function of a mapper should be self explanatory from its name. You can add pre-configured mappers by clicking the *Add Builtin* button. -Each mapper has a set of common settings. There are additional settings available, depending on the mapper type. Click the `Edit` button next to a mapper to access the configuration screen to adjust these settings. +Each mapper has a set of common settings. There are additional settings available, depending on the mapper type. Click the *Edit* button next to a mapper to access the configuration screen to adjust these settings. .Mapper Config image:{project_images}/mapper-config.png[] Details on each option can be viewed by hovering over its tooltip. -Many OIDC mappers allow you to control where the claim gets placed. You can opt to include or exclude the claim from the _id_ and _access_ tokens by adjusting the `Add to ID token` and `Add to access token` switches. +Many OIDC mappers allow you to control where the claim gets placed. You can opt to include or exclude the claim from the _id_ and _access_ tokens by adjusting the *Add to ID token* and *Add to access token* switches. include::proc-creating-mappers.adoc[] @@ -48,21 +48,21 @@ For example, to compute the roles which will be included with a token: [[_protocol-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. You can click the `Add builtin` button to include session details. +User session details are defined using mappers and are automatically included when you use or enable a feature on a client. You can click the *Add builtin* button to include session details. Impersonated user sessions provide the following details: -* `IMPERSONATOR_ID`: The ID of an impersonating user. -* `IMPERSONATOR_USERNAME`: The username of an impersonating user. +* *IMPERSONATOR_ID*: The ID of an impersonating user. +* *IMPERSONATOR_USERNAME*: The username of an impersonating user. Service account sessions provide the following details: -* `clientId`: The client ID of the service account. -* `clientAddress`: The remote host IP of the service account's authenticated device. -* `clientHost`: The remote host name of the service account's authenticated device. +* *clientId*: The client ID of the service account. +* *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 -The `Script Mapper` allows you 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}]. +The *Script Mapper* allows you 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}]. When scripts deploy, you should be able to select the deployed scripts from the list of available mappers. diff --git a/server_admin/topics/clients/oidc/con-advanced-settings.adoc b/server_admin/topics/clients/oidc/con-advanced-settings.adoc index 6b7f4f36f1..2be7bfb086 100644 --- a/server_admin/topics/clients/oidc/con-advanced-settings.adoc +++ b/server_admin/topics/clients/oidc/con-advanced-settings.adoc @@ -44,9 +44,9 @@ If an attacker steals an authorization code of a legitimate client, Proof Key fo An administrator can select one of these options: -`(blank)`:: {project_name} does not apply PKCE unless the client sends appropriate PKCE parameters to {project_name}s authorization endpoint. -`S256`:: {project_name} applies to the client PKCE whose code challenge method is S256. -`plain`:: {project_name} applies to the client PKCE whose code challenge method is plain. +*(blank)*:: {project_name} does not apply PKCE unless the client sends appropriate PKCE parameters to {project_name}s authorization endpoint. +*S256*:: {project_name} applies to the client PKCE whose code challenge method is S256. +*plain*:: {project_name} applies to the client PKCE whose code challenge method is plain. See https://tools.ietf.org/html/rfc7636[RFC 7636 Proof Key for Code Exchange by OAuth Public Clients] for more details. @@ -73,10 +73,10 @@ The client must pass its public key for encrypting CEK to {project_name}. {proje The procedure is: -. Open the client's `Credentials` tab. -. Select `Signed Jwt` from the `Client Authenticator` menu. -. Set the `JWKS URL` switch to ON. -. Input the client's public key URL in the `JWKS URL` textbox. +. Open the client's *Credentials* tab. +. Select *Signed Jwt* from the *Client Authenticator* menu. +. Set the *JWKS URL* switch to ON. +. Input the client's public key URL in the *JWKS URL* textbox. Key Encryption's algorithms are defined in the https://tools.ietf.org/html/rfc7518#section-4.1[Json Web Algorithm (JWA)] specification. {project_name} supports: @@ -86,6 +86,6 @@ Key Encryption's algorithms are defined in the https://tools.ietf.org/html/rfc75 The procedure to select the algorithm is: -. Open the client's `Settings` tab. -. Open `Fine Grain OpenID Connect Configuration`. -. Select the algorithm from `ID Token Encryption Content Encryption Algorithm` pulldown menu. +. Open the client's *Settings* tab. +. Open *Fine Grain OpenID Connect Configuration*. +. Select the algorithm from *ID Token Encryption Content Encryption Algorithm* pulldown menu. diff --git a/server_admin/topics/clients/oidc/con-audience.adoc b/server_admin/topics/clients/oidc/con-audience.adoc index 3c01805556..f47ff90d4a 100644 --- a/server_admin/topics/clients/oidc/con-audience.adoc +++ b/server_admin/topics/clients/oidc/con-audience.adoc @@ -32,27 +32,27 @@ To prevent any misuse of the access token, limit the audience on the token and c . {project_name} authenticates a user. -. {project_name} issues a token to the application. The application knows that it will need to invoke an untrusted service so it places `scope=` in the authentication request sent to {project_name} (see <<_client_scopes, Client Scopes section>> for more details about the _scope_ parameter). +. {project_name} issues a token to the application. The application knows that it will need to invoke an untrusted service so it places *scope=* in the authentication request sent to {project_name} (see <<_client_scopes, Client Scopes section>> for more details about the _scope_ parameter). + -The token issued to the application contains a reference to the untrusted service in its audience (`"audience": [ "" ]`) which declares that the client uses this access token to invoke the untrusted service. +The token issued to the application contains a reference to the untrusted service in its audience (*"audience": [ "" ]*) which declares that the client uses this access token to invoke the untrusted service. + .The untrusted service serves the request to the client application but also keeps the token. . The untrusted service invokes a trusted service with the token. Invocation is not successful because the trusted service checks the audience on the token and find that its audience is only for the untrusted service. This is expected behavior and security is not broken. -If the client wants to invoke the trusted service later, it must obtain another token by reissuing the SSO login with `scope=`. The returned token will then contain the trusted service as an audience: +If the client wants to invoke the trusted service later, it must obtain another token by reissuing the SSO login with *scope=*. The returned token will then contain the trusted service as an audience: [source,json] ---- "audience": [ "" ] ---- -Use this to invoke the ``. +Use this to invoke the **. ===== Setup When setting up audience checking: -* Ensure that services are configured to check audience on the access token sent to them by adding the flag `_verify-token-audience_` in the adapter configuration. See link:{adapterguide_link}#_java_adapter_config[Adapter configuration] for details. +* Ensure that services are configured to check audience on the access token sent to them by adding the flag *_verify-token-audience_* in the adapter configuration. See link:{adapterguide_link}#_java_adapter_config[Adapter configuration] for details. * 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>>. @@ -74,7 +74,7 @@ you can use the access token issued for the confidential client to invoke the be ==== If you want to ensure that the audience is not added automatically, do not configure role scope mappings directly on the confidential client. Instead, you can create a dedicated client scope that contains the role scope mappings for the client roles of your dedicated client scope. -Assuming that the client scope is added as an optional client scope to the confidential client, the client roles and the audience will be added to the token if explicitly requested by the `scope=` parameter. +Assuming that the client scope is added as an optional client scope to the confidential client, the client roles and the audience will be added to the token if explicitly requested by the *scope=* parameter. ==== [NOTE] @@ -94,25 +94,25 @@ You can use any custom value, for example a URL, if you want to use a different You can add the protocol mapper directly to the frontend client. If the protocol mapper is added directly, the audience will be always added as well. -For more control over the protocol mapper, you can create the protocol mapper on the dedicated client scope, which will be called for example `good-service`. +For more control over the protocol mapper, you can create the protocol mapper on the dedicated client scope, which will be called for example *good-service*. .Audience Protocol Mapper image:{project_images}/audience_mapper.png[] -* From the <<_client_installation, Installation tab>> of the `good-service` client, you can generate the adapter configuration and you can confirm that _verify-token-audience_ option will be set to `true`. This forces the adapter to verify the audience if you use this configuration. +* From the <<_client_installation, Installation tab>> of the *good-service* client, you can generate the adapter configuration and you can confirm that _verify-token-audience_ option will be set to *true*. This forces the adapter to verify the audience if you use this configuration. -* You need to ensure that the `my-app` frontend client is able to request `good-service` as an audience in its tokens. +* You need to ensure that the *my-app* frontend client is able to request *good-service* as an audience in its tokens. + -On the `my-app` client: +On the *my-app* client: + . Click the _Client Scopes_ tab. -. Assign `good-service` as an optional (or default) client scope. +. Assign *good-service* as an optional (or default) client scope. + See <<_client_scopes_linking, Client Scopes Linking section>> for more details. -* You can optionally <<_client_scopes_evaluate, Evaluate Client Scopes>> and generate an example access token. `good-service` will be added to the audience of the generated access token if `good-service` is included in the _scope_ parameter, when you assigned it as an optional client scope. +* You can optionally <<_client_scopes_evaluate, Evaluate Client Scopes>> and generate an example access token. *good-service* will be added to the audience of the generated access token if *good-service* is included in the _scope_ parameter, when you assigned it as an optional client scope. -* In your `my-app` application, you must ensure that the _scope_ parameter is used. The value `good-service` must be included when you want to issue the token for accessing `good-service`. +* In your *my-app* application, you must ensure that the _scope_ parameter is used. The value *good-service* must be included when you want to issue the token for accessing *good-service*. + See: + diff --git a/server_admin/topics/clients/oidc/con-basic-settings.adoc b/server_admin/topics/clients/oidc/con-basic-settings.adoc index 3ca94b141a..6b6406faf3 100644 --- a/server_admin/topics/clients/oidc/con-basic-settings.adoc +++ b/server_admin/topics/clients/oidc/con-basic-settings.adoc @@ -2,20 +2,20 @@ ==== Basic Settings [role="_abstract"] -When you create an OIDC client, you see the following fields on the `Settings` tab. +When you create an OIDC client, you see the following fields on the *Settings* tab. -`Client ID`:: The alpha-numeric ID string that is used in OIDC requests and in the {project_name} database to identify the client. +*Client ID*:: The alpha-numeric ID string that is used in OIDC requests and in the {project_name} database to identify the client. -`Name`:: The name for the client in {project_name} UI screen. To localize +*Name*:: The name for the client in {project_name} UI screen. To localize the name, set up a replacement string value. For example, a string value such as $\{myapp}. See the link:{developerguide_link}[{developerguide_name}] for more information. -`Description`:: The description of the client. This setting can also be localized. +*Description*:: The description of the client. This setting can also be localized. -`Enabled`:: When turned off, the client cannot request authentication. +*Enabled*:: When turned off, the client cannot request authentication. -`Consent Required`:: When turned on, users see a consent page that they can use to grant access to that application. It will also display metadata so the user knows the exact information that the client can access. +*Consent Required*:: When turned on, users see a consent page that they can use to grant access to that application. It will also display metadata so the user knows the exact information that the client can access. -[[_access-type]]`Access Type`:: The type of OIDC client. +[[_access-type]]*Access Type*:: The type of OIDC client. _Confidential_:: For server-side clients that perform browser logins and require client secrets when making an Access Token Request. This setting should be used for server-side applications. @@ -26,24 +26,24 @@ _Public_:: _Bearer-only_:: The application allows only bearer token requests. When turned on, this application cannot participate in browser logins. -`Standard Flow Enabled`:: When enabled, clients can use the OIDC xref:_oidc-auth-flows-authorization[Authorization Code Flow]. +*Standard Flow Enabled*:: When enabled, clients can use the OIDC xref:_oidc-auth-flows-authorization[Authorization Code Flow]. -`Implicit Flow Enabled`:: When enabled, clients can use the OIDC xref:_oidc-auth-flows-implicit[Implicit Flow]. +*Implicit Flow Enabled*:: When enabled, clients can use the OIDC xref:_oidc-auth-flows-implicit[Implicit Flow]. -`Direct Access Grants Enabled`:: When enabled, clients can use the OIDC xref:_oidc-auth-flows-direct[Direct Access Grants]. +*Direct Access Grants Enabled*:: When enabled, clients can use the OIDC xref:_oidc-auth-flows-direct[Direct Access Grants]. -`Root URL`:: This value adds a prefix to any configured URLS that {project_name} uses. +*Root URL*:: This value adds a prefix to any configured URLS that {project_name} uses. -`Valid Redirect URIs`:: Required field. Enter a URL pattern and click *+* to add and *-* to remove existing URLs and click *Save*. You can use wildcards at the end of the URL pattern. For example $$http://host.com/*$$ +*Valid Redirect URIs*:: Required field. Enter a URL pattern and click *+* to add and *-* to remove existing URLs and click *Save*. You can use wildcards at the end of the URL pattern. For example $$http://host.com/*$$ + Exclusive redirect URL patterns are typically more secure. See xref:unspecific-redirect-uris_{context}[Unspecific Redirect URIs] for more information. -`Base URL`:: This URL is used when {project_name} needs to link to the client. +*Base URL*:: This URL is used when {project_name} needs to link to the client. -`Admin URL`:: Callback endpoint for a client. The server uses this URL to make callbacks like pushing revocation policies, performing backchannel logout, and other administrative operations. For {project_name} servlet adapters, this URL can be the root URL of the servlet application. +*Admin URL*:: Callback endpoint for a client. The server uses this URL to make callbacks like pushing revocation policies, performing backchannel logout, and other administrative operations. For {project_name} servlet adapters, this URL can be the root URL of the servlet application. For more information, see link:{adapterguide_link}[{adapterguide_name}]. -`Web Origins`:: Enter a URL pattern and click *+* to add and *-* to remove existing URLs. Click *Save*. +*Web Origins*:: Enter a URL pattern and click *+* to add and *-* to remove existing URLs. Click *Save*. + This option handles link:https://fetch.spec.whatwg.org/[Cross-Origin Resource Sharing (CORS)]. If browser JavaScript attempts an AJAX HTTP request to a server whose domain is different from the one that the diff --git a/server_admin/topics/clients/oidc/con-confidential-client-credentials.adoc b/server_admin/topics/clients/oidc/con-confidential-client-credentials.adoc index 4264308aa6..01428c8918 100644 --- a/server_admin/topics/clients/oidc/con-confidential-client-credentials.adoc +++ b/server_admin/topics/clients/oidc/con-confidential-client-credentials.adoc @@ -4,25 +4,25 @@ ==== 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. +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. .Credentials Tab image:{project_images}/client-credentials.png[Credentials Tab] -The `Client Authenticator` drop-down list specifies the type of credential to use for your client. +The *Client Authenticator* drop-down list specifies the type of credential to use for your client. *Client ID and Secret* -This choice is the default setting. The secret is automatically generated for you and the `Regenerate Secret` button recreates the secret if necessary. +This choice is the default setting. The secret is automatically generated for you and the *Regenerate Secret* button recreates the secret if necessary. *Signed JWT* .Signed JWT image:{project_images}/client-credentials-jwt.png[] -`Signed JWT` is "Signed Json Web Token". +*Signed JWT* is "Signed Json Web Token". -To use the `Signed JWT` credential type, a private key and certificate must be generated for the client. The private key is used to sign the JWT and the certificate is used by the server to verify the signature. Click the `Generate new keys and certificate` button to begin this process. +To use the *Signed JWT* credential type, a private key and certificate must be generated for the client. The private key is used to sign the JWT and the certificate is used by the server to verify the signature. Click the *Generate new keys and certificate* button to begin this process. .Generate Keys image:{project_images}/generate-client-keys.png[] @@ -30,21 +30,21 @@ image:{project_images}/generate-client-keys.png[] . Select the archive format you want to use. . Enter a key password. . Enter a store password. -. Click `Generate and Download`. +. Click *Generate and Download*. When you generate the keys, {project_name} will store the certificate and you must download the private key and certificate for your client. -You can also generate keys using an external tool and then import the client's certificate by clicking the `Import Certificate` button. +You can also generate keys using an external tool and then import the client's certificate by clicking the *Import Certificate* button. .Import Certificate image:{project_images}/import-client-cert.png[] . Select the archive format of the certificate. . Enter the store password. -. Select the certificate file by clicking the `Import File` button. -. Click `Import`. +. Select the certificate file by clicking the *Import File* button. +. Click *Import*. -It is not necessary to import a certificate if you click the `Use JWKS URL` switch. In this case, you can provide the URL where the public key is published in https://self-issued.info/docs/draft-ietf-jose-json-web-key.html[JWK] format. With this option, if the key is ever changed, {project_name} reimports the key. +It is not necessary to import a certificate if you click the *Use JWKS URL* switch. In this case, you can provide the URL where the public key is published in https://self-issued.info/docs/draft-ietf-jose-json-web-key.html[JWK] format. With this option, if the key is ever changed, {project_name} reimports the key. If you are using a client secured by {project_name} adapter, you can configure the JWKS URL in this format, assuming that https://myhost.com/myapp is the root URL of your client application: diff --git a/server_admin/topics/clients/oidc/proc-creating-oidc-client.adoc b/server_admin/topics/clients/oidc/proc-creating-oidc-client.adoc index 0725e864b8..33deee4f3d 100644 --- a/server_admin/topics/clients/oidc/proc-creating-oidc-client.adoc +++ b/server_admin/topics/clients/oidc/proc-creating-oidc-client.adoc @@ -4,39 +4,39 @@ To protect an application that uses the OpenID connect protocol, you create a client. .Procedure -. Click `Clients` in the left navigation pane. +. Click *Clients* in the left navigation pane. -. Click *Create* to go to the `Add Client` page. +. Click *Create* to go to the *Add Client* page. + .Add Client image:{project_images}/add-client-oidc.png[Add Client] -. Enter any name for `Client ID.` +. Enter any name for *Client ID.* -. Select `openid-connect` in the `Client Protocol` drop down box. +. Select *openid-connect* in the *Client Protocol* drop down box. -. Enter the base URL of your application in the `Root URL` field. +. Enter the base URL of your application in the *Root URL* field. . Click *Save*. ifdef::api-management[] . Configure the client permissions -.. Set `Access Type` to *confidential*. -.. Set `Standard Flow Enabled` to *OFF*. -.. Set `Direct Access Grants Enabled` to *OFF*. -.. set `Service Accounts Enabled` to *ON*. +.. Set *Access Type* to *confidential*. +.. Set *Standard Flow Enabled* to *OFF*. +.. Set *Direct Access Grants Enabled* to *OFF*. +.. set *Service Accounts Enabled* to *ON*. . Set the service account roles for the client: .. Click the *Service Account Roles* tab. .. Click *Client Roles* and enter *realm-management*. -.. Under `Available Roles`, select *manage-clients*. -.. Click *Add selected >>* to move *manage-clients* under `Assigned Roles`. +.. Under *Available Roles*, select *manage-clients*. +.. Click *Add selected >>* to move *manage-clients* under *Assigned Roles*. . Note the client credentials .. On the Credentials tab, make a note of the Secret field -.. On the `Settings` tab, make note the client ID that you assigned. +.. On the *Settings* tab, make note the client ID that you assigned. . Click *Save*. endif::[] ifdef::standalone[] -This action creates the client and bring you to the `Settings` +This action creates the client and bring you to the *Settings* tab. .Client Settings @@ -44,7 +44,7 @@ image:{project_images}/client-settings-oidc.png[Client Settings] [role="_additional-resources"] .Additional resources -* For more information about fields on the `Settings` tab, see xref:con-basic-settings_{context}[Basic Settings]. +* For more information about fields on the *Settings* tab, see xref:con-basic-settings_{context}[Basic Settings]. * For more information about the OIDC protocol, see xref:con-oidc_{context}[OpenID Connect]. endif::[] diff --git a/server_admin/topics/clients/oidc/proc-using-a-service-account.adoc b/server_admin/topics/clients/oidc/proc-using-a-service-account.adoc index 7bd35172e5..377b1c0f4e 100644 --- a/server_admin/topics/clients/oidc/proc-using-a-service-account.adoc +++ b/server_admin/topics/clients/oidc/proc-using-a-service-account.adoc @@ -8,14 +8,14 @@ Each OIDC client has a built-in _service account_, which allows it to obtain an .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`. -. Set the `Service Accounts Enabled` switch to ON. +. Click on the *Settings* tab. +. Set the <<_access-type, Access Type>> of your client is set to *confidential*. +. Set the *Service Accounts Enabled* switch to ON. . Click *Save*. . Configure your <<_client-credentials, client credentials>>. -. Click on the `Scope` tab. +. Click on the *Scope* tab. . Verify that you have roles or set Full Scope Allowed to ON. -. On the `Service Account Roles` tab, configure the roles available to this service account for your client. +. On the *Service Account Roles* tab, configure the roles available to this service account for your client. Roles from access tokens are the intersection of: @@ -24,9 +24,9 @@ Roles from access tokens are the intersection of: The REST URL to invoke is `/auth/realms/{realm-name}/protocol/openid-connect/token`. This URL must be invoked as a POST request and requires that you post the client credentials with the request. -By default, client credentials are represented by the clientId and clientSecret of the client in the `Authorization: Basic` header but you can also authenticate the client with a signed JWT assertion or any other custom mechanism for client authentication. +By default, client credentials are represented by the clientId and clientSecret of the client in the *Authorization: Basic* header but you can also authenticate the client with a signed JWT assertion or any other custom mechanism for client authentication. -You also need to set the `grant_type` parameter to "client_credentials" as per the OAuth2 specification. +You also need to set the *grant_type* parameter to "client_credentials" as per the OAuth2 specification. For example, the POST invocation to retrieve a service account can look like this: diff --git a/server_admin/topics/clients/proc-creating-client-scopes.adoc b/server_admin/topics/clients/proc-creating-client-scopes.adoc index a5754b5a58..be1da22ec4 100644 --- a/server_admin/topics/clients/proc-creating-client-scopes.adoc +++ b/server_admin/topics/clients/proc-creating-client-scopes.adoc @@ -3,14 +3,14 @@ [role="_abstract"] To create a client scope, follow these steps: -. Click `Client Scopes` in the left toolbar. +. Click *Client Scopes* in the left toolbar. + .Client Scopes List image:{project_images}/client-scopes-list.png[] + -. Click `Create`. +. Click *Create*. . Name your client scope. -. Click `Save`. +. Click *Save*. A _client scope_ has similar tabs to regular clients. You can define <<_protocol-mappers, protocol mappers>> and <<_role_scope_mappings, role scope mappings>>. These mappings can be inherited by other clients and are configured to inherit from this client scope. diff --git a/server_admin/topics/clients/proc-creating-mappers.adoc b/server_admin/topics/clients/proc-creating-mappers.adoc index 2c90b28ff5..35c67c46b8 100644 --- a/server_admin/topics/clients/proc-creating-mappers.adoc +++ b/server_admin/topics/clients/proc-creating-mappers.adoc @@ -4,10 +4,10 @@ You can add mapper types as follows: .Procedure -. Go to the `Mappers` tab. -. Click the `Create` button. +. Go to the *Mappers* tab. +. Click the *Create* button. + .Add Mapper image:{project_images}/add-mapper.png[] + -. Select a `Mapper Type` from the list box. +. Select a *Mapper Type* from the list box. diff --git a/server_admin/topics/clients/proc-evaluating-client-scopes.adoc b/server_admin/topics/clients/proc-evaluating-client-scopes.adoc index 76adfdb819..587a7f988c 100644 --- a/server_admin/topics/clients/proc-evaluating-client-scopes.adoc +++ b/server_admin/topics/clients/proc-evaluating-client-scopes.adoc @@ -1,21 +1,21 @@ [id="proc_evaluating_client_scopes_{context}"] [role="_abstract"] -The `Mappers` tab contains the protocol mappers and the `Scope` tab contains the role scope mappings declared for this client. They do not contain the mappers and scope mappings inherited from client scopes. It is possible to see the effective protocol mappers (that is the protocol mappers defined on the client itself as well as inherited from the linked client scopes) and the effective role scope mappings used when generating a token for a client. +The *Mappers* tab contains the protocol mappers and the *Scope* tab contains the role scope mappings declared for this client. They do not contain the mappers and scope mappings inherited from client scopes. It is possible to see the effective protocol mappers (that is the protocol mappers defined on the client itself as well as inherited from the linked client scopes) and the effective role scope mappings used when generating a token for a client. .Procedure -. Click the `Client Scopes` tab for the client. -. Open the sub-tab `Evaluate`. +. Click the *Client Scopes* tab for the client. +. Open the sub-tab *Evaluate*. . Select the optional client scopes that you want to apply. -This will also show you the value of the `scope` parameter. This parameter needs to be sent from the application to the {project_name} OpenID Connect authorization endpoint. +This will also show you the value of the *scope* parameter. This parameter needs to be sent from the application to the {project_name} OpenID Connect authorization endpoint. .Evaluating Client Scopes image:{project_images}/client-scopes-evaluate.png[] [NOTE] ==== -To send a custom value for a `scope` parameter from your application, see the link:{adapterguide_link}#_params_forwarding[parameters forwarding section], for servlet adapters or the link:{adapterguide_link}#_javascript_adapter[javascript adapter section], for javascript adapters. +To send a custom value for a *scope* parameter from your application, see the link:{adapterguide_link}#_params_forwarding[parameters forwarding section], for servlet adapters or the link:{adapterguide_link}#_javascript_adapter[javascript adapter section], for javascript adapters. ==== -An example of a generated access token, specific to the user, client and `scope` parameter, is automatically generated under the `Generated Access Token` tab. +An example of a generated access token, specific to the user, client and *scope* parameter, is automatically generated under the *Generated Access Token* tab. diff --git a/server_admin/topics/clients/proc-generating-client-adapter-config.adoc b/server_admin/topics/clients/proc-generating-client-adapter-config.adoc index 91b36b6fbe..73c686ba2f 100644 --- a/server_admin/topics/clients/proc-generating-client-adapter-config.adoc +++ b/server_admin/topics/clients/proc-generating-client-adapter-config.adoc @@ -7,10 +7,10 @@ {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. -. Go to the `Installation` tab of the client you want to generate configuration for. +. Go to the *Installation* tab of the client you want to generate configuration for. + image:{project_images}/client-installation.png[] + -. Select the `Format Option` you want configuration generated for. +. Select the *Format Option* you want configuration generated for. All {project_name} client adapters for OIDC and SAML are supported. The mod-auth-mellon Apache HTTPD adapter for SAML is supported as well as standard SAML entity descriptor files. diff --git a/server_admin/topics/clients/proc-updating-default-scopes.adoc b/server_admin/topics/clients/proc-updating-default-scopes.adoc index d9112c6493..ec95c131e5 100644 --- a/server_admin/topics/clients/proc-updating-default-scopes.adoc +++ b/server_admin/topics/clients/proc-updating-default-scopes.adoc @@ -1,13 +1,13 @@ [id="proc_updating_client_scopes_{context}"] [role="_abstract"] -`Realm Default Client Scopes` allow you to define sets of client scopes which are automatically linked to newly created clients. +*Realm Default Client Scopes* allow you to define sets of client scopes which are automatically linked to newly created clients. .Procedure -. Click the `Client Scopes` tab for the client. -. Click `Default Client Scopes`. +. Click the *Client Scopes* tab for the client. +. Click *Default Client Scopes*. -From here, select the client scopes that you want to add as `Default Client Scopes` to newly created clients and `Optional Client Scopes`. +From here, select the client scopes that you want to add as *Default Client Scopes* to newly created clients and *Optional Client Scopes*. .Default Client Scopes image:{project_images}/client-scopes-default.png[] diff --git a/server_admin/topics/clients/saml/idp-initiated-login.adoc b/server_admin/topics/clients/saml/idp-initiated-login.adoc index de4ca73574..d489764982 100644 --- a/server_admin/topics/clients/saml/idp-initiated-login.adoc +++ b/server_admin/topics/clients/saml/idp-initiated-login.adoc @@ -2,21 +2,21 @@ ==== 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`. +In the *Settings* tab for your client, you need to specify the *IDP Initiated SSO URL Name*. This is a simple string with no whitespace in it. After this you can reference your client at the following URL: `root/auth/realms/{realm}/protocol/saml/clients/{url-name}` The IDP initiated login implementation prefers _POST_ over _REDIRECT_ binding (check <<_saml, saml bindings>> for more information). Therefore the final binding and SP URL are selected in the following way: -1. If the specific `Assertion Consumer Service POST Binding URL` is defined (inside `Fine Grain SAML Endpoint Configuration` section +1. If the specific *Assertion Consumer Service POST Binding URL* is defined (inside *Fine Grain SAML Endpoint Configuration* section of the client settings) _POST_ binding is used through that URL. -2. If the general `Master SAML Processing URL` is specified then _POST_ binding is used again throught this general URL. -3. As the last resort, if the `Assertion Consumer Service Redirect Binding URL` is configured (inside -`Fine Grain SAML Endpoint Configuration`) _REDIRECT_ binding is used with this URL. +2. If the general *Master SAML Processing URL* is specified then _POST_ binding is used again throught this general URL. +3. As the last resort, if the *Assertion Consumer Service Redirect Binding URL* is configured (inside +*Fine Grain SAML Endpoint Configuration*) _REDIRECT_ binding is used with this URL. -If your client requires a special relay state, you can also configure this on the `Settings` tab in the `IDP Initiated SSO Relay State` field. -Alternatively, browsers can specify the relay state in a `RelayState` query parameter, i.e. +If your client requires a special relay state, you can also configure this on the *Settings* tab in the *IDP Initiated SSO Relay State* field. +Alternatively, browsers can specify the relay state in a *RelayState* query parameter, i.e. `root/auth/realms/{realm}/protocol/saml/clients/{url-name}?RelayState=thestate`. When using <<_identity_broker,identity brokering>>, it is possible to set up an IDP Initiated Login for a client from an @@ -25,15 +25,15 @@ to set up the client for application IDP Initiated Login that will point to a sp representing IDP Initiated Login endpoint for a selected client at the brokering IDP. This means that in client settings at the external IDP: -* `IDP Initiated SSO URL Name` is set to a name that will be published as IDP Initiated Login initial point, -* `Assertion Consumer Service POST Binding URL` in the `Fine Grain SAML Endpoint Configuration` section has +* *IDP Initiated SSO URL Name* is set to a name that will be published as IDP Initiated Login initial point, +* *Assertion Consumer Service POST Binding URL* in the *Fine Grain SAML Endpoint Configuration* section has to be set to the following URL: `broker-root/auth/realms/{broker-realm}/broker/{idp-name}/endpoint/clients/{client-id}`, where: ** _broker-root_ is base broker URL ** _broker-realm_ is name of the realm at broker where external IDP is declared ** _idp-name_ is name of the external IDP at broker - ** _client-id_ is the value of `IDP Initiated SSO URL Name` attribute of the SAML client defined at broker. It is + ** _client-id_ is the value of *IDP Initiated SSO URL Name* attribute of the SAML client defined at broker. It is this client, which will be made available for IDP Initiated Login from the external IDP. Please note that you can import basic client settings from the brokering IDP into client settings of the external IDP - diff --git a/server_admin/topics/clients/saml/proc-creating-saml-client.adoc b/server_admin/topics/clients/saml/proc-creating-saml-client.adoc index 9c8adb3a1b..463a03195f 100644 --- a/server_admin/topics/clients/saml/proc-creating-saml-client.adoc +++ b/server_admin/topics/clients/saml/proc-creating-saml-client.adoc @@ -6,90 +6,90 @@ 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. .Procedure -. Click `Clients` in the left navigation pane. +. Click *Clients* in the left navigation pane. -. Click *Create* to go to the `Add Client` page. +. Click *Create* to go to the *Add Client* page. + .Add Client image:{project_images}/add-client-saml.png[] -. Enter the `Client ID` of the client. This is often a URL and is the expected `issuer` value in SAML requests sent by the application. +. Enter the *Client ID* of the client. This is often a URL and is the expected *issuer* value in SAML requests sent by the application. -. Select `saml` in the `Client Protocol` drop down box. +. Select *saml* in the *Client Protocol* drop down box. -. Enter the `Client SAML Endpoint` URL. This URL is where you want the {project_name} server to send SAML requests and responses. Generally, applications have one URL for processing SAML requests. Multiple URLs can be set in the `Settings` tab of the client. +. Enter the *Client SAML Endpoint* URL. This URL is where you want the {project_name} server to send SAML requests and responses. Generally, applications have one URL for processing SAML requests. Multiple URLs can be set in the *Settings* tab of the client. -. Click *Save*. This action creates the client and brings you to the `Settings` tab. +. Click *Save*. This action creates the client and brings you to the *Settings* tab. + .Client Settings image:{project_images}/client-settings-saml.png[] + The following list describes each setting: + -`Client ID`:: The alpha-numeric ID string that is used in OIDC requests and in the {project_name} database to identify the client. This value must match the issuer value sent with AuthNRequests. {project_name} pulls the issuer from the Authn SAML request and match it to a client by this value. +*Client ID*:: The alpha-numeric ID string that is used in OIDC requests and in the {project_name} database to identify the client. This value must match the issuer value sent with AuthNRequests. {project_name} pulls the issuer from the Authn SAML request and match it to a client by this value. -`Name`:: The name for the client in a {project_name} UI screen. To localize +*Name*:: The name for the client in a {project_name} UI screen. To localize the name, set up a replacement string value. For example, a string value such as $\{myapp}. See the link:{developerguide_link}[{developerguide_name}] for more information. -`Description`:: The description of the client. This setting can also be localized. +*Description*:: The description of the client. This setting can also be localized. -`Enabled`:: When set to OFF, the client cannot request authentication. +*Enabled*:: When set to OFF, the client cannot request authentication. -`Consent Required`:: When set to ON, users see a consent page that grants access to that application. The page also displays the metadata of the information that the client can access. If you have ever done a social login to Facebook, you often see a similar page. Red Hat Single Sign-On provides the same functionality. +*Consent Required*:: When set to ON, users see a consent page that grants access to that application. The page also displays the metadata of the information that the client can access. If you have ever done a social login to Facebook, you often see a similar page. Red Hat Single Sign-On provides the same functionality. -`Include AuthnStatement`:: SAML login responses may specify the authentication method used, such as password, as well as timestamps of the login and the session expiration. -This switch is enabled by default, so that the `AuthnStatement` element will be included in login responses. Setting this to OFF prevents clients from determining the maximum session length, which can create client sessions that do not expire. +*Include AuthnStatement*:: SAML login responses may specify the authentication method used, such as password, as well as timestamps of the login and the session expiration. +This switch is enabled by default, so that the *AuthnStatement* element will be included in login responses. Setting this to OFF prevents clients from determining the maximum session length, which can create client sessions that do not expire. -`Sign Documents`:: When set to ON, {project_name} signs the document using the realms private key. +*Sign Documents*:: When set to ON, {project_name} signs the document using the realms private key. -`Optimize REDIRECT signing key lookup`:: When set to ON, the SP messages include the {project_name} native extension. This extension contains a hint with the signing key ID. The SP uses the extension for signature validation instead of attempting to validate the signature using keys. +*Optimize REDIRECT signing key lookup*:: When set to ON, the SP messages include the {project_name} native extension. This extension contains a hint with the signing key ID. The SP uses the extension for signature validation instead of attempting to validate the signature using keys. + This option applies to REDIRECT bindings where the signature is transferred in query parameters and this information is not found in the signature information. This is contrary to POST binding messages where key ID is always included in document signature. + -This option is used when {project_name} server and adapter provide the IDP and SP. This option is only relevant when `Sign Documents` is set to ON. +This option is used when {project_name} server and adapter provide the IDP and SP. This option is only relevant when *Sign Documents* is set to ON. -`Sign Assertions`:: The assertion is signed and embedded in the SAML XML Auth response. +*Sign Assertions*:: The assertion is signed and embedded in the SAML XML Auth response. -`Signature Algorithm`:: The algorithm used in signing SAML documents. +*Signature Algorithm*:: The algorithm used in signing SAML documents. -`SAML Signature Key Name`:: Signed SAML documents sent using POST binding contain the identification of the signing key in the `KeyName` element. This action can be controlled by the `SAML Signature Key Name` option. This option controls the contents of the `Keyname`. +*SAML Signature Key Name*:: Signed SAML documents sent using POST binding contain the identification of the signing key in the *KeyName* element. This action can be controlled by the *SAML Signature Key Name* option. This option controls the contents of the *Keyname*. + -- -* _KEY_ID_:: The `KeyName` contains the key ID. This option is the default option. -* _CERT_SUBJECT_:: The `KeyName` contains the subject from the certificate corresponding to the realm key. This option is expected by Microsoft Active Directory Federation Services. -* _NONE_:: The `KeyName` hint is completely omitted from the SAML message. +* _KEY_ID_:: The *KeyName* contains the key ID. This option is the default option. +* _CERT_SUBJECT_:: The *KeyName* contains the subject from the certificate corresponding to the realm key. This option is expected by Microsoft Active Directory Federation Services. +* _NONE_:: The *KeyName* hint is completely omitted from the SAML message. -- + -`Canonicalization Method`:: The canonicalization method for XML signatures. +*Canonicalization Method*:: The canonicalization method for XML signatures. -`Encrypt Assertions`:: Encrypts the assertions in SAML documents with the realms private key. The AES algorithm uses a key size of 128 bits. +*Encrypt Assertions*:: Encrypts the assertions in SAML documents with the realms private key. The AES algorithm uses a key size of 128 bits. -`Client Signature Required`:: If this switch is set to ON, documents coming from a client are expected to be signed. {project_name} validates this signature using the client public key or certificate set up in the `SAML Keys` tab. +*Client Signature Required*:: If this switch is set to ON, documents coming from a client are expected to be signed. {project_name} validates this signature using the client public key or certificate set up in the *SAML Keys* tab. -`Force POST Binding`:: By default, {project_name} responds using the initial SAML binding of the original request. By setting this switch to ON, {project_name} responds using the SAML POST binding even if the original request used the redirect binding. +*Force POST Binding*:: By default, {project_name} responds using the initial SAML binding of the original request. By setting this switch to ON, {project_name} responds using the SAML POST binding even if the original request used the redirect binding. -`Front Channel Logout`:: If this switch is set to ON, the application requires a browser redirect to perform a logout. For example, the application may require a cookie to be reset which could only be done via a redirect. If this switch is set to OFF, {project_name} invokes a background SAML request to log out of the application. +*Front Channel Logout*:: If this switch is set to ON, the application requires a browser redirect to perform a logout. For example, the application may require a cookie to be reset which could only be done via a redirect. If this switch is set to OFF, {project_name} invokes a background SAML request to log out of the application. -`Force Name ID Format`:: If a request has a name ID policy, ignore it and use the value configured in the admin console under `Name ID Format`. +*Force Name ID Format*:: If a request has a name ID policy, ignore it and use the value configured in the admin console under *Name ID Format*. -`Name ID Format`:: The Name ID Format for the subject. This format is used if no name ID policy is specified in a request, or if the Force Name ID Format attribute is set to ON. +*Name ID Format*:: The Name ID Format for the subject. This format is used if no name ID policy is specified in a request, or if the Force Name ID Format attribute is set to ON. -`Root URL`:: When {project_name} uses a configured relative URL, this value is prepended to the URL. +*Root URL*:: When {project_name} uses a configured relative URL, this value is prepended to the URL. -`Valid Redirect URIs`:: Enter a URL pattern and click the + sign to add. Click the - sign to remove. Click the `Save` button to save these changes. +*Valid Redirect URIs*:: Enter a URL pattern and click the + sign to add. Click the - sign to remove. Click the *Save* button to save these changes. Wildcards values are allowed only at the end of a URL. For example, http://host.com/*$$. This field is used when the exact SAML endpoints are not registered and {project_name} pulls the Assertion Consumer URL from a request. -`Base URL`:: If {project_name} needs to link to a client, this URL is used. +*Base URL*:: If {project_name} needs to link to a client, this URL is used. -`Master SAML Processing URL`:: This URL is used for all SAML requests and the response is directed to the SP. It is used as the Assertion Consumer Service URL and the Single Logout Service URL. +*Master SAML Processing URL*:: This URL is used for all SAML requests and the response is directed to the SP. It is used as the Assertion Consumer Service URL and the Single Logout Service URL. + If login requests contain the Assertion Consumer Service URL then those login requests will take precedence. This URL must be validated by a registered Valid Redirect URI pattern. -`Assertion Consumer Service POST Binding URL`:: POST Binding URL for the Assertion Consumer Service. +*Assertion Consumer Service POST Binding URL*:: POST Binding URL for the Assertion Consumer Service. -`Assertion Consumer Service Redirect Binding URL`:: Redirect Binding URL for the Assertion Consumer Service. +*Assertion Consumer Service Redirect Binding URL*:: Redirect Binding URL for the Assertion Consumer Service. -`Logout Service POST Binding URL`:: POST Binding URL for the Logout Service. +*Logout Service POST Binding URL*:: POST Binding URL for the Logout Service. -`Logout Service Redirect Binding URL`:: Redirect Binding URL for the Logout Service. +*Logout Service Redirect Binding URL*:: Redirect Binding URL for the Logout Service. diff --git a/server_admin/topics/clients/saml/proc-using-an-entity-descriptor.adoc b/server_admin/topics/clients/saml/proc-using-an-entity-descriptor.adoc index 0be47d651c..35ff250201 100644 --- a/server_admin/topics/clients/saml/proc-using-an-entity-descriptor.adoc +++ b/server_admin/topics/clients/saml/proc-using-an-entity-descriptor.adoc @@ -4,13 +4,13 @@ [role="_abstract"] Instead of registering a SAML 2.0 client manually, you can import the client using a standard SAML Entity Descriptor XML file. -The Add Client page includes an `Import` option. +The Add Client page includes an *Import* option. .Add Client image:{project_images}/add-client-saml.png[] .Procedure -. Click the `Select File` button. +. Click the *Select File* button. . Load the file that contains the XML entity descriptor information. . Review the information to ensure everything is set up correctly.