From 56ef4d609a2fbcaccca709a499fbe5b597c33645 Mon Sep 17 00:00:00 2001 From: Ioannis Kakavas Date: Sat, 25 May 2019 20:25:32 +0300 Subject: [PATCH 1/2] OIDC Guide additions - Call out the fact that the SSL Configuration is important and offer a minimal example of configuring a custom CA for trust. - Add information about the `op.issuer` that was missing and add information about the `rp.post_logout_redirect` in the example since `op.endsession_endpoint` was already mentioned there and these two should be together - Explain that `op.jwks_path` can be a URL. --- .../authentication/oidc-guide.asciidoc | 52 ++++++++++++++++--- 1 file changed, 44 insertions(+), 8 deletions(-) diff --git a/x-pack/docs/en/security/authentication/oidc-guide.asciidoc b/x-pack/docs/en/security/authentication/oidc-guide.asciidoc index df5ce11c63c14..ccbf1ceb5275c 100644 --- a/x-pack/docs/en/security/authentication/oidc-guide.asciidoc +++ b/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 <> 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 <>. claims.groups:: See <>. @@ -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 From ec85445415f00132ba0d35607961a13e75765a0f Mon Sep 17 00:00:00 2001 From: Ioannis Kakavas Date: Mon, 3 Jun 2019 22:37:07 +0300 Subject: [PATCH 2/2] address feedback --- x-pack/docs/en/security/authentication/oidc-guide.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/docs/en/security/authentication/oidc-guide.asciidoc b/x-pack/docs/en/security/authentication/oidc-guide.asciidoc index ccbf1ceb5275c..d7d68ada0e721 100644 --- a/x-pack/docs/en/security/authentication/oidc-guide.asciidoc +++ b/x-pack/docs/en/security/authentication/oidc-guide.asciidoc @@ -392,7 +392,7 @@ important that {es} can validate and trust the server certificate that the OP us 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 +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: