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