Der Beitrag 10/2023 – Today: Transportation (Rails) erschien zuerst auf Carsten Spräner.

Der Beitrag 04/2022 – 10/2023: Department of Justice erschien zuerst auf Carsten Spräner.

There are some examples on the internet to demonstrate how to configure spring-boot version 3+ to use a SAML 2.0 identity provider, but they are using OKTA and not KeyCloak.

This is a demo of implementing SAML 2.0 with spring boot using KeyCloak as IDP. It was pretty challenging because of the little changes to be made when using KeyCloak instead of Okta or adfs.

Example available!

I implemented an example of a spring boot application with KeyCloak and SAML 2.0. You can find it at github here:
https://github.com/carstenSpraener/keycloak-examples 

Tip

Error detection in SAML can be challenging. But it can be simplified by installing some SAML debugging plugins into the browser. I had a good experience with the SAML Tracer plugin. When you activate, it will record the SAML-Requests and show them in a separate panel:

Necessary steps

The necessary steps are the same as using Okta, adsf, or any other SAML 2.0 platform. They are:

• Create a basic spring boot application.
• Configure a client in a realm to use SAML 2.0.
• Configure Spring Boot to use SAML 2.0 as SSO implementation.
• Connect them via metadata URL and private key.

It’s quite simple, but the devil is in the details. So, let’s go through all these steps in Detail.

Create a basic spring boot application

This task is nearly out of the box, but you have to add the following dependencies to your Gradle/maven project (example for Gradle):

implementation 'org.spring framework.boot:spring-boot-starter-security'

implementation 'org.spring framework.security:spring-security-saml2-service-provider:6.1.2'
implementation 'org.thymeleaf.extras:thymeleaf-extras-springsecurity6'

And here is the first Detail! Spring security for saml 2.0 relies on openSaml, which is not hosted on the standard maven repository. So you have to add the following repository to your build file:

repositories {
    mavencentral()
    maven {
        url "https://build.shibboleth.net/maven/releases"
    }
}

Now, Gradle can resolve the dependency to openSaml.

Configuring a client for SAML 2.0 in KeyCloak

You should know what a realm is and how to create one in KeyCloak.

So now, this Realm has to be selected, and a new client has to be created inside that Realm.

Here are the steps:

Again: Be sure that you selected the correct Realm.

Create a new client in that Realm

Notice:

• Client Type is SAML. The default is OpenID Connect. This default has to be changed.
• Detail! The ClientId is the saml2 service provider metadata URL.
• The rest is for information.

On the second page, you need to add the following information:

• The Root URL is the URL of the spring boot application.
• The Home URL is the Homepage URL of the application.
• Valid redirect URIs are the URI(s) to which the user is redirected after a valid login.
• The IDP-Initiated SSO URL name is a postfix for a KeyCloak URL that can be called to log in to the client via KeyCloak. This URL is for IDP-initiated (in this case KeyCloak initiated) login.

Enable Logout in KeyCloak

When your client initiates a logout, the user should be redirected to the Spring Boot Application after the logout succeeded. It would be best to tell KeyCloak which URL the user should be redirected to. Open the Advanced tab in the client’s panel and go to the Logout Service POST Binding URL field.

Here, enter the URL /logout/saml2/slo. As shown here:

That’s it for now. Hit the save button, and your client is created in KeyCloak.

KeyCloak now knows about a client app that will use it as an IDP with the SAML protocol. But the relationship has to be trusted. So, there has
to be some key exchanges. We will do that in a further step. But first, let’s go to the spring boot side to use KeyCloak and create the needed keys and certificates.

Binding your spring boot application to KeyCloak SAML

The SAML-2.0 support for spring boot relies on two main classes that must be created and configured. It is the SecurityFilterChain and a RelyingPartyRegistrationRepository.

The Spring Boot app is the relying party because it relies on the assertions are given from the assertion parts (KeyCloak in this case).

The RelyingPartyRegistrationRepository stores the registration of this relying party to some assertion party by a registration ID.

Creating keys and certificates

SAML communicates via XML-Messages routed through the browser. The messages need to be at least signed to protect them from fake messages. For this purpose, the application requires a key and a certificate to sign the messages sent from the application to KeyCloak. (As it is needed for logout)

To create a pair of keys and certificates, go to then
src/main/resources/config directory and execute the following
command:

openssl req -newkey rsa:2048 -nodes -keyout rp-key.key -x509 -days 365 -out rp-certificate.crt

This command will create two files, rp-key.key and rp-certificate.key. These are the credentials that the Spring Boot application will use to sign messages for KeyCloak. They are valid for 365 days.

Now open the application.yaml file and configure these two files there so we can easily refer them from the application:

saml2:
  rp:
    signing:
      # This pair was generated with the following command:
      # openssl req -newkey rsa:2048 -nodes -keyout rp-key.key -x509 -days 365 -out rp-certificate.crt
      cert-location: /config/rp-certificate.crt
      key-location: /config/rp-key.key

With this, we can later refer to the files in any spring boot component
by:

@Value("${saml2.rp.signing.cert-location}")
private String rpSigningCertLocation;

@Value("${saml2.rp.signing.key-location}")
private String rpSigningKeyLocation;

KeyCloak-Certificate

The third certificate needed is the KeyCloak signing certificate, which the application needs to verify that the message is coming from KeyCloak. To get the certificate, go to the KeyCloak administration site, make sure you selected the right Realm, and then go to Realm Setting and open the Keys Tab. The correct certificate is the RSH256 with Use „SIG“. Click on the marked Certificate button:

This button will open the certificate that you can copy into the clipboard.

When you copy the certificate into the clipboard, open the application.yaml and paste the certificate under the key saml2.ap.signing-cert like this:

saml2:
  ap:
    signing-cert: MIICqTCCAZECBgGJiC2o2jANBgkqhkiG...

The certificate can also be found in the same descriptor XML of your Realm. It is the body of the element X509Certificate.

Note: This is my way of referring to the keys and certificates. There are many other ways to do so. But, well, this is how I did it.

No, let’s get back to the spring boot application.

Enable and Configure Spring Boot security

The next step is to create a configuration bean that also enables SpringSecurity. For that, create a new class and do the following annotation at the class level:

@Configuration
@EnableWebSecurity
public class SamlServiceProviderConfig { 
    ...

These annotations mark the class as a configuration source and will also enable web security for the application.

Next, we need a bean that configures the HTTP security. This configuration is done by creating a new method that returns a SecurityFilterChain and receives a HttpSecurity parameter. Here is an example:

import static org. spring framework.security.config.Customizer.withDefaults;
...

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    HTTP
        .authorizeHttpRequests(authorize -> authorize
            .requestMatchers("/ping").permitAll()
            .requestMatchers("/").permitAll()
            .requestMatchers("**").authenticated()
        )
        .logout( logout -> logout
            .logoutUrl("/")
        )
        //Configure saml2 login with the default values
        .saml2Login(withDefaults())
        // configure saml2 logout with the default values
        .saml2Logout(withDefaults())
    ;
    return http.build();
}

The first part is a typical spring boot security setup based on URL patterns. For SAML, you need to set up saml2Login and saml2Logout with default values.

The method withDefaults() comes from the static import of the class
Customizer , which is shown in the first line.

As mentioned above, we need to create and configure a RelyingPartyRegistrationRepository.
So, there needs to be a second method that creates this repository:

@Value("${saml2.ap.metadata.location}")
private String metadataLocation;

...

@Bean
public RelyingPartyRegistrationRepository relyingPartyRegistrations() throws Exception {
    Resource signingCertResource = new ClassPathResource(this.rpSigningCertLocation);
    Resource signingKeyResource = new ClassPathResource(this.rpSigningKeyLocation);
    try (
            InputStream is = signingKeyResource.getInputStream();
            InputStream certIS = signingCertResource.getInputStream();
    ) {
        X509Certificate rpCertificate = X509Support.decodeCertificate(certIS.readAllBytes());
        RSAPrivateKey rpKey = RsaKeyConverters.pkcs8().convert(is);
        final Saml2X509Credential rpSigningCredentials = Saml2X509Credential.signing(rpKey, rpCertificate);

        X509Certificate apCert = X509Support.decodeCertificate(apCertificate);
        Saml2X509Credential apCredential = Saml2X509Credential.verification(apCert);

        RelyingPartyRegistration registration = RelyingPartyRegistrations
                .fromMetadataLocation(metadataLocation)
                .registrationId("saml-app")
                .singleLogoutServiceLocation("{baseUrl}/logout/saml2/slo")
                .signingX509Credentials(c -> c.add(rpSigningCredentials))
                .assertingPartyDetails(party -> party
                        .wantAuthnRequestsSigned(true)
                        .verificationX509Credentials(c -> c.add(apCredential))
                )
                .build();
        return new InMemoryRelyingPartyRegistrationRepository(registration);
    }
}

That’s much stuff going on here. But let’s break it down.

The first rows are about reading the certificates and keys used to sign and verify the SAML messages. As we configured two values to hold the path to the files, we can now easily access them, create a Resource for them, open an InputStream to the files, and create a Saml2X509Credetial object:

X509Certificate rpCertificate = X509Support.decodeCertificate(certIS.readAllBytes());
RSAPrivateKey rpKey = RsaKeyConverters.pkcs8().convert(is);
final Saml2X509Credential rpSigningCredentials = Saml2X509Credential.signing(rpKey, rpCertificate);

Detail! To use the certificate and key for signing, you have to create the credential with the Saml2X509Credential.singning() method.

To create the assertion party verification credentials, we have to get the certificate from the application.yaml, decode it to an X509 certificate, and generate its verification credentials.

X509Certificate apCert = X509Support.decodeCertificate(apCertificate);
Saml2X509Credential apCredential = Saml2X509Credential.verification(apCert);

Detail! To create a signing verification credential object, you have to call the Saml2X509Credential.verification() method!

Don’t mix up the singing and verification methods of the Saml2X509Credential class. That costs me some time to debug.

Create the registration

The following lines of code are about creating a registration. This registration tells SAML2 in Spring Boot what your identity provider is and how to verify it.

So the line is:

@Value("${saml2.ap.metadata.location}")
private String metadataLocation;

...

RelyingPartyRegistration registration = RelyingPartyRegistrations
        .fromMetadataLocation(metadataLocation)
        .registrationId("saml-app")
        .singleLogoutServiceLocation("{baseUrl}/logout/saml2/slo")
        .signingX509Credentials(c -> c.add(rpSigningCredentials))
        .assertingPartyDetails(party -> party
                .wantAuthnRequestsSigned(true)
                .verificationX509Credentials(c -> c.add(apCredential))
        )
        .build();

The used metadata location is the URL to the SAML-Descriptor of your Realm.
This URL can be found on the KeyCloak Realm Settings page:

Copy that links address and add it to the application.yaml under the key
saml2.ap.metadata.location like:

saml2:
  ap:
    metadata:
      location: http://localhost:8080/realms/SAML-IDP-Test/protocol/saml/descriptor
    signing-cert: MIICqTCCAZECBgGJiC2o2j...

With this link stored in the variable metadataLocation we can now start and create the RelyingPartyRegistration by using ATTENTION RelyingPartyRegistrations (plural) to build the desired instance.

You have to set the following values:

• the metadata location
• the registrationId: This is an arbitrary string. With this string, saml can refer to this APs registration.
• a singleLogoutServicelocation as seen in the example
• the signing certificate created in the previous step
• and the assertingParty parameters.

Our asserting party wants the Authentication Requests to be signed, and it will sign its requests with the certificate stored in the apCredential.

Detail! The Certificate is also included in the descriptor.xml of the IDP/AP, but for some reason, it did not work without setting it explicitly in the RelyingPartyRegistration.

Importing RP-Certificate into KeyCloak

We established a secured connection from the IDP/AP (KeyCloak) to the RP (Spring-Boot Application) with the above steps. But we still need to tell KeyCloak about the signature of the Spring-Boot Application. This upload of the certificate is the final step to establishing the connection.

Import the RPs key into KeyCloak

Go to the KeyCloak administrators page. Check that the correct Realm is selected.
Then, navigate to the Clients Panel, select the Spring-Boot App client, and open the Keys tab. It should look like this:

The Import Key button will open a file import dialog. Choose the
src/main/resources/config/rp-certificate.crt File as the certificate to
import. Select Certificate PEM as Archive format and press Import

Well done! Your login into the application via SAML with KeyCloak as an IDP. It should work now.

But wait! There is no user… So, create a user in the Realm, and you should be able to log in with that user.

Der Beitrag SpringBoot – SAML 2.0 – KeyCloak erschien zuerst auf Carsten Spräner.

Creation of a model-driven approach for the TALL stack.

Within the openSource project cgv19 a model driven approach for the TALL stack (TailwindCSS, AlpineJS, Livewire, Laravel) and the Laravel extension Filament-3 was developed. The project is developed and available as an openSource project on

https://github.com/carstenSpraener/cgV19

It can generate a runnable application from a diagram, as shown here:

Details

• Familiarization with Laravel, Tailwind CSS, AlpineJS, Livewire and Filament-3.
• Implementation of the cartridge for Laravel (LowCode for Laravel/Filament with cgv19)

Activities

Implementation of templates for cgv19 according to programming standards in Laravel and Filament. Implementation of tests for the code generators. Optimization of the generated PHP sources for round-trip engineering with model-driven methods.

IT-Technology

Tailwind CSS, AlpineJS, Livewire, Laravel, PhpStorm, Visual Paradigm, PHP-8, cgv19, Groovy

Der Beitrag 07/2023 – Today: Learning the TALL-Stack (Advanced Training) erschien zuerst auf Carsten Spräner.

Der Beitrag 07/2023 – Today: Prototype of a Symfony Application (Own Development) erschien zuerst auf Carsten Spräner.

Every project with more than one user must have some authentication and authorization. These days, a quite handy and easy-to-use solution for user management comes in a project called KeyCloak. KeyCloak provides all necessary functionality like user registration, sign-in, and sign-in via Google, Facebook, and whatnot, all supporting modern standards like OICD.

KeyCloak is sponsored by Red Hat and is very well maintained. Regular updates and support for new technologies have been seen in recent years. KeyCloak could be a good choice for every company if it trusts open-source projects.

In this post, I describe how to install KeyCloak on a local machine for development purposes. The Version described here is Version 22.0.1.

Downloading and starting KeyCloak

KeyCloak comes in a zip or tar file and can be downloaded from here: https://www.keycloak.org/downloads

If you download the zip file, you can extract it wherever you want and start KeyCloak by:

> cd KeyCloak
> bin/bc.sh start-dev

Attention I tried it with the most recent version 22.0.1 and got an error. KeyCloak 21.1.1 works fine.

After start-up KeyCloak is reachable under the URL

http://localhost:8080

When you first visit this page, KeyCloak will ask you to set an administrator username and password:

Enter the administrator’s username and password, and you will see the new Welcome screen:

Now, you can navigate to the administrator console via the link. Enter
the credentials as specified above, and you will see the main page of KeyCloak:

YEP! That’s it. You set up a KeyCloak instance for your personal development.

What’s next

In the next posts, I will set up a realm for development. A Real is an area where users, roles, groups, and clients are managed.

After that, I will bring KeyCloak into a cloud environment with docker-compose, NgInx, and MariaDB.

Some Notes

• Do not use this setup method for production. For production, you have to do a lot more.
• I tried the new Version 22.0.1 of KeyCloak and got an error during the start procedure:

  ERROR: Failed to run 'build' command.
  ERROR: Name is too long
  For more details run the same command passing the '--verbose' option. Also you can use '--help' to see the details about the usage of the particular command.

This error is still under investigation…

Der Beitrag Using KeyCloak on your local machine erschien zuerst auf Carsten Spräner.

Der Beitrag 06/2023: IT Service Industry erschien zuerst auf Carsten Spräner.

When I first heard someone talking about COBOL online programs, they always used the term „transaction monitor“ and CICS. As a Java developer, I wondered why monitoring a database transaction is so important for developing the 3270-Screens. As I learned now, I couldn’t be more wrong!

In „Jurassic Park“ a „monitor“ is neither a device to show some UI on a screen nor a program that helps you analyze the control flow of a program. A Monitor is more of some kind of system. (As far as I understood. But let me know if I’m wrong). And CICS is one of the very first implementations of such a system to handle user Input in a transactional way. All the old systems that turned the world from the 60s to today are developed with this transaction monitor CICS.

So CICS is very similar to Jakarta EE or a REST Controller from a conceptual point of view. It is how you handle user input and process it in an „All or Nothing“ transactional way.

Since CICS is a commercial product and is not free to the public, there is now a (legal) way to get it run on a Hercules emulator. But there is a free alternative that is somehow compatible with CICS. At least on the API Level. This alternative is KICKS!

The installation process of KICKS is quite complicated. The YouTuber moshix made a nice video that you can follow up, and you will have a running KICKS-System on your Hercules-driven MVS/TK4 Mainframe.
When you finish with video, you should be able to start the KICKS-Transaction-Monitor under the user HERC01.

But I want to use it under my own user ID, and that needs a little extra work. As the KICKS-Documentation says, you have to allow access to the VSAM-Files to everybody. So log on as HERC01, and open the data set „SYS2.SECURE.CNTL(PROFILES) and add the following lines to the end. (Unbelievable. I understand what I’m writing here!)

DATASET HERC01.KICKS.MURACH.CUSTMAS                         UPDATE
DATASET HERC01.KICKS.MURACH.INVCTL                          UPDATE
DATASET HERC01.KICKS.MURACH.INVOICE                         UPDATE
DATASET HERC01.KICKS.MURACH.INVOICE.PATH                    UPDATE
DATASET HERC01.KICKS.MURACH.PRODUCT                         UPDATE
DATASET HERC01.KICKS.TACDATA                                UPDATE
DATASET HERC01.KICKS.V1R5M0.SDB                             UPDATE
DATASET HERC01.KICKSSYS.V1R5M0.KIKINTRA                     UPDATE
DATASET HERC01.KICKSSYS.V1R5M0.KIKTEMP                      UPDATE

The editor screen should look something like this:

Saving the file and restart rakf (or the whole Hercules to be saved).

Next, you should copy the member KICKS and KFIX to the SYS2.PROCLIB data set. The tool MOVE/COPY (option 3.3) is very handy for this task, and I managed it without reading any manuals.

When you finish these copies, you can log off and log on as a regular user. CASI, in my case.

Now, it should be able to launch KICKS from the TSO command prompt. I tried and…. failed. After a little research and asking the experts at Discord, it turned out that I forgot the ‚ !! So the correct command to start KICKS is:

EXEC 'SYS2.CMDPROC(KICKS)'

With this command (AND DO NOT MISS THE APOSTROPHE!), the system will start. Press the CLEAR Button and enter BTC0, and you will see the TAC-Transaction used in the Nevada Department of Labor in the 70s.

There are some other transactions also installed. Especially all the examples in Murach’s bible of „CICS for the COBOL Programmer“. I think I’m now done with installing Hercules, TK4, ROB enhancements, and KICKS. So, the next step could be implementing the first online transaction in COBOL.

Der Beitrag KICKS-Starter! erschien zuerst auf Carsten Spräner.

Hercules is actively developed under the project Hercules Hyperion, and the current release, 4.5 is available on GitHub. I tried to compile it on my macOS but had some trouble with the software not being available, so I decided to give Docker a chance and carry this cute little Dinosaur. And it was actually relatively easy. (Attention: This approach is only tested on x86 architectures. I tried a build on a Raspberry Pi 4 with 64Bit, and it failed due to missing external libraries. I’m working on it)

First, I cloned the GitHub repository on a local directory.

git clone https://github.com/SDL-Hercules-390/hyperion.git

Then, you will have the whole project on your local drive. The installation instructions in the project documentation are straightforward, so I followed them up in a Dockerfile. (Copy this Dockerfile into the project directory.)

#
# Start building hercules-hyperion docker image from a debian base
# since it does not need many stuff the slim image should be sufficient
#
# The extra software is installed with apt.
#
FROM debian:stable-slim AS env

RUN mkdir /opt/build &&\
    apt-get update &&\
    apt-get -y install git wget time &&\
    apt-get -y install build-essential cmake flex gawk m4 autoconf automake libtool-bin libltdl-dev &&\
    apt-get -y install libbz2-dev zlib1g-dev &&\
    apt-get -y install libcap2-bin

# No the environment is set and the build can Start
# copy all the project files into the build directory and Start
# building it.
#
FROM env AS build

WORKDIR /opt/build

COPY . /opt/build

RUN ./configure &&\
    mkdir /opt/hercules &&\
    make &&\
    make install &&\
    /sbin/ldconfig -v

#
# With the hercules hyperion build it is no easy to Start
# hercules.
#
# The docker image expects a working area mounted to /opt/hercules
# and in that directory there must be the configuratio under conf/herculues.cnf
# The start script inside the hercules console has to be under scripts/ipl.rc
#
#  <DirecotryMountedUnder/opt/hercules>
#   .
#   +--conf/hercules.cnf
#   +--scripts/ipl.rc
#
FROM build AS hercules-hyperion
WORKDIR /opt/build
VOlUME /opt/hercules

CMD ["/bin/bash", "/opt/build/container-start"]

The Dockerfile has three stages. The first stage starts from the Debian-slim image and follows the installation instructions of the project documentation. It leaves a stage env to use in the next stage.

The stage build copies the entire project into the working directory of the image and follows the make instructions of the project documentation. This leads to a new stage build with a compiled and installed Hercules inside. I only needed to add the /sbin/ldconfig -v command to make the Hercules libraries accessible in the image.

The third stage is the final one, which builds the final image and makes Hercules run in a docker container. It uses a little bash script:

#!/bin/bash

(
cd /opt/hercules
export HERCULES_RC=scripts/ipl.rc
hercules -f conf/hercules.cnf -d >3033.log
)

The script changes to a directory /opt/Hercules sets the environment variable HERCULES_RC to scripts/ipl.rc, and starts the Hercules emulator. As you can see, this script implies some setups from the user. You have to mount a directory with your own Hercules environment under /opt/Hercules, and in that environment, you have to store the configuration under conf/Hercules.cnf and the startup script under scripts/ipl.rc

Starting Hercules is one thing. But installing the software and bringing it all together is a much more difficult task. At least for me as a Java developer. There are some readily defined distributions with all devices, dasds, configs, and start scripts needed available, and you surely want to use them. Like the TK-4 distribution mentioned in the other articles. This distribution has the configuration under conf/tk4-.cnf. Copy it to conf/Hercules.cnf and you are fine. The start script is under scripts/ipl.rc as the container script requires.

docker build -t hercules-hyperion .

When you start the docker build like:

Docker will create the image. To start the image, use this command:

docker run -v /<YOUR HERCULES ENVIRONMENT DIRECTORY>:/opt/hercules \
    -p 3270:3270 \
    -p 3278:3278 \
    -p 8038:8038 \
    --name hercules \
    hercules-hyperion

Now you have a running Hercules 4.5 Hyperion instance in docker. The ports are exposed to 3270 (3270-Terminal emulation), 3278 (Telnet port), and 8038 (Web-Server)

Der Beitrag Running HERCULES 4.X Hyperion in a Docker Container erschien zuerst auf Carsten Spräner.

• Running MVS on your own emulated Mainframe or…
  … welcome to Jurassic Parc. The world of the Dinosaurs. I’ve been a Java programmer since my very first days as a professional software engineer. Before that, I started programming with BASIC and Assembler on a Commodore +4. During my studies, is programmed C on an ATARI-ST or Solaris Workstations. My first job was in ...
• Installing and starting HERCULES and MVS
  The easy part… installing and starting HERCULES today (2023) really is no problem at all. It can run on any commonly used OS like Windows, macOS, and Linux. I chose my old Raspberry Pi 3B as my mainframe platform. And it does the job quite well for one user. So, how is it going: My first try ...
• Running HERCULES 4.X Hyperion in a Docker Container
  … when two worlds come together Hercules is actively developed under the project Hercules Hyperion, and the current release, 4.5 is available on GitHub. I tried to compile it on my macOS but had some trouble with the software not being available, so I decided to give Docker a chance and carry this cute little Dinosaur. ...
• KICKS-Starter!
  …installing a „Transaction Monitor“ When I first heard someone talking about COBOL online programs, they always used the term „transaction monitor“ and CICS. As a Java developer, I wondered why monitoring a database transaction is so important for developing the 3270-Screens. As I learned now, I couldn’t be more wrong! In „Jurassic Park“ a „monitor“ is neither ...

Der Beitrag erschien zuerst auf Carsten Spräner.