Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

此内容没有您所选择的语言版本。

Chapter 4. Advanced Concepts

These cover additional configuration topics, such as seting up keystores and a truststore for the Red Hat Single Sign-On server, creating an administrator account, an overview of available Red Hat Single Sign-On client registration methods, and guidance on configuring clustering.

The hostname SPI introduced a flexible way to configure the hostname for the Red Hat Single Sign-On server. There are two built-in providers. The first is request, which uses the request headers to determine the hostname. This is the default setting for Red Hat Single Sign-On for OpenShift image. The second is fixed, which allows configuring a fixed hostname. The latter makes sure that only valid hostnames can be used and allows internal applications to invoke Red Hat Single Sign-On server through an alternative URL.

Run the following commands to set the fixed hostname SPI provider for the Red Hat Single Sign-On server:

  1. Deploy the Red Hat Single Sign-On for OpenShift image with SSO_HOSTNAME environment variable set to the desired hostname of the Red Hat Single Sign-On server. 

    $ oc new-app --template=sso-cd-x509-https \
  -p SSO_HOSTNAME="rh-sso-server.openshift.example.com"
    Copy to Clipboard Toggle word wrap

  2. Identify the name of the route for the Red Hat Single Sign-On service. 

    $ oc get routes
    Copy to Clipboard Toggle word wrap
    Expand
    NAMEHOST/PORTPATHSERVICESPORTTERMINATIONWILDCARD

    sso

    sso-sso-app-demo.openshift.example.com

    		 

    sso

    <all>

    reencrypt

    None

  3. Change the host: field to match the hostname specified as the value of the SSO_HOSTNAME environment variable above.

    Note

    Adjust the rh-sso-server.openshift.example.com value in the following command as necessary. 

    $ oc patch route/sso --type=json -p '[{"op": "replace", "path": "/spec/host", "value": "rh-sso-server.openshift.example.com"}]'
    Copy to Clipboard Toggle word wrap

    If successful, the previous command will return the following output: 

    route "sso" patched
    Copy to Clipboard Toggle word wrap

4.2.1. Connecting to an external database
复制链接

Red Hat Single Sign-On can be configured to connect to an external (to OpenShift cluster) database. In order to achieve this, you need to modify the sso-{database name} Endpoints object to point to the proper address. The procedure has been described in OpenShift manual.

Tip: The easiest way to get started is to deploy Red Hat Single Sign-On from a template and then modify the Endpoints object. You might also need to update some of the datasource configuration variables in the DeploymentConfig. Once you’re done, just roll a new deployment out.

Red Hat Single Sign-On does not provide any pre-configured management account out of the box. This administrator account is necessary for logging into the master realm’s management console and perform server maintenance operations such as, creating realms or users, or registering applications intended to be secured by Red Hat Single Sign-On.

The administrator account can be created:

Note

Red Hat Single Sign-On allows an initial administrator account to be created via the Welcome Page web form, but only if the Welcome Page is accessed from localhost; this method of administrator account creation is not applicable for the Red Hat Single Sign-On for OpenShift image.

When deploying Red Hat Single Sign-On application template, the SSO_ADMIN_USERNAME and SSO_ADMIN_PASSWORD parameters denote the username and password of the Red Hat Single Sign-On server’s administrator account to be created for the master realm.

Note

Both of these parameters are required. If not specified, they are auto generated and displayed as an OpenShift instructional message when the template is instantiated.

Important

The lifespan of the Red Hat Single Sign-On server’s administrator account depends upon the storage type used to store the Red Hat Single Sign-On server’s database:

  • For an in-memory database mode (sso73-https and sso73-x509-https templates) the account exists throughout the lifecycle of the particular Red Hat Single Sign-On pod (stored account data is lost upon pod destruction),
  • For an ephemeral database mode (sso73-mysql and sso73-postgresql templates) the account exists throughout the lifecycle of the database pod (even if the Red Hat Single Sign-On pod is destructed, the stored account data is preserved under the assumption that the database pod is still running),
  • For persistent database mode (sso73-mysql-persistent, sso73-x509-mysql-persistent, sso73-postgresql-persistent, and sso73-x509-postgresql-persistent templates) the account exists throughout the lifecycle of the persistent medium used to hold the database data. This means that the stored account data is preserved even when both the Red Hat Single Sign-On and the database pods are destructed.

It is a common practice to deploy an Red Hat Single Sign-On application template to get the corresponding OpenShift deployment config for the application, and then reuse that deployment config multiple times (every time a new Red Hat Single Sign-On application needs to be instantiated).

Warning

In the case of ephemeral or persistent database mode, after creating the RH_SSO server’s administrator account, remove the SSO_ADMIN_USERNAME and SSO_ADMIN_PASSWORD variables from the deployment config before deploying new Red Hat Single Sign-On applications.

Important

Run the following commands to prepare the previously created deployment config of the Red Hat Single Sign-On application for reuse after the administrator account has been created:

  1. Identify the deployment config of the Red Hat Single Sign-On application. 

    $ oc get dc -o name
deploymentconfig/sso
deploymentconfig/sso-mysql
    Copy to Clipboard Toggle word wrap

  2. Clear the SSO_ADMIN_USERNAME and SSO_ADMIN_PASSWORD variables setting. 

    $ oc set env dc/sso \
  -e SSO_ADMIN_USERNAME="" \
  -e SSO_ADMIN_PASSWORD=""
    Copy to Clipboard Toggle word wrap

Run following commands to create an administrator account for the master realm of the Red Hat Single Sign-On server, when deploying the Red Hat Single Sign-On for OpenShift image directly from the image stream (without the template), after the Red Hat Single Sign-On application pod has been started:

  1. Identify the Red Hat Single Sign-On application pod. 

    $ oc get pods
NAME                READY     STATUS    RESTARTS   AGE
sso-12-pt93n        1/1       Running   0          1m
sso-mysql-6-d97pf   1/1       Running   0          2m
    Copy to Clipboard Toggle word wrap

  2. Open a remote shell session to the Red Hat Single Sign-On for OpenShift container. 

    $ oc rsh sso-12-pt93n
sh-4.2$
    Copy to Clipboard Toggle word wrap

  3. Create the Red Hat Single Sign-On server administrator account for the master realm at the command line with the add-user-keycloak.sh script. 

    sh-4.2$ cd /opt/eap/bin/
sh-4.2$ ./add-user-keycloak.sh \
        -r master \
        -u sso_admin \
        -p sso_password
Added 'sso_admin' to '/opt/eap/standalone/configuration/keycloak-add-user.json', restart server to load user
    Copy to Clipboard Toggle word wrap
    Note

    The 'sso_admin' / 'sso_password' credentials in the example above are for demonstration purposes only. Refer to the password policy applicable within your organization for guidance on how to create a secure user name and password.

  4. Restart the underlying JBoss EAP server instance to load the newly added user account. Wait for the server to restart properly. 

    sh-4.2$ ./jboss-cli.sh --connect ':reload'
{
    "outcome" => "success",
    "result" => undefined
}
    Copy to Clipboard Toggle word wrap
    Warning

    When restarting the server it is important to restart just the JBoss EAP process within the running Red Hat Single Sign-On container, and not the whole container. This is because restarting the whole container will recreate it from scratch, without the Red Hat Single Sign-On server administration account for the master realm.

  5. Log in to the master realm’s administration console of the Red Hat Single Sign-On server using the credentials created in the steps above. In the browser, navigate to http://sso-<project-name>.<hostname>/auth/admin for the Red Hat Single Sign-On web server, or to https://secure-sso-<project-name>.<hostname>/auth/admin for the encrypted Red Hat Single Sign-On web server, and specify the user name and password used to create the administrator user.

4.4. Deployment Process
复制链接

Once deployed, the sso73-https and sso73-x509-https templates create a single pod that contains both the database and the Red Hat Single Sign-On servers. The sso73-mysql, sso73-mysql-persistent, sso73-x509-mysql-persistent, sso73-postgresql, sso73-postgresql-persistent, and sso73-x509-postgresql-persistent templates create two pods, one for the database server and one for the Red Hat Single Sign-On web server.

After the Red Hat Single Sign-On web server pod has started, it can be accessed at its custom configured hostnames, or at the default hostnames:

  • http://sso-<project-name>.<hostname>/auth/admin: for the Red Hat Single Sign-On web server, and
  • https://secure-sso-<project-name>.<hostname>/auth/admin: for the encrypted Red Hat Single Sign-On web server.

Use the administrator user credentials to log in into the master realm’s administration console.

4.5. Red Hat Single Sign-On Clients
复制链接

Clients are Red Hat Single Sign-On entities that request user authentication. A client can be an application requesting Red Hat Single Sign-On to provide user authentication, or it can be making requests for access tokens to start services on behalf of an authenticated user. See the Managing Clients chapter of the Red Hat Single Sign-On documentation for more information.

Red Hat Single Sign-On provides OpenID-Connect and 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 <auth-method> key of the application web.xml file. This file is read by the image at deployment. Set the value of <auth-method> 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: 

...
<login-config>
        <auth-method>KEYCLOAK</auth-method>
</login-config>
...
Copy to Clipboard Toggle word wrap

A client application can be automatically registered to an Red Hat Single Sign-On 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 Red Hat Single Sign-On client adapter and including it in the client application configuration.

Automatic Red Hat Single Sign-On client registration is determined by Red Hat Single Sign-On environment variables specific to the eap64-sso-s2i, eap71-sso-s2i, and datavirt63-secure-s2i templates. The Red Hat Single Sign-On credentials supplied in the template are then used to register the client to the Red Hat Single Sign-On realm during deployment of the client application.

The Red Hat Single Sign-On environment variables included in the eap64-sso-s2i, eap71-sso-s2i, and datavirt63-secure-s2i templates are:

Expand
VariableDescription

HOSTNAME_HTTP

Custom hostname for http service route. Leave blank for default hostname of <application-name>.<project>.<default-domain-suffix>

HOSTNAME_HTTPS

Custom hostname for https service route. Leave blank for default hostname of <application-name>.<project>.<default-domain-suffix>

SSO_URL

The Red Hat Single Sign-On web server authentication address: https://secure-sso-<project-name>.<hostname>/auth

SSO_REALM

The Red Hat Single Sign-On 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 Red Hat Single Sign-On 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 Red Hat Single Sign-On adapter enables Cross-Origin Resource Sharing (CORS).

If the Red Hat Single Sign-On client uses the SAML protocol, the following additional variables need to be configured:

Expand
VariableDescription

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 Example Workflow: Automatically Registering EAP Application in Red Hat Single Sign-On with OpenID-Connect Client for an end-to-end example of the automatic client registration method using an OpenID-Connect client.

4.5.1.2. Manual Red Hat Single Sign-On Client Registration
复制链接

Manual Red Hat Single Sign-On 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 Red Hat Single Sign-On web console. The name of this file is different for OpenID-Connect and SAML clients:

OpenID-Connect

../configuration/secure-deployments

SAML

../configuration/secure-saml-deployments

These files are copied to the Red Hat Single Sign-On adapter configuration section in the standalone-openshift.xml at when the application is deployed.

There are two methods for passing the Red Hat Single Sign-On adapter configuration to the client application:

  • Modify the deployment file to contain the Red Hat Single Sign-On 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 Example Workflow: Manually Configure an Application to Use Red Hat Single Sign-On Authentication, Using SAML Client for an end-to-end example of the manual Red Hat Single Sign-On client registration method using a SAML client.

4.6. Limitations
复制链接

OpenShift does not currently accept OpenShift role mapping from external providers. If Red Hat Single Sign-On is used as an authentication gateway for OpenShift, users created in Red Hat Single Sign-On must have the roles added using the OpenShift Administrator oc adm policy command.

For example, to allow an Red Hat Single Sign-On-created user to view a project namespace in OpenShift: 

$ oc adm policy add-role-to-user view <user-name> -n <project-name>
Copy to Clipboard Toggle word wrap
返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat