anchor.diff:  NOTE: The values used below are meant to be an example and are not intended to apply to
   every use case. The details below the configuration snippet provide insights and suggestions
   to help you pick the proper values, depending on your OP configuration.
  +
  +[source, yaml]
  +-------------------------------------------------------------------------------------
  +xpack.security.authc.realms.oidc.oidc1:
  +  order: 2
  +  rp.client_id: "the_client_id"
  +  rp.response_type: code
  +  rp.redirect_uri: "https://kibana.example.org:5601/api/security/v1/oidc"
  +  op.issuer: "https://op.example.org"
  +  op.authorization_endpoint: "https://op.example.org/oauth2/v1/authorize"
  +  op.token_endpoint: "https://op.example.org/oauth2/v1/token"
  +  op.jwkset_path: oidc/jwkset.json
  +  op.userinfo_endpoint: "https://op.example.org/oauth2/v1/userinfo"
  +  op.endsession_endpoint: "https://op.example.org/oauth2/v1/logout"
  +  rp.post_logout_redirect_uri: "https://kibana.example.org:5601/logged_out"
  +  claims.principal: sub
  +  claims.groups: "http://example.info/claims/groups"
  +-------------------------------------------------------------------------------------
  +
  +The configuration values used in the example above are:
  +
  +xpack.security.authc.realms.oidc.oidc1::
  +    This defines a new `oidc` authentication realm named "oidc1".
  +    See <<realms>> for more explanation of realms.
  +
  +order::
  +    You should define a unique order on each realm in your authentication chain.
  +    It is recommended that the OpenID Connect realm be at the bottom of your authentication
  +    chain (that is, that it has the _highest_ order).
  +
  +rp.client_id::
  +    This, usually opaque, arbitrary string, is the Client Identifier that was assigned to the Elastic Stack RP by the OP upon
  +    registration.
  +
  +rp.response_type::
  +    This is an identifier that controls which OpenID Connect authentication flow this RP supports and also
  +    which flow this RP requests the OP should follow. Supported values are
  +    - `code`, which means that the RP wants to use the Authorization Code flow. If your OP supports the
  +       Authorization Code flow, you should select this instead of the Implicit Flow.
  +    - `id_token token` which means that the RP wants to use the Implicit flow and we also request an oAuth2
  +       access token from the OP, that we can potentially use for follow up requests ( UserInfo ). This
  +       should be selected if the OP offers a UserInfo endpoint in its configuration, or if you know that
  +       the claims you will need to use for role mapping are not available in the ID Token.
  +    - `id_token` which means that the RP wants to use the Implicit flow, but is not interested in getting
  +       an oAuth2 token too. Select this if you are certain that all necessary claims will be contained in
  +       the ID Token or if the OP doesn't offer a User Info endpoint.
  +
  +rp.redirect_uri::
  +    The redirect URI where the OP will redirect the browser after authentication. This needs to be
  +    _exactly_ the same as the one <<oidc-guide-op, configured with the OP upon registration>> and will
  +    typically be +$\{kibana-url}/api/security/v1/oidc+ where _$\{kibana-url}_ is the base URL for your {kib} instance
  +
  +op.issuer::
  +    A verifiable Identifier for your OpenID Connect Provider. An Issuer Identifier is usually a case sensitive URL.
  +    The value for this setting should be provided by your OpenID Connect Provider.
  +
  +op.authorization_endpoint::
  +    The URL for the Authorization Endpoint in the OP. This is where the user's browser
  +    will be redirected to start the authentication process. The value for this setting should be provided by your
  +    OpenID Connect Provider.
  +
  +op.token_endpoint::
  +    The URL for the Token Endpoint in the OpenID Connect Provider. This is the endpoint where
  +    {es} will send a request to exchange the code for an ID Token, in the case where the Authorization Code
  +    flow is used. The value for this setting should be provided by your OpenID Connect Provider.
  +
  +op.jwkset_path::
  +    The path to a file or a URL containing a JSON Web Key Set with the key material that the OpenID Connect
  +    Provider uses for signing tokens and claims responses. If a path is set, it is resolved relative to the {es}
  +    config directory.
  +    {es} will automatically monitor this file for changes and will reload the configuration whenever
  +    it is updated. Your OpenID Connect Provider should provide you with this file or a URL where it is available.
  +
  +op.userinfo_endpoint::
  +    (Optional) The URL for the UserInfo Endpoint in the OpenID Connect Provider. This is the endpoint of the OP that
  +    can be queried to get further user information, if required. The value for this setting should be provided by your
  +     OpenID Connect Provider.
  +
  +op.endsession_endpoint::
  +    (Optional) The URL to the End Session Endpoint in the OpenID Connect Provider. This is the endpoint where the user's
  +    browser will be redirected after local logout, if the realm is configured for RP initiated Single Logout and
  +    the OP supports it. The value for this setting should be provided by your OpenID Connect Provider.
  +
  +rp.post_logout_redirect_uri::
  +    (Optional) The Redirect URL where the OpenID Connect Provider should redirect the user after a
  +    successful Single Logout (assuming `op.endsession_endpoint` above is also set). This should be set to a value that
  +    will not trigger a new OpenID Connect Authentication, such as +$\{kibana-url}/logged_out+ where _$\{kibana-url}_ is
  +    the base URL for your {kib} instance.
  +
  +claims.principal:: See <<oidc-claims-mapping>>.
  +claims.groups:: See <<oidc-claims-mapping>>.
  +
  +A final piece of configuration of the OpenID Connect realm is to set the `Client Secret` that was assigned
  +to the RP during registration in the OP. This is a secure setting and as such is not defined in the realm
  +configuration in `elasticsearch.yml` but added to the {ref}/secure-settings.html[elasticsearch keystore].
  +For instance
  +
  +
  +[source,sh]
  +----
  +bin/elasticsearch-keystore add xpack.security.authc.realms.oidc.oidc1.rp.client_secret
  +----
  +
  +
  +NOTE: According to the OpenID Connect specification, the OP should also make their configuration
  +available at a well known URL, which is the concatenation of their `Issuer` value with the
  +`.well-known/openid-configuration` string. For example: `https://op.org.com/.well-known/openid-configuration`
  +That document should contain all the necessary information to configure the OpenID Connect realm in {es}.
  +
  +
  +[[oidc-claims-mapping]]
  +==== Claims mapping
  +
  +===== Claims and scopes
  +
  +When authenticating to {kib} using OpenID Connect, the OP will provide information about the user
  +in the form of OpenID Connect Claims, that can be included either in the ID Token, or be retrieved from the
  +UserInfo endpoint of the OP. The claim is defined as a piece of information asserted by the OP
  +for the authenticated user. Simply put, a claim is a name/value pair that contains information about
  +the user. Related to claims, we also have the notion of OpenID Connect Scopes. Scopes are identifiers
  +that are used to request access to specific lists of claims. The standard defines a set of scope
  +identifiers that can be requested. The only mandatory one is `openid`, while commonly used ones are
  +`profile` and `email`. The `profile` scope requests access to the `name`,`family_name`,`given_name`,`middle_name`,`nickname`,
  +`preferred_username`,`profile`,`picture`,`website`,`gender`,`birthdate`,`zoneinfo`,`locale`, and `updated_at` claims.
  +The `email` scope requests access to the `email` and `email_verified` claims. The process is that
  +the RP requests specific scopes during the authentication request. If the OP Privacy Policy
  +allows it and the authenticating user consents to it, the related claims are returned to the
  +RP (either in the ID Token or as a UserInfo response).
  +
  +The list of the supported claims will vary depending on the OP you are using, but you can expect
  +the https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims[Standard Claims] to be
  +largely supported.
  +
  +[[oidc-claim-to-property]]
  +===== Mapping claims to user properties
  +
  +The goal of claims mapping is to configure {es} in such a way as to be able to map the values of
  +specified returned claims to one of the <<oidc-user-properties, user properties>> that are supported
  +by {es}. These user properties are then utilized to identify the user in the {kib} UI or the audit
  +logs, and can also be used to create <<oidc-role-mapping, role mapping>> rules.
  +
  +The recommended steps for configuring OpenID Claims mapping are as follows:
  +
  +. Consult your OP configuration to see what claims it might support. Note that
  +  the list provided in the OP's metadata or in the configuration page of the OP
  +  is a list of potentially supported claims. However, for privacy reasons it might
  +  not be a complete one, or not all supported claims will be available for all
  +  authenticated users.
  +
  +. Read through the list of <<oidc-user-properties, user properties>> that {es}
  +  supports, and decide which of them are useful to you, and can be provided by
  +  your OP in the form of claims. At a _minimum_, the `principal` user property
  +  is required.
  +
  +. Configure your OP to "release" those claims to your {stack} Relying
  +  party. This process greatly varies by provider. You can use a static
  +  configuration while others will support that the RP requests the scopes that
  +  correspond to the claims to be "released" on authentication time. See
  +  {ref}/security-settings.html#ref-oidc-settings[`rp.requested_scopes`] for details about how
  +  to configure the scopes to request. To ensure interoperability and minimize
  +  the errors, you should only request scopes that the OP supports, and which you
  +  intend to map to {es} user properties.
  +
  +. Configure the OpenID Connect realm in {es} to associate the {es} user properties (see
  +  <<oidc-user-properties, the listing>> below), to the name of the claims that your
  +  OP will release. In the example above, we have configured the `principal` and
  +  `groups` user properties as follows:
  +
  +  .. `claims.principal: sub` : This instructs {es} to look for the OpenID Connect claim named `sub`
  +     in the ID Token that the OP issued for the user ( or in the UserInfo response ) and assign the
  +     value of this claim to the `principal` user property. `sub` is a commonly used claim for the
  +     principal property as it is an identifier of the user in the OP and it is also a required
  +     claim of the ID Token, thus offering guarantees that it will be available. It is, however,
  +     only used as an example here, the OP may provide another claim that is a better fit for your needs.
  +
  +  .. `claims.groups: "http://example.info/claims/groups"` : Similarly, this instructs {es} to look
  +     for the claim with the name `http://example.info/claims/groups` (note that this is a URI - an
  +     identifier, treated as a string and not a URL pointing to a location that will be retrieved)
  +     either in the ID Token or in the UserInfo response, and map the value(s) of it to the user
  +     property `groups` in {es}. There is no standard claim in the specification that is used for
  +     expressing roles or group memberships of the authenticated user in the OP, so the name of the
  +     claim that should be mapped here, will vary greatly between providers. Consult your OP
  +     documentation for more details.
  +
  +[[oidc-user-properties]]
  +===== {es} user properties
  +
  +The {es} OpenID Connect realm can be configured to map OpenID Connect claims to the
  +following properties on the authenticated user:
  +
  +principal:: _(Required)_
  +    This is the _username_ that will be applied to a user that authenticates
  +    against this realm.
  +    The `principal` appears in places such as the {es} audit logs.
  +
  +NOTE: If the principal property fails to be mapped from a claim, the authentication fails.
  +
  +groups:: _(Recommended)_
  +    If you wish to use your OP's concept of groups or roles as the basis for a
  +    user's {es} privileges, you should map them with this property.
  +    The `groups` are passed directly to your <<oidc-role-mapping, role mapping rules>>.
  +
  +name:: _(Optional)_ The user's full name.
  +mail:: _(Optional)_ The user's email address.
  +dn:: _(Optional)_ The user's X.500 _Distinguished Name_.
  +
  +
  +===== Extracting partial values from OpenID Connect claims
  +
  +There are some occasions where the value of a claim may contain more information
  +than you wish to use within {es}. A common example of this is one where the
  +OP works exclusively with email addresses, but you would like the user's
  +`principal` to use the _local-name_ part of the email address.
  +For example if their email address was `james.wong@staff.example.com`, then you
  +would like their principal to simply be `james.wong`.
  +
  +This can be achieved using the `claim_patterns` setting in the {es}
  +realm, as demonstrated in the realm configuration below:
   
   [source, yaml]
   -------------------------------------------------------------------------------------
  
positive.code:   op.endsession_endpoint: "https://op.example.org/oauth2/v1/logout"
    op.issuer: "https://op.example.org"
    op.jwkset_path: oidc/jwkset.json
    claims.principal: sub
    claims.groups: "http://example.info/claims/groups"
  -------------------------------------------------------------------------------------
  
  The configuration values used in the example above are:
  
  xpack.security.authc.realms.oidc.oidc1::
      This defines a new `oidc` authentication realm named "oidc1".
      See <<realms>> for more explanation of realms.
  
  order::
      You should define a unique order on each realm in your authentication chain.
      It is recommended that the OpenID Connect realm be at the bottom of your authentication
      chain (that is, that it has the _highest_ order).
  
  rp.client_id::
      This, usually opaque, arbitrary string, is the Client Identifier that was assigned to the Elastic Stack RP by the OP upon
      registration.
  
  rp.response_type::
      This is an identifier that controls which OpenID Connect authentication flow this RP supports and also
      which flow this RP requests the OP should follow. Supported values are
      - `code`, which means that the RP wants to use the Authorization Code flow. If your OP supports the
         Authorization Code flow, you should select this instead of the Implicit Flow.
      - `id_token token` which means that the RP wants to use the Implicit flow and we also request an oAuth2
         access token from the OP, that we can potentially use for follow up requests ( UserInfo ). This
         should be selected if the OP offers a UserInfo endpoint in its configuration, or if you know that
         the claims you will need to use for role mapping are not available in the ID Token.
      - `id_token` which means that the RP wants to use the Implicit flow, but is not interested in getting
         an oAuth2 token too. Select this if you are certain that all necessary claims will be contained in
         the ID Token or if the OP doesn't offer a User Info endpoint.
  
  rp.redirect_uri::
      The redirect URI where the OP will redirect the browser after authentication. This needs to be
      _exactly_ the same as the one <<oidc-guide-op, configured with the OP upon registration>> and will
      typically be +$\{kibana-url}/api/security/v1/oidc+ where _$\{kibana-url}_ is the base URL for your {kib} instance
  
  op.authorization_endpoint::
      The URL for the Authorization Endpoint in the OP. This is where the user's browser
      will be redirected to start the authentication process. The value for this setting should be provided by your
      OpenID Connect Provider.
  
  op.token_endpoint::
      The URL for the Token Endpoint in the OpenID Connect Provider. This is the endpoint where
      {es} will send a request to exchange the code for an ID Token, in the case where the Authorization Code
      flow is used. The value for this setting should be provided by your OpenID Connect Provider.
  
  op.userinfo_endpoint::
      (Optional) The URL for the UserInfo Endpoint in the OpenID Connect Provider. This is the endpoint of the OP that
      can be queried to get further user information, if required. The value for this setting should be provided by your
       OpenID Connect Provider.
  
  op.endsession_endpoint::
      (Optional) The URL to the End Session Endpoint in the OpenID Connect Provider. This is the endpoint where the user's
      browser will be redirected after local logout, if the realm is configured for RP initiated Single Logout and
      the OP supports it. The value for this setting should be provided by your OpenID Connect Provider.
  
  op.jwkset_path::
      The path to a file containing a JSON Web Key Set with the key material that the OpenID Connect
      Provider uses for signing tokens and claims responses. The path is resolved relative to the {es}
      config directory.
      {es} will automatically monitor this file for changes and will reload the configuration whenever
      it is updated. Your OpenID Connect Provider should provide you with this file.
  
  claims.principal:: See <<oidc-claims-mapping>>.
  claims.groups:: See <<oidc-claims-mapping>>.
  
  A final piece of configuration of the OpenID Connect realm is to set the `Client Secret` that was assigned
  to the RP during registration in the OP. This is a secure setting and as such is not defined in the realm
  configuration in `elasticsearch.yml` but added to the {ref}/secure-settings.html[elasticsearch keystore].
  For instance
  
  
  [source,sh]
  ----
  bin/elasticsearch-keystore add xpack.security.authc.realms.oidc.oidc1.rp.client_secret
  ----
  
  
  NOTE: According to the OpenID Connect specification, the OP should also make their configuration
  available at a well known URL, which is the concatenation of their `Issuer` value with the
  `.well-known/openid-configuration` string. For example: `https://op.org.com/.well-known/openid-configuration`
  That document should contain all the necessary information to configure the OpenID Connect realm in {es}.
  
  
  [[oidc-claims-mapping]]
  ==== Claims mapping
  
  ===== Claims and scopes
  
  When authenticating to {kib} using OpenID Connect, the OP will provide information about the user
  in the form of OpenID Connect Claims, that can be included either in the ID Token, or be retrieved from the
  UserInfo endpoint of the OP. The claim is defined as a piece of information asserted by the OP
  for the authenticated user. Simply put, a claim is a name/value pair that contains information about
  the user. Related to claims, we also have the notion of OpenID Connect Scopes. Scopes are identifiers
  that are used to request access to specific lists of claims. The standard defines a set of scope
  identifiers that can be requested. The only mandatory one is `openid`, while commonly used ones are
  `profile` and `email`. The `profile` scope requests access to the `name`,`family_name`,`given_name`,`middle_name`,`nickname`,
  `preferred_username`,`profile`,`picture`,`website`,`gender`,`birthdate`,`zoneinfo`,`locale`, and `updated_at` claims.
  The `email` scope requests access to the `email` and `email_verified` claims. The process is that
  the RP requests specific scopes during the authentication request. If the OP Privacy Policy
  allows it and the authenticating user consents to it, the related claims are returned to the
  RP (either in the ID Token or as a UserInfo response).
  
  The list of the supported claims will vary depending on the OP you are using, but you can expect
  the https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims[Standard Claims] to be
  largely supported.
  
  [[oidc-claim-to-property]]
  ===== Mapping claims to user properties
  
  The goal of claims mapping is to configure {es} in such a way as to be able to map the values of
  specified returned claims to one of the <<oidc-user-properties, user properties>> that are supported
  by {es}. These user properties are then utilized to identify the user in the {kib} UI or the audit
  logs, and can also be used to create <<oidc-role-mapping, role mapping>> rules.
  
  The recommended steps for configuring OpenID Claims mapping are as follows:
  
  . Consult your OP configuration to see what claims it might support. Note that
    the list provided in the OP's metadata or in the configuration page of the OP
    is a list of potentially supported claims. However, for privacy reasons it might
    not be a complete one, or not all supported claims will be available for all
    authenticated users.
  
  . Read through the list of <<oidc-user-properties, user properties>> that {es}
    supports, and decide which of them are useful to you, and can be provided by
    your OP in the form of claims. At a _minimum_, the `principal` user property
    is required.
  
  . Configure your OP to "release" those claims to your {stack} Relying
    party. This process greatly varies by provider. You can use a static
    configuration while others will support that the RP requests the scopes that
    correspond to the claims to be "released" on authentication time. See
    {ref}/security-settings.html#ref-oidc-settings[`rp.requested_scopes`] for details about how
    to configure the scopes to request. To ensure interoperability and minimize
    the errors, you should only request scopes that the OP supports, and which you
    intend to map to {es} user properties.
  
  . Configure the OpenID Connect realm in {es} to associate the {es} user properties (see
    <<oidc-user-properties, the listing>> below), to the name of the claims that your
    OP will release. In the example above, we have configured the `principal` and
    `groups` user properties as follows:
  
    .. `claims.principal: sub` : This instructs {es} to look for the OpenID Connect claim named `sub`
       in the ID Token that the OP issued for the user ( or in the UserInfo response ) and assign the
       value of this claim to the `principal` user property. `sub` is a commonly used claim for the
       principal property as it is an identifier of the user in the OP and it is also a required
       claim of the ID Token, thus offering guarantees that it will be available. It is, however,
       only used as an example here, the OP may provide another claim that is a better fit for your needs.
  
    .. `claims.groups: "http://example.info/claims/groups"` : Similarly, this instructs {es} to look
       for the claim with the name `http://example.info/claims/groups` (note that this is a URI - an
       identifier, treated as a string and not a URL pointing to a location that will be retrieved)
       either in the ID Token or in the UserInfo response, and map the value(s) of it to the user
       property `groups` in {es}. There is no standard claim in the specification that is used for
       expressing roles or group memberships of the authenticated user in the OP, so the name of the
       claim that should be mapped here, will vary greatly between providers. Consult your OP
       documentation for more details.
  
  [[oidc-user-properties]]
  ===== {es} user properties
  
  The {es} OpenID Connect realm can be configured to map OpenID Connect claims to the
  following properties on the authenticated user:
  
  principal:: _(Required)_
      This is the _username_ that will be applied to a user that authenticates
      against this realm.
      The `principal` appears in places such as the {es} audit logs.
  
  NOTE: If the principal property fails to be mapped from a claim, the authentication fails.
  
  groups:: _(Recommended)_
      If you wish to use your OP's concept of groups or roles as the basis for a
      user's {es} privileges, you should map them with this property.
      The `groups` are passed directly to your <<oidc-role-mapping, role mapping rules>>.
  
  name:: _(Optional)_ The user's full name.
  mail:: _(Optional)_ The user's email address.
  dn:: _(Optional)_ The user's X.500 _Distinguished Name_.
  
  
  ===== Extracting partial values from OpenID Connect claims
  
  There are some occasions where the value of a claim may contain more information
  than you wish to use within {es}. A common example of this is one where the
  OP works exclusively with email addresses, but you would like the user's
  `principal` to use the _local-name_ part of the email address.
  For example if their email address was `james.wong@staff.example.com`, then you
  would like their principal to simply be `james.wong`.
  
  This can be achieved using the `claim_patterns` setting in the {es}
  realm, as demonstrated in the realm configuration below:
  
  [source, yaml]
  -------------------------------------------------------------------------------------
  xpack.security.authc.realms.oidc.oidc1:
    rp.client_id: "the_client_id"
    rp.response_type: code
    rp.redirect_uri: "https://kibana.example.org:5601/api/security/v1/oidc"
    op.authorization_endpoint: "https://op.example.org/oauth2/v1/authorize"
    op.token_endpoint: "https://op.example.org/oauth2/v1/token"
    op.userinfo_endpoint: "https://op.example.org/oauth2/v1/userinfo"
    op.endsession_endpoint: "https://op.example.org/oauth2/v1/logout"
    op.issuer: "https://op.example.org"
    op.jwkset_path: oidc/jwkset.json
    claims.principal: email_verified
    claim_patterns.principal: "^([^@]+)@staff\\.example\\.com$"
  -------------------------------------------------------------------------------------
  
negative.code: will trigger re-authentication of the user. For instance, when using OpenID Connect to support
  single sign-on to {kib}, this could be set to +$\{kibana-url}/logged_out+,  which will show a user-
  friendly message to the user.
  
  [[oidc-ssl-config]]
  ==== OpenID Connect Realm SSL Configuration
  
  OpenID Connect depends on TLS to provide security properties such as encryption in transit and endpoint authentication. The RP
  is required to establish back-channel communication with the OP in order to exchange the code for an ID Token during the
  Authorization code grant flow and in order to get additional user information from the UserInfo endpoint. Furthermore, if
  you configure `op.jwks_path` as a URL, {es} will need to get the OP's signing keys from the file hosted there. As such, it is
  important that {es} can validate and trust the server certificate that the OP uses for TLS. Since the system truststore is
  used for the client context of outgoing https connections, if your OP is using a certificate from a trusted CA, no additional
  configuration is needed.
  
  However, if the issuer of your OP's certificate is not trusted by the JVM on which {es} is running (e.g it uses a organization CA), then you must configure
  {es} to trust that CA. Assuming that you have the CA certificate that has signed the certificate that the OP uses for TLS
  stored in the /oidc/company-ca.pem` file stored in the configuration directory of {es}, you need to set the following
  property in the realm configuration:
  
  [source, yaml]
  -------------------------------------------------------------------------------------
  xpack.security.authc.realms.oidc.oidc1:
    order: 1
    ...
    ssl.certificate_authorities: ["/oidc/company-ca.pem"]
  -------------------------------------------------------------------------------------
  
  [[oidc-role-mapping]]
  === Configuring role mappings
  