OIDC Guide additions

x-pack/docs/en/security/authentication/oidc-guide.asciidoc

@@ -103,12 +103,13 @@ 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.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"
-  op.issuer: "https://op.example.org"
-  op.jwkset_path: oidc/jwkset.json
+  rp.post_logout_redirect_uri: "https://kibana.example.org:5601/logged_out"
   claims.principal: sub
   claims.groups: "http://example.info/claims/groups"
 -------------------------------------------------------------------------------------
@@ -146,6 +147,10 @@ rp.redirect_uri::
     _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
@@ -156,6 +161,13 @@ op.token_endpoint::
     {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
@@ -166,12 +178,11 @@ op.endsession_endpoint::
     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.
+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>>.
@@ -306,6 +317,7 @@ realm, as demonstrated in the realm configuration below:
 [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"
@@ -369,6 +381,30 @@ will trigger re-authentication of the user. For instance, when using OpenID Conn
 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 your OP uses a certificate that is issued for instance, by a CA used only in your Organization, 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