Monday, 29 May 2017

Easily secure your Spring Boot applications with Keycloak

What is Keycloak?

Although security is a crucial aspect of any application, its implementation can be difficult. Worse, it is often neglected, poorly implemented and intrusive in the code. But lately, security servers have appeared which allow for outsourcing and delegating all the authentication and authorization aspects. Of these servers, one of the most promising is Keycloak, open-source, flexible, and agnostic of any technology, it is easily deployable/adaptable in its own infrastructure. Moreover, Keycloak is more than just an authentication server, it also provides a complete Identity Management system, user federation for third parties like LDAP and a lot more ... Check it out on here. The project can also be found on Github

Thursday, 11 May 2017

Criticial vulnerability fixed in Keycloak Node.js adapters

A criticial vulnerability was discovered in Keycloak Node.js adapters. We highly recommend everyone upgrades to version 3.1.0 of the adapter immediately. This adapter will work with Keycloak 2 and upwards.

For more details see CVE-2017-7474.

Wednesday, 3 May 2017

Keycloak 3.1.0.Final Released

Keycloak 3.1.0.Final has just been released.

To download the release go to the Keycloak homepage.

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the migration guide.

Thursday, 27 April 2017

Keycloak 3.1.0.CR1 Released

Keycloak 3.1.0.CR1 has just been released.

To download the release go to the Keycloak homepage.

Highlights

  • X509 Certificate user authentication - Thanks to Peter Nalyvayko for the contribution
  • Proof Key for Code Exchange by OAuth Public Clients - Thanks to Takashi Norimatsu for the contribution
  • WildFly Elytron adapters - Adapters for Elytron, a new security subsystem coming in WildFly 11 and EAP 7.1
  • TypeScript type definitions for keycloak.js - Simplifies using keycloak.js from TypeScript
  • Identity Provider for Openshift - Thanks to Bartosz Majsak for the contribution

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the migration guide. Release candidates are not recommended in production and we do not support upgrading from release candidates.

Thursday, 23 March 2017

How to Setup MS AD FS 3.0 as Brokered Identity Provider in Keycloak

This document guides you through initial setup of Microsoft Active Directory Federation Services 3.0 as a brokered identity provider Keycloak.

Prerequisites

  • Two server hosts:
    • Microsoft Windows Server 2012 with Active Directory Federation Services (AD FS) installed. The AD domain will be named DOMAIN.NAME in this post.
    • Keycloak server. This can be generally placed anywhere but here it is expected to be running on separate host
  • DNS setup:
    • The Windows host name will be fs.domain.name in this post
    • The Keycloak host name will be kc.domain.name in this post

Setup Keycloak Server

Keycloak server has configured for SSL/TLS transport - this is mandatory for AD FS to communicate with it. This comprises two steps:
  • Setup keycloak for incoming HTTPS connections - steps are provided here.
  • Export AD FS certificate into a Java truststore to enable outgoing HTTPS connections:
    • In the AD FS management console, go to Service → Certificates node in the tree and export the Service communications certificate.
    • Import the certificate into a Java truststore (JKS format) using Java keytool utility.
    • Setup the truststore in Keycloak as described here.

Setup Identity Provider in Keycloak

Setup Basic Properties of Brokered Identity Provider

In the Identity Providers, create a new SAML v2.0 identity provider. In this post, the identity provider will be known under alias adfs-idp-alias.
Now scroll to the bottom and enter the AD FS descriptor URL into Import from URL field. For AD FS 3.0, this URL is https://fs.domain.name/FederationMetadata/2007-06/FederationMetadata.xml. Once you click “Import”, check the settings. Usually, you would at least enable Validate signature option.
If the authentication requests sent to the AD FS instance are expected to be signed, which is also usually the case, you have to enable Want AuthnRequests Signed option. Importantly, then the SAML Signature Key Name field that shows after enabling the Want AuthnRequests Signed option has to be set to CERT_SUBJECT as AD FS expects the signing key name hint to be the subject of the signing certificate.
The AD FS will be set up in the next step to respond with name ID in Windows Domain Qualified Name format, hence set the NameID Policy Format field accordingly.


Setup Mappers

In the steps setting AD FS below, AD FS will be set up to send email and group information in SAML assertion. To transform these details from SAML document issued by AD FS to Keycloak user store, we’ll need to set up two corresponding mappers in the Mappers tab of Identity Provider:
  • Mapper named Group: managers will be of type SAML Attribute to Role, and will map attribute named http://schemas.xmlsoap.org/claims/Group, if that has attribute value managers, to role manager.


  • Mapper named Attribute: email will be of type Attribute Importer, and will map attribute named http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress into user attribute named email.

Obtain information for the AD FS configuration

Now we determine SAML service provider descriptor URI that will be used in AD FS setup from the Redirect URI field in the identity provider detail by adding “/descriptor” to the URI in this field. The URI will be similar to https://kc.domain.name:8443/auth/realms/master/broker/adfs-idp-alias/endpoint/descriptor. You can check whether you got the URI right by entering the URI into the browser - you should receive a SAML service provider XML descriptor.

Setup Relying Party Trust in AD FS

Setup Relying Party

In AD FS Management console, right-click Trust relationships → Relying Party Trusts and select Add Relying Party Trust from the menu:




At the beginning of the wizard, enter the SAML descriptor URL obtained in the previous step into the Federation metadata address field, and let AD FS import the settings. Proceed with the wizard, and adjust the settings where appropriate. Here we use only the default settings. Note that you will need to edit the claim rules so when asked to do so at the last page of the wizard, you can leave the checkbox checked on.

Setup Claim Mapping

Now the SAML protocol would proceed correctly, AD FS would be able to correctly authenticate the users according to requests from Keycloak, but the requested name ID format is not yet recognized and SAML response would not contain any additional information like e-mail. It is hence necessary to map claims from AD user details into SAML document.
We will set up three rules: one for mapping user ID, second for mapping standard user attributes, and third for a user group. All start by clicking the Add Rule button in the Edit Claim Rules for kc.domain.name window:




The first rule will map user ID in Windows Qualified Domain name to the SAML response. In the Add Transform Claim Rule window, select Transform an incoming claim rule type:




The example above targets windows account name ID format. Other name ID formats are supported but out of scope of this post. See e.g. this blog on how to setup name IDs for persistent and transient formats.


The second rule will map user e-mail to the SAML response. In the Add Transform Claim Rule window, select Send LDAP attributes as Claims rule type. You can add other attributes as needed:




The third rule would send a group name if the user is member of a named group. Start again in the Add Transform Claim Rule window, and select Send Group Membership as a Claim rule type. Then enter the requested values in the field:




This setup would send an attribute named Group in the SAML assertion with value managers if the authenticated user is member of the DOMAIN\Managers group.

Troubleshooting

As a first-hand tool, you should check SAML messages sent back and forth between Keycloak and AD FS in your browser. The SAML decoders are available as browser extensions (e.g. SAML Tracer for Firefox, SAML Chrome Panel for Chrome). From the captured communication, you might see error status codes as well as the actual attribute names and values in SAML assertion necessary for setting up mappers. For example, if name ID format is not recognized, AD FS would return a SAML response containing urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy status code.


As a second resort, check the logs. For AD FS, the logs are available in the Event viewer under Applications and Services Logs → AD FS → Admin. In Keycloak, you can enable tracing of the SAML processing by connecting to the running Keycloak instance via jboss-cli.sh and entering the following commands:


/subsystem=logging/logger=org.keycloak.saml:add(level=DEBUG)
/subsystem=logging/logger=org.keycloak.broker.saml:add(level=DEBUG)


Then you will be able to find the SAML messages and broker-related SAML processing messages in the Keycloak server log.

Common issues

Q: I cannot log out! When I click logout in my app, it seems I’m logged out from Keycloak but when I return to the app, AD FS login form never displays and I’m redirected back authenticated as the same user as previously!
A: Don’t panic. This is not a Keycloak issue, rather AD FS settings of authentication policy. Try disabling Windows Authentication before reporting an issue.

Q: While using AD FS in Windows 2016, the following error appeared in Keycloak log after importing the descriptor from URL: RESTEASY002010: Failed to execute: javax.ws.rs.NotFoundException: RESTEASY003210: Could not find resource for full path: https://kc.domain.name/auth/realms/master/broker/adfs-idp-alias/endpoint/descriptor/FederationMetadata/2007-06/FederationMetadata.xml. Does it cause any harm?
A: It is harmless. It seems that Windows 2016 version first checks for AD FS-like descriptor URL by adding FederationMetadata/2007-06/FederationMetadata.xml to the entered URL. Such resource does not exist in Keycloak, so it reports error. AD FS however seems to import using the entered URL when this happens. Please see also the original email discussion on this issue. 

Conclusion

If you get stuck, do not hesitate to write a question to keycloak-user mailing list.


As there is always room for improvement, if you find any issue or have any suggestion on this text, feel free to leave a comment!

Wednesday, 22 March 2017

Keycloak 3.0.0.Final released

Keycloak 3.0.0.Final is released.

To download the release go to the Keycloak homepage.

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the migration guide.

Thursday, 16 March 2017

Keycloak 3.0.0.CR1 released

Keycloak 3.0.0.CR1 is released. Even though we've been busy wrapping up Keycloak 2.5 we've managed to include quite a few new features.

To download the release go to the Keycloak homepage.

This release is the first that comes without Mongo support.

Highlights

  • No import option for LDAP - This option allows consuming users from LDAP without importing into the Keycloak database
  • Initiate linking of identity provider from application - In the past adding additional identity brokering accounts could only be done through the account management console. Now this can be done from your application
  • Hide identity provider - It's now possible to hide an identity provider from the login page
  • Jetty 9.4 - Thanks to reneploetz we now have support for Jetty 9.4
  • Swedish translations - Thanks to Viktor Kostov for adding Swedish translations
  • Checksums for downloads - The website now has md5 checksums for all downloads
  • BOMs - We've added BOMs for adapters as well as Server SPIs

The full list of resolved issues is available in JIRA.

Upgrading

Before you upgrade remember to backup your database and check the migration guide.