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.

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.

Wednesday, 15 March 2017

Keycloak 2.5.5.Final Released

Keycloak 2.5.5.Final is out. There's nothing much except a handful bug fixes, but it's still worth upgrading.

To download the release go to the Keycloak homepage.

Highlights

  • A few bug fixes

The full list of resolved issues is available in JIRA.

Upgrading

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

Wednesday, 22 February 2017

Keycloak 2.5.4.Final Released

Keycloak 2.5.4.Final is out. There's nothing much except a handful bug fixes, but it's still worth upgrading.

To download the release go to the Keycloak homepage.

Highlights

  • A few bug fixes

The full list of resolved issues is available in JIRA.

Upgrading

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

Monday, 6 February 2017

Removing Mongo support from Keycloak

At times you have to make hard decisions and this has been one of those. We have decided to remove Mongo support from Keycloak. The primary motivation behind this decision is that we simply don't have the resources to maintain and further develop the back-end for both relational databases and Mongo. Further, there are some fundamental issues with our current use of Mongo that would require a large amount of work to become fully production ready. This primarily boils down to the lack of ACID transactions in Mongo.

We hope that this decision won't result in too much trouble for those of you that are currently using Mongo as the back-end for Keycloak. It should be relatively painless to migrate to a relational database with our export/import feature. If you do run into issues with this please let us know on the mailing list and we will do whatever we can to help make the transition as smooth as possible.

If anyone from the community would like to take over the Mongo support and maintain it as a separate extension please let us know. We can help with extracting the code and work together in making it easy to install it as an extension.

Migrating from Mongo to relational database

First step is to export the full database. You can do this by stopping the Keycloak server and running:

bin/standalone.sh -Dkeycloak.migration.action=export -Dkeycloak.migration.provider=dir -Dkeycloak.migration.dir=backup

This will export all data from Mongo to JSON files within the directory backup. For full details refer to the Server Administration Guide.

Next step is to install a relational database and configure it in Keycloak. Take your pick we support quite a few. For full details refer to the Server Installation Guide.

Once you have the relational database ready and configured, you can start Keycloak and import the data exported from Mongo. To do this run Keycloak with:

bin/standalone.sh -Dkeycloak.migration.action=import -Dkeycloak.migration.provider=dir -Dkeycloak.migration.dir=backup

Hopefully you're now up and running with all your realms and users migrated to the relational database. If not, let us know on the user mailing list and we'll help you out as soon as possible.

Thursday, 26 January 2017

Administer Keycloak server from shell with Admin CLI

A few months ago we introduced Client Registration CLI - a tool for registering new clients with Keycloak server in a self-service manner.

With release 2.5.0 we now also have Admin CLI - a general purpose administration tool that an admin can use to perform a full set of actions over Admin REST API without having to use a web based Admin Console.

This tool should come especially handy in combination with shell scripts or tools like Ansible or Docker, where before one would have to resort to using curl or wget in a much more cumbersome way.

You can find Admin CLI execution scripts in KEYCLOAK/bin directory - there's kcadm.sh for Bash, and kcadm.bat for Windows CMD.

Running the tool without any parameters will greet you with some help to get you started.

$ kcadm.sh

Typical usage begins with authentication step where user or client credentials are provided.

$ kcadm.sh config credentials --server http://localhost:8080/auth --realm master --user admin --password admin

Session is maintained by saving an access token into a configuration file - by default it is at ~/.keycloak/kcadm.config.

You can also pass authentication parameters to any other commands together with --no-config option, which will skip using a config file altogether - authentication, access token retrieval, and operation invocation will all be part of a single command execution after which the token will simply be forgotten.

Assuming we've authenticated using a configuration file we can then perform operations against Admin REST endpoints. For example, you may want to create a new realm with roles, clients, some users, then reset a user's password, and set up events logging.

Create a new realm

$ kcadm.sh create realms -s realm=demo -s enabled=true

Create new realm roles

$ kcadm.sh create roles -r demo -s name=admin
$ kcadm.sh create roles -r demo -s name=user


Create a new public client

$ kcadm.sh create clients -r demo -s clientId=myapp -s publicClient=true -s 'redirectUris["http://localhost:8980/myapp/*"]' -o

Create a new user

$ SUPER_ID=`kcadm.sh create users -r demo -s username=super -i`

Add client role to a user

$ kcadm.sh add-roles -r demo --uusername super --cclientid realm-management --rolename realm-admin

Add realm roles to a user

$ kcadm.sh add-roles -r demo --uusername super --rolename admin --rolename user

Update a user

$ kcadm.sh update users/$SUPER_ID -r demo -s enabled=true

Change user's password

$ kcadm.sh set-password -r demo --username super --password password


We can now login as a newly created user so we don't have to continually specify the target realm:

$ kcadm.sh config credentials --server http://localhost:8080/auth --realm demo --user super --password password

Get existing users

$ kcadm.sh get users --limit 20

Get existing clients

$ kcadm.sh get clients --fields id,clientId,publicClient,redirectUris


Setup login events logging

$ kcadm.sh update events/config -s eventsEnabled=true

Get last twenty login events

$ kcadm.sh get events --offset 0 --limit 100


As you may have guessed by now Admin CLI is pretty generic. You specify a command followed by a target endpoint URI which will be resolved relative to Admin REST API root, and current realm as specified with --realm option during authentication. It also takes target realm override into account which you specify with -r option. This way any Admin REST API endpoint can be reached. Content to send is specified by using -s option - specified attributes become part of a JSON document sent to a target URI.


You can find a more comprehensive list of recipes for specific tasks in Admin CLI chapter of a Server Administration Guide.


Give Admin CLI a try, and let us know how it works for you.