Chapter 3. Configuring realms Once you have an administrative account for the Admin Console, you can configure realms. A realm is a space where you manage objects, including users, applications, roles, and groups. A user belongs to and logs into a realm. One Red Hat Single Sign-On deployment can define, store, and manage as many realms as there is space for in the database. 3.1. Using the Admin Console You configure realms and perform most administrative tasks in the Red Hat Single Sign-On Admin Console. Prerequisites You need an administrator account. See Creating the first administrator . Procedure Go the the URL for the Admin Console. For example, for localhost, use this URL: http://localhost:8080/auth/admin/ Login page Enter the username and password you created on the Welcome Page or the add-user-keycloak script in the bin directory. This action displays the Admin Console. Admin Console Note the menus and other options that you can use: Click the menu labeled Master to pick a realm you want to manage or to create a new one. Click the top right list to view your account or log out. Hover over a question mark ? icon to show a tooltip text that describes that field. The image above shows the tooltip in action. 3.2. The master realm In the Admin Console, two types of realms exist: Master realm - This realm was created for you when you first started Red Hat Single Sign-On. It contains the administrator account you created at the first login. Use the master realm only to create and manage the realms in your system. Other realms - These realms are created by the administrator in the master realm. In these realms, administrators manage the users in your organization and the applications they need. The applications are owned by the users. Realms and applications Realms are isolated from one another and can only manage and authenticate the users that they control. Following this security model helps prevent accidental changes and follows the tradition of permitting user accounts access to only those privileges and powers necessary for the successful completion of their current task. Additional resources See Dedicated Realm Admin Consoles if you want to disable the master realm and define administrator accounts within any new realm you create. Each realm has its own dedicated Admin Console that you can log into with local accounts. 3.3. Creating a realm You create a realm to provide a management space where you can create users and give them permissions to use applications. At first login, you are typically in the master realm, the top-level realm from which you create other realms. When deciding what realms you need, consider the kind of isolation you want to have for your users and applications. For example, you might create a realm for the employees of your company and a separate realm for your customers. Your employees would log into the employee realm and only be able to visit internal company applications. Customers would log into the customer realm and only be able to interact with customer-facing apps. Procedure Point to the top of the left pane. Click Add Realm . Add realm menu Enter a name for the realm. Click Create . Create realm The current realm is now set to the realm you just created. You can switch between managing different realms by pointing to the top left corner to click Select Realm . 3.4. Configuring SSL for a realm Each realm has an associated SSL Mode, which defines the SSL/HTTPS requirements for interacting with the realm. Browsers and applications that interact with the realm honor the SSL/HTTPS requirements defined by the SSL Mode or they cannot interact with the server. Warning Red Hat Single Sign-On generates a self-signed certificate the first time it runs. Please note that self-signed certificates are not secure, and should only be used for testing purposes. It is highly recommended that you install a CA-signed certificate on the Red Hat Single Sign-On server itself or on a reverse proxy in front of the Red Hat Single Sign-On server. See the Server Installation and Configuration Guide . Procedure Click Realm Settings in the menu. Click the Login tab. Login tab Set Require SSL to one of the following SSL modes: external requests:: Users can interact with Red Hat Single Sign-On without SSL so long as they stick to private IP addresses such as localhost , 127.0.0.1 , 10.x.x.x , 192.168.x.x , and 172.16.x.x . If you try to access Red Hat Single Sign-On without SSL from a non-private IP address, you will get an error. none:: Red Hat Single Sign-On does not require SSL. This choice applies only in development when you are experimenting and do not plan to support this deployment. all requests:: Red Hat Single Sign-On requires SSL for all IP addresses. 3.5. Clearing server caches Red Hat Single Sign-On caches everything it can in memory within the limits of your JVM and the limits you have configured. If the Red Hat Single Sign-On database is modified by a third party, such as a DBA, outside the scope of the server's REST APIs or Admin Console, parts of the in-memory cache could be stale. You can clear the realm cache, user cache or cache of external public keys, such as Public keys of external clients or Identity providers, which Red Hat Single Sign-On may use to verify signatures of particular external entity. Procedure Click Realm Settings in the menu. Click the Cache tab. Click Clear for the cache you want to evict. Cache tab 3.6. Configuring email for a realm Red Hat Single Sign-On sends emails to users to verify their email addresses, when they forget their passwords, or when an administrator needs to receive notifications about a server event. To enable Red Hat Single Sign-On to send emails, you provide Red Hat Single Sign-On with your SMTP server settings. Procedure Click Realm Settings in the menu. Click the Email tab. Email tab Fill in the fields and toggle the switches as needed. Host Host denotes the SMTP server hostname used for sending emails. Port Port denotes the SMTP server port. From From denotes the address used for the From SMTP-Header for the emails sent. From Display Name From Display Name allows to configure a user friendly email address aliases (optional). If not set the plain From email address will be displayed in email clients. Reply To Reply To denotes the address used for the Reply-To SMTP-Header for the mails sent (optional). If not set the plain From email address will be used. Reply To Display Name Reply To Display Name allows to configure a user friendly email address aliases (optional). If not set the plain Reply To email address will be displayed. Envelope From Envelope From denotes the Bounce Address used for the Return-Path SMTP-Header for the mails sent (optional). Enable SSL and Enable StartTSL Toggle one of these switches to ON to support sending emails for recovering usernames and passwords, especially if the SMTP server is on an external network. You will most likely need to change the Port to 465, the default port for SSL/TLS. Enable Authentication Set this switch to ON if your SMTP server requires authentication. When prompted, supply the Username and Password . The value of the Password field can refer a value from an external vault . 3.7. Configuring themes and internationalization For a given realm, you can change the appearance of any UI, including the language that appears, in Red Hat Single Sign-On by using themes. Procedure Click Realm Setting in the menu. Click the Themes tab. Themes tab Pick the theme you want for each UI category and click Save . Login Theme Username password entry, OTP entry, new user registration, and other similar screens related to login. Account Theme Each user has an User Account Management UI. Admin Console Theme The skin of the Red Hat Single Sign-On Admin Console. Email Theme Whenever Red Hat Single Sign-On has to send out an email, it uses templates defined in this theme to craft the email. Additional resources The Server Developer Guide describes how to create a new theme or modify existing ones. 3.7.1. Enabling internationalization Every UI screen is internationalized in Red Hat Single Sign-On. The default language is English, but you can choose which locales you want to support and what the default locale will be. Procedure Click Realm Settings in the menu. Click the Theme tab. Set Internationalization to ON . The time a user logs in, that user can choose a language on the login page to use for the login screens, Account Console, and Admin Console. Additional resources The Server Developer Guide explains how you can offer additional languages. All internationalized texts which are provided by the theme can be overwritten by realm-specific texts on the Localization tab. 3.7.2. User locale selection A locale selector provider suggests the best locale on the information available. However, it is often unknown who the user is. For this reason, the previously authenticated user's locale is remembered in a persisted cookie. The logic for selecting the locale uses the first of the following that is available: User selected - when the user has selected a locale using the drop-down locale selector User profile - when there is an authenticated user and the user has a preferred locale set Client selected - passed by the client using for example ui_locales parameter Cookie - last locale selected on the browser Accepted language - locale from Accept-Language header Realm default If none of the above, fall back to English When a user is authenticated an action is triggered to update the locale in the persisted cookie mentioned earlier. If the user has actively switched the locale through the locale selector on the login pages the users locale is also updated at this point. If you want to change the logic for selecting the locale, you have an option to create custom LocaleSelectorProvider . For details, please refer to the Server Developer Guide . 3.8. Controlling login options Red Hat Single Sign-On includes several built-in login page features. 3.8.1. Enabling forgot password If you enable Forgot Password , users can reset their login credentials if they forget their passwords or lose their OTP generator. Procedure Click Realm Settings in the menu. Click the Login tab. Login tab Toggle Forgot Password to ON . A forgot password link displays in your login pages. Forgot password link Click this link to bring users where they can enter their username or email address and receive an email with a link to reset their credentials. Forgot password page The text sent in the email is configurable. See Server Developer Guide for more information. When users click the email link, Red Hat Single Sign-On asks them to update their password, and if they have set up an OTP generator, Red Hat Single Sign-On asks them to reconfigure the OTP generator. Depending on security requirements of your organization, you may not want users to reset their OTP generator through email. To change this behavior, perform these steps: Procedure Click Authentication in the menu. Click the Flows tab. Select the Reset Credentials flow. Reset credentials flow If you do not want to reset the OTP, set the Reset OTP requirement to Disabled . Click the Required Actions tab. Ensure Update Password is enabled. 3.8.2. Enabling Remember Me A logged-in user closing their browser destroys their session, and that user must log in again. You can set Red Hat Single Sign-On to keep the user's login session open if that user clicks the Remember Me checkbox upon login. This action turns the login cookie from a session-only cookie to a persistence cookie. Procedure Click Realm Settings in the menu. Click the Login tab. Toggle the Remember Me switch to ON . Login tab When you save this setting, a remember me checkbox displays on the realm's login page. Remember Me 3.8.3. ACR to Level of Authentication (LoA) Mapping In the login settings of a realm, you can define which Authentication Context Class Reference (ACR) value is mapped to which Level of Authentication (LoA) . The ACR can be any value, whereas the LoA must be numeric. The acr claim can be requested in the claims or acr_values parameter sent in the OIDC request and it is also included in the access token and ID token. The mapped number is used in the authentication flow conditions. Mapping can be also specified at the client level in case that particular client needs to use different values than realm. However, a best practice is to stick to realm mappings. For further details see Step-up Authentication and the offical OIDC specification . 3.8.3.1. Update Email Workflow (UpdateEmail) With this workflow, users will have to use an UPDATE_EMAIL action to change their own email address. The action is associated with a single email input form. If the realm has email verification disabled, this action will allow to update the email without verification. If the realm has email verification enabled, the action will send an email update action token to the new email address without changing the account email. Only the action token triggering will complete the email update. Applications are able to send their users to the email update form by leveraging UPDATE_EMAIL as an AIA (Application Initiated Action). Note UpdateEmail is Technology Preview and is not fully supported. This feature is disabled by default. To enable start the server with -Dkeycloak.profile=preview or -Dkeycloak.profile.feature.update_email=enabled . For more details see Profiles . Note If you enable this feature and you are migrating from a version, enable the Update Email required action in your realms. Otherwise, users cannot update their email addresses. 3.9. Configuring realm keys The authentication protocols that are used by Red Hat Single Sign-On require cryptographic signatures and sometimes encryption. Red Hat Single Sign-On uses asymmetric key pairs, a private and public key, to accomplish this. Red Hat Single Sign-On has a single active keypair at a time, but can have several passive keys as well. The active keypair is used to create new signatures, while the passive keypairs can be used to verify signatures. This makes it possible to regularly rotate the keys without any downtime or interruption to users. When a realm is created, a keypair and a self-signed certificate is automatically generated. Procedure Select the realm in the Admin Console. Click Realm settings . Click Keys . Click Passive to view passive keys. Click Disabled to view disabled keys. A keypair can have the status Active , but still not be selected as the currently active keypair for the realm. The selected active pair which is used for signatures is selected based on the first key provider sorted by priority that is able to provide an active keypair. 3.9.1. Rotating keys We recommend that you regularly rotate keys. Start by creating new keys with a higher priority than the existing active keys. You can instead create new keys with the same priority and making the keys passive. Once new keys are available, all new tokens and cookies are signed with the new keys. When a user authenticates to an application, the SSO cookie is updated with the new signature. When OpenID Connect tokens are refreshed, new tokens are signed with the new keys. Eventually, all cookies and tokens use the new keys and after a while the old keys can be removed. The frequency of deleting old keys is a tradeoff between security and making sure all cookies and tokens are updated. Consider creating new keys every three to six months and deleting old keys one to two months after you create the new keys. If a user was inactive in the period between the new keys being added and the old keys being removed, that user will have to re-authenticate. Rotating keys also applies to offline tokens. To make sure they are updated, the applications need to refresh the tokens before the old keys are removed. 3.9.2. Adding a generated keypair Use this procedure to generate a keypair including a self-signed certificate. Procedure Select the realm in the Admin Console. Click Realm settings . Click the Keys tab. Click the Providers tab. Click Add keystore and select rsa-generated . Enter a number in the Priority field. This number determines if the new key pair becomes the active keypair. The highest number makes the keypair active. Select a value for keysize . Click Save . Changing the priority for a provider will not cause the keys to be re-generated, but if you want to change the keysize you can edit the provider and new keys will be generated. 3.9.3. Rotating keys by extracting a certificate You can rotate keys by extracting a certificate from an RSA generated keypair and using that certificate in a new keystore. Prerequisites A generated keypair Procedure Select the realm in the Admin Console. Click Realm Settings . Click the Keys tab. A list of Active keys appears. On a row with an RSA key, click Certificate under Public Keys . The certificate appears in text form. Save the certificate to a file and enclose it in these lines. Use the keytool command to convert the key file to PEM Format. Remove the current RSA public key certificate from the keystore. Import the new certificate into the keystore Undeploy and rebuild the application. 3.9.4. Adding an existing keypair and certificate To add a keypair and certificate obtained elsewhere select Providers and choose rsa from the dropdown. You can change the priority to make sure the new keypair becomes the active keypair. Prerequisites A private key file. The file must be PEM formatted. Procedure Select the realm in the Admin Console. Click Realm settings . Click the Keys tab. Click the Providers tab. Click Add keystore and select rsa . Enter a number in the Priority field. This number determines if the new key pair becomes the active key pair. Click Select file beside Private RSA Key to upload the private key file. If you have a signed certificate for your private key, click Select file beside X509 Certificate to upload the certificate file. Red Hat Single Sign-On autmatically generates a self-signed certificate if you do not upload a certificate. Click Save . 3.9.5. Loading keys from a Java Keystore To add a keypair and certificate stored in a Java Keystore file on the host select Providers and choose java-keystore from the dropdown. You can change the priority to make sure the new keypair becomes the active keypair. For the associated certificate chain to be loaded it must be imported to the Java Keystore file with the same Key Alias used to load the keypair. Procedure Select the realm in the Admin Console. Click Realm settings . Click the Keys tab. Click the Providers tab. Click Add keystore and select java-keystore . Enter a number in the Priority field. This number determines if the new key pair becomes the active key pair. Enter a value for Keystore . Enter a value for Keystore Password . Enter a value for Key Alias . Enter a value for Key Password . Click Save . 3.9.6. Making keys passive Procedure Select the realm in the Admin Console. Click Realm settings. Click the Keys tab. Click the Active tab. Click the provider of the key you want to make passive. Toggle Active to OFF . Click Save . 3.9.7. Disabling keys Procedure Select the realm in the Admin Console. Click Realm settings. Click the Keys tab. Click the Active tab. Click the provider of the key you want to make passive. Toggle Enabled to OFF . Click Save . 3.9.8. Compromised keys Red Hat Single Sign-On has the signing keys stored just locally and they are never shared with the client applications, users or other entities. However, if you think that your realm signing key was compromised, you should first generate new keypair as described above and then immediately remove the compromised keypair. Alternatively, you can delete the provider from the Providers table. Procedure Click Clients in the menu. Click security-admin-console . Click the Revocation tab. Click Set to now . Click Push . Pushing the not-before policy ensures that client applications do not accept the existing tokens signed by the compromised key. The client application is forced to download new key pairs from Red Hat Single Sign-On also so the tokens signed by the compromised key will be invalid. Note REST and confidential clients must set Admin URL so Red Hat Single Sign-On can send clients the pushed not-before policy request.

Commands:
----Begin Certificate---- <Output> ----End Certificate----
keytool -delete -keystore <keystore>.jks -storepass <password> -alias <key>
keytool -importcert -file domain.crt -keystore <keystore>.jks -storepass <password> -alias <key>
wildfly:undeploy mvn clean install wildfly:deploy