oc new-app quay.io/sshaaf/mailcatcher --name=mailcatcher
oc expose svc/mailcatcher --port 8080Server Setup
Now that we have the server installed, lets make a few basic configuration changes to get started.
In this section we will view some of the current configuration and also add smtp config and email addresses so that our SSO server can communicate with the end users. We will then test our flow with Email verification and user registrations.
What is a Realm
A realm is the logical namespace for all configurations, options, for a given group or applications or services. A realm secures and manages security metadata for a set of users, applications, and registered identity brokers, clients etc. Users can be created within a specific realm within the Administration console. Roles (permission types) can be defined at the realm level and you can also set up user role mappings to assign these permissions to specific users. A user belongs to and logs into a realm. Realms are isolated from one another and can only manage and authenticate the users that they control.
For this example we will configure our demo realm which needs to be created.
Click on the left menu, and press the button Add Realm
Lets give it a name demojs. We are calling it demojs, as the name denotes, our first applictation will be a simple Java Script Console. This console will help us do some fun exercises and learn more about Red Hat SSO. So whats the difference between the Master Realm that was already created and why did we create a new one?
The Master Realm
The initial realm is the master realm. It is the highest level in the hierarchy of realms. Admin accounts in this realm have permissions to view and manage any other realm created on the server instance. When you define your initial admin account, you create an account in the master realm. Your initial login to the admin console will also be via the master realm.
It is recommended that you do not use the master realm to manage the users and applications in your organization. Reserve use of the master realm for super admins to create and manage the realms in your system. 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.
It is possible to disable the master realm and define admin accounts within each individual new realm you create. Each realm has its own dedicated Admin Console that you can log into with local accounts.
Setting up email integration
With Single Sign-On we expect there will be users logging in, there is integration to OAuth etc. Obviously we need to have an email integration so SSO server can send verfication emails etc.
To start lets setup a mail server that has a catchall and is only used for testing. MailCatcher runs a super simple SMTP server which catches any message sent to it to display in a web interface. By running mailcatcher we can get all the emails within our setup for testing and we wont need to use our personal or corporate emails for this. Its a great utility. the mail server is setup on port '1025' and the html interface to recieve and send should be setup on port '8080'. Lets create our test mail server by running the following commands.
1. the first command will initiate the mailcatcher server
2. the second ones exposes the port 8080 to ensure we have the http end point setup for viewing the emails recieved.
Once the installation is done you should see it as follows.
Lets configure our new realm demojs. Just a small config we should do before that. Since we plan to use emails lets add the Admin email account details too.
Ensure you are logged into the SSO admin console. Once logged in click on menu at the right hand corner of the SSO Admin console.
Click on Manage account, this will bring you to the Admin user profile.
Make sure you setup a valid email address that is reachable and also fill in the name fields.
Once done press save and click on Back to Security Admin Console.
Now goto the realm settings by clicking on the demojs Realm.
Press the email Tab, and lets configure it.
1. Further more ensure that Enable SSL, Enable StartTLS and Enable Authentication are selected.
2. Also ensure that you have filled in the From Display Name, its not mandatory, but for this tutorial if users are sharing emails, it will help alot.
Once done making changes save.
Now lets make a quick test. Test Connection, once pressed will report back if your configuration was successful. If it is, an email should arrive in your inbox, with a subject e.g.
'[KEYCLOAK] - SMTP test message'
Goto the mailcatcher service and you should see something similar.
Perfect, now we have the email configuration.
Lets move on to the Login tab.
Enable the following:
User Registration, User registration allows new users to register to the SSOVerify Email, and this will ensure that we can verify the user by thier email.
Press Save
Now lets test our basic config. Open a new browser session in privacy mode, or open another browser.
Ensure that you are not logged into the SSO admin panel in the newly opened browser sessions.
1. It should show a login screen, with a link under the buttons to register.
2. Hit the register button and register a new user.
3. Ensure that you fill in the right email address, since an email will be sent to verify the newly created user. ensure that this email address is not the same as used previously in this excercise.
Once you have registered you should see the following message:
Head over to your email and you should have recieved a new email. Click on the link in the email to verify this new user. Now you should be able to login to the admin console with your new user.
Great, so now we have some basic config for our RH-SSO server and its realm. Lets head off to the next section where we will deploy our first application. And subsequently configure it to use RH-SSO.