Golang Keycloak SAML Usage
This document analyzes using Keycloak’s SAML with Golang.
1. Certificate Generation
SAML Service Provider requires a certificate. Generate a certificate using the following command.
$ openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"2. Service Provider Code
| |
[Code 1] is a SAML Service Provider App that authenticates Users through a SAML Identity Provider and outputs SAML Session information obtained through the authentication process. The complete App Code can be found in the following Repo.
The operation process is as follows.
- When a User accesses the “/session” Path of the Service Provider, the Service Provider sends a SAML Request to the Identity Provider through the RequireAccount() Middleware function to redirect the User for authentication. The SAML Request also includes the URL information requested by the User after authentication.
- When authentication is completed through the Identity Provider, the Identity Provider redirects the User back to the Service Provider’s ACS Endpoint “/saml/acs” that was previously registered, and also sends the SAML Response containing authentication information to the ACS Endpoint. The SAML Response also includes the URL information requested by the User that was included in the SAML Request.
- The Service Provider’s ACS receives the SAML Response, verifies the authentication information, and sets authentication in the Web Browser’s Cookie. Afterward, the Service Provider redirects the User back to the URL requested by the User included in the SAML Response so that the User can use the service.
The line-by-line explanation of [Code 1] is as follows.
- Line 3, 51 : The samlRequestPrinter() function is a Middleware that outputs requests coming to the ACS.
- Line 12 : The echoSession() function is a function that returns Session information set by SAML.
- Line 55 : The samlSP.RequireAccount() function is a Middleware that requests authentication from the Identity Provider when accessing the “/session” path.
3. Service Provider Metadata Extraction
The Metadata of the Service Provider in [Code 1] must be extracted. The extracted Metadata is used to register the Service Provider with the Identity Provider. Extract the Service Provider’s Metadata using the following command. The Service Provider in [Code 1] can extract it through the “/saml/metadata” path.
$ go run main.go
$ curl localhost:8000/saml/metadata > metadata4. Keycloak Installation and Configuration
Install Keycloak using Docker. Set Keycloak’s Admin ID/Password to admin/admin.
$ docker run --name keycloak -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin -d quay.io/keycloak/keycloak:17.0.0 start-dev![[Figure 1] Realm Creation](/blog-software/docs/programming/golang-keyclock-saml/images/keycloak-create-realm.png)
[Figure 1] Realm Creation
After accessing “localhost:8080” and logging in with the Admin account, create a “ssup2” Realm as shown in [Figure 1]. Keycloak’s Realm represents the authentication scope. Multiple Service Providers can be registered in one Realm.
![[Figure 2] Client Creation](/blog-software/docs/programming/golang-keyclock-saml/images/keycloak-create-client.png)
[Figure 2] Client Creation
Load the Metadata extracted from the Service Provider and create a Client as shown in [Figure 2].
![[Figure 3] Client Signature Off](/blog-software/docs/programming/golang-keyclock-saml/images/keycloak-create-client-signature.png)
[Figure 3] Client Signature Off
Enter the created Client as shown in [Figure 3] and turn off Client Signature Required. This is necessary because the Service Provider uses an arbitrary certificate.
![[Figure 4] User Password Setting](/blog-software/docs/programming/golang-keyclock-saml/images/keycloak-user-password.png)
[Figure 4] User Password Setting
Create a “users” Group and create a “user” User under the “users” Group. Then set the Password of the created “user” User to “user” as shown in [Figure 4].
![[Figure 5] User Role Check](/blog-software/docs/programming/golang-keyclock-saml/images/keycloak-user-role.png)
[Figure 5] User Role Check
Then check the Role of the created “user” User as shown in [Figure 5].
5. Service Provider Execution
![[Figure 6] User Login](/blog-software/docs/programming/golang-keyclock-saml/images/keycloak-user-login.png)
[Figure 6] User Login
| |
When you run the Service Provider and access the “/session” Path, you can see a Login screen like [Figure 6] through the URL in [Text 1]. Looking at [Text 1], you can see “SAML Request” and “Relay State” in the URL’s Query format. SAML Request is an authentication request sent by the Service Provider to the Identity Provider (Keycloak), and Relay State is a value that the Identity Provider delivers to the Service Provider’s ACS along with “SAML Response” after the Identity Provider’s authentication process, used to determine what action the Service Provider should perform after authentication.
| |
By performing URL Decoding, Base64 Decoding, and XML Inflate on the SAML Request value in [Text 1], you can obtain the XML-formatted [Text 2] SAML Request.
| |
[Text 3] shows the Request that Keycloak delivers to the Service Provider’s ACS Endpoint after authentication is completed in Keycloak. You can see that the Request’s Body contains “SAML Response” and “Relay State”. You can see that the Relay State is the same as the Relay State in [Text 1]. The Service Provider determines and performs redirecting the User to the “/session” Path through the Relay State delivered to the ACS Endpoint.
| |
By performing URL Decoding and Base64 Decoding on the SAML Response in [Text 3], you can obtain the XML-formatted SAML Response like [Text 4].
| |
When accessing the Service Provider’s “/session” Endpoint, you can check the current Session information as shown in [Text 5]. You can see that the Role includes the Role from [Figure 5].
6. References
- https://www.keycloak.org/getting-started/getting-started-docker
- https://docs.anchore.com/3.0/docs/overview/sso/examples/keycloak/
- https://github.com/crewjam/saml
- https://goteleport.com/blog/how-saml-authentication-works/
- https://www.rancher.co.jp/docs/rancher/v2.x/en/admin-settings/authentication/keycloak/