From f743f4633cf736b77077b7ff0d3b0344d19b1452 Mon Sep 17 00:00:00 2001 From: Jan Lieskovsky Date: Fri, 14 Dec 2018 20:34:48 +0100 Subject: [PATCH] [General] Drop the duplicate occurrence of the '{project_name} Clients' section and 'Limitations' section from the 'Get Started' book section Keep them in the 'Advanced Concepts' section, since this is the one where these two belongs (see 7.2 guide for reference) Signed-off-by: Jan Lieskovsky --- openshift/topics/advanced_concepts.adoc | 6 +- openshift/topics/get_started.adoc | 119 ------------------------ openshift/topics/tutorials.adoc | 4 +- 3 files changed, 5 insertions(+), 124 deletions(-) diff --git a/openshift/topics/advanced_concepts.adoc b/openshift/topics/advanced_concepts.adoc index 44f1d13087..f466efb747 100644 --- a/openshift/topics/advanced_concepts.adoc +++ b/openshift/topics/advanced_concepts.adoc @@ -443,10 +443,10 @@ After the {project_name} web server pod has started, it can be accessed at its c Use the xref:../advanced_concepts/advanced_concepts.adoc#advanced-concepts-sso-administrator-setup[administrator user credentials] to log in into the `master` realm’s administration console. -[[advanced-concepts-SSO-Clients]] +[[SSO-Clients]] === {project_name} Clients -Clients are {project_name} entities that request user authentication. A client can be an application requesting {project_name} to provide user authentication, or it can make requests for access tokens to start services on behalf of an authenticated user. See the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_administration_guide/clients[Managing Clients chapter of the Red Hat Single Sign-On documentation] for more information. +Clients are {project_name} entities that request user authentication. A client can be an application requesting {project_name} to provide user authentication, or it can be making requests for access tokens to start services on behalf of an authenticated user. See the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_administration_guide/clients[Managing Clients chapter of the {project_name} documentation] for more information. {project_name} provides link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_administration_guide/clients#oidc_clients[OpenID-Connect] and link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_administration_guide/clients#saml_clients[SAML] client protocols. + OpenID-Connect is the preferred protocol and utilizes three different access types: @@ -471,7 +471,7 @@ The following is an example snippet for the application *web.xml* to configure a ... ---- -[[advanced-concepts-Auto-Man-Client-Reg]] +[[Auto-Man-Client-Reg]] ==== Automatic and Manual {project_name} Client Registration Methods A client application can be automatically registered to an {project_name} realm by using credentials passed in variables specific to the *_eap64-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates. diff --git a/openshift/topics/get_started.adoc b/openshift/topics/get_started.adoc index 37fcb4f538..9d194b60ff 100644 --- a/openshift/topics/get_started.adoc +++ b/openshift/topics/get_started.adoc @@ -289,125 +289,6 @@ The {project_openshift_product_name} templates use TLS passthrough termination f For more information on OpenShift route types, see the link:https://docs.openshift.com/container-platform/3.7/architecture/networking/routes.html#route-types[Networking chapter] of the OpenShift Architecture Guide. -[[SSO-Clients]] -==== {project_name} Clients - -Clients are {project_name} entities that request user authentication. A client can be an application requesting {project_name} to provide user authentication, or it can be making requests for access tokens to start services on behalf of an authenticated user. See the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_administration_guide/clients[Managing Clients chapter of the {project_name} documentation] for more information. - -{project_name} provides link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_administration_guide/clients#oidc_clients[OpenID-Connect] and link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html/server_administration_guide/clients#saml_clients[SAML] client protocols. + -OpenID-Connect is the preferred protocol and utilizes three different access types: - -- *public*: Useful for JavaScript applications that run directly in the browser and require no server configuration. -- *confidential*: Useful for server-side clients, such as EAP web applications, that need to perform a browser login. -- *bearer-only*: Useful for back-end services that allow bearer token requests. - -It is required to specify the client type in the ** key of the application *web.xml* file. This file is read by the image at deployment. Set the value of ** element to: - -* *KEYCLOAK* for the OpenID Connect client. -* *KEYCLOAK-SAML* for the SAML client. - -The following is an example snippet for the application *web.xml* to configure an OIDC client: - -[source,bash,subs="attributes+,macros+"] ----- -... - - KEYCLOAK - -... ----- - -[[Auto-Man-Client-Reg]] -==== Automatic and Manual {project_name} Client Registration Methods -A client application can be automatically registered to an {project_name} realm by using credentials passed in variables specific to the *_eap64-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates. - -Alternatively, you can manually register the client application by configuring and exporting the {project_name} client adapter and including it in the client application configuration. - -==== Automatic {project_name} Client Registration - -Automatic {project_name} client registration is determined by {project_name} environment variables specific to the *_eap64-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates. The {project_name} credentials supplied in the template are then used to register the client to the {project_name} realm during deployment of the client application. - -The {project_name} environment variables included in the *_eap64-sso-s2i_*, *_eap71-sso-s2i_*, and *_datavirt63-secure-s2i_* templates are: - -[cols="2*", options="header"] -|=== -|Variable -|Description -|*_HOSTNAME_HTTP_* -|Custom hostname for http service route. Leave blank for default hostname of .. - -|*_HOSTNAME_HTTPS_* -|Custom hostname for https service route. Leave blank for default hostname of .. - -|*_SSO_URL_* -|The {project_name} web server authentication address: $$https://secure-sso-$$__.__/auth - -|*_SSO_REALM_* -|The {project_name} realm created for this procedure. - -|*_SSO_USERNAME_* -|The name of the _realm management user_. - -|*_SSO_PASSWORD_* -| The password of the user. - -|*_SSO_PUBLIC_KEY_* -|The public key generated by the realm. It is located in the *Keys* tab of the *Realm Settings* in the {project_name} console. - -|*_SSO_BEARER_ONLY_* -|If set to *true*, the OpenID Connect client is registered as bearer-only. - -|*_SSO_ENABLE_CORS_* -|If set to *true*, the {project_name} adapter enables Cross-Origin Resource Sharing (CORS). -|=== - -If the {project_name} client uses the SAML protocol, the following additional variables need to be configured: - -[cols="2*", options="header"] -|=== -|Variable -|Description -|*_SSO_SAML_KEYSTORE_SECRET_* -|Secret to use for access to SAML keystore. The default is _sso-app-secret_. - -|*_SSO_SAML_KEYSTORE_* -|Keystore filename in the SAML keystore secret. The default is _keystore.jks_. - -|*_SSO_SAML_KEYSTORE_PASSWORD_* -|Keystore password for SAML. The default is _mykeystorepass_. - -|*_SSO_SAML_CERTIFICATE_NAME_* -|Alias for keys/certificate to use for SAML. The default is _jboss_. -|=== - -See xref:Example-EAP-Auto[Example Workflow: Automatically Registering EAP Application in {project_name} with OpenID-Connect Client] for an end-to-end example of the automatic client registration method using an OpenID-Connect client. - -==== Manual {project_name} Client Registration - -Manual {project_name} client registration is determined by the presence of a deployment file in the client application's _../configuration/_ directory. These files are exported from the client adapter in the {project_name} web console. The name of this file is different for OpenID-Connect and SAML clients: - -[horizontal] -*OpenID-Connect*:: _../configuration/secure-deployments_ -*SAML*:: _../configuration/secure-saml-deployments_ - -These files are copied to the {project_name} adapter configuration section in the _standalone-openshift.xml_ at when the application is deployed. - -There are two methods for passing the {project_name} adapter configuration to the client application: - -* Modify the deployment file to contain the {project_name} adapter configuration so that it is included in the _standalone-openshift.xml_ file at deployment, or -* Manually include the OpenID-Connect _keycloak.json_ file, or the SAML _keycloak-saml.xml_ file in the client application's *../WEB-INF* directory. - -See xref:Example-EAP-Manual[Example Workflow: Manually Configure an Application to Use {project_name} Authentication, Using SAML Client] for an end-to-end example of the manual {project_name} client registration method using a SAML client. - -==== Limitations -OpenShift does not currently accept OpenShift role mapping from external providers. If {project_name} is used as an authentication gateway for OpenShift, users created in {project_name} must have the roles added using the OpenShift Administrator `oc adm policy` command. - -For example, to allow an {project_name}-created user to view a project namespace in OpenShift: -[source,bash,subs="attributes+,macros+"] ----- -$ oc adm policy add-role-to-user view -n ----- - === Binary Builds To deploy existing applications on OpenShift, you can use the link:https://docs.openshift.com/container-platform/latest/dev_guide/builds/build_inputs.html#binary-source[binary source] capability. diff --git a/openshift/topics/tutorials.adoc b/openshift/topics/tutorials.adoc index 8d6a8290a5..aa92027f24 100644 --- a/openshift/topics/tutorials.adoc +++ b/openshift/topics/tutorials.adoc @@ -848,7 +848,7 @@ This follows on from xref:Example-Deploying-SSO[Example Workflow: Preparing and [NOTE] ==== -This example uses a OpenID-Connect client but an SAML client could also be used. See xref:SSO-Clients[{project_name} Clients] and xref:Auto-Man-Client-Reg[Automatic and Manual {project_name} Client Registration Methods] for more information on the differences between OpenID-Connect and SAML clients. +This example uses a OpenID-Connect client but an SAML client could also be used. See xref:../advanced_concepts/advanced_concepts.adoc#SSO-Clients[{project_name} Clients] and xref:../advanced_concepts/advanced_concepts.adoc#Auto-Man-Client-Reg[Automatic and Manual {project_name} Client Registration Methods] for more information on the differences between OpenID-Connect and SAML clients. ==== ==== Preparing {project_name} Authentication for OpenShift Deployment @@ -1015,7 +1015,7 @@ This example prepares {project_name} realm, role, and user credentials for an EA [NOTE] ==== -This example uses a SAML client but an OpenID-Connect client could also be used. See xref:SSO-Clients[{project_name} Clients] and xref:Auto-Man-Client-Reg[Automatic and Manual {project_name} Client Registration Methods] for more information on the differences between SAML and OpenID-Connect clients. +This example uses a SAML client but an OpenID-Connect client could also be used. See xref:../advanced_concepts/advanced_concepts.adoc#SSO-Clients[{project_name} Clients] and xref:../advanced_concepts/advanced_concepts.adoc#Auto-Man-Client-Reg[Automatic and Manual {project_name} Client Registration Methods] for more information on the differences between SAML and OpenID-Connect clients. ==== ==== Preparing the {project_name} Credentials