Keycloak 2.2.1.Final has just been released. This release fixes an issue in the JavaScript adapter that was introduced in 2.2.0.Final, for more details see KEYCLOAK-3586.
To download the release go to the Keycloak homepage.
↧
Keycloak 2.2.1.Final Released
↧
Keycloak 2.3.0.CR1 Released
We've just released Keycloak 2.3.0.CR1. This release brings a number of new existing features!
Highlights of the release includes:
- OpenID Connect certification - We've now completed the work on making our OpenID Connect implementation pass the OpenID Connect certification and we're currently passing all 5 profiles!
- User SPI - We now have a new simpler User SPI. This will make it easier to implement a custom user provider to pull in users from any external user store. In the next release we'll port our LDAP provider to this SPI, which will make it possible to pull in users from LDAP without syncing data to the Keycloak database. Once this work is completed we'll remove the old User Federation SPI.
- Realm Key Rotation - We now support multiple keys in a realm. This makes it possible to seamlessly rotate keys without any impact to applications and users.
- Client Registration CLI - A while back we added dynamic client registration capabilities, we've now created a CLI that makes it easy to register and update clients from the command-line.
- Dynamic Client Registration Policies - We've introduced a mechanism to control what clients can be dynamically created. This includes the ability to define policies to allow clients to register without the need to authenticate.
- Node.js Adapter - We've had a Node.js adapter a while, but we've now polished it a lot and made it a first class citizen.
↧
↧
Keycloak 2.3.0.Final Released
Keycloak 2.3.0.Final has just been released.
For the list of resolved issues check out JIRA and to download the release go to the Keycloak homepage. Before you upgrade refer to the migration guide
↧
Registering new clients from shell
Keycloak comes with a powerful web admin console that is a primary tool for configuring everything in Keycloak. As powerful as it is it does not lend itself to scripting. Automation requires the ability to script the admin tasks, and to facilitate that we've been working on CLI tools that would be friendly for automation as well as interactive shell use.
The first of the CLI tools - Client Registration CLI - is now available as part of Keycloak distribution. It allows creating and updating new clients - operations you would otherwise have to do in Web Admin Console under Clients section.
Client Registration CLI can be used by application developers that integrate their applications with Keycloak server, and don't necessarily have administrative privileges on the server itself. That is possible by way of special client creation tokens called Initial Access Tokens that can be issued by realm administrator, and distributed to developers for them to self-service. In that case developer doesn't even need a user account, Initial Access Token is their means of authenticating to perform client creation operations.
The Client Registration CLI can also be used by applications and services to dynamically self-register themselves. This makes it possible to automate the creation and management of client configuration by applications and services themselves.
In theory such self-service can be performed by using generic tools like curl or wget, but in reality the mechanics of handling the tokens requires writing code or shell script and debugging it before it starts to work properly. Client Registration CLI takes care of all of that. It can maintain state between invocations, it can handle tokens for you, and it's very easy to use.
You can find the tool in your KEYCLOAK/bin directory - it's called kcreg.sh (or kcreg.bat on Windows).
Here's a little tour to give you a sense of what you can do with it.
$ kcreg.sh config initial-token --server http://localhost:8080/auth --realm demo
You will be prompted for the token issued to you by realm admin. The token will be saved to default configuration file at ~/.keycloak/kcreg.config
$ kcreg.sh config credentials --server http://localhost:8080/auth --realm demo
Any operation from now on will use the set server, and realm as default values.
Alternatively you can login as user with client management rights - admin for example:
$ kcreg.sh config credentials --server http://localhost:8180/auth --realm master --user admin --password admin --secret db2cd162-aa86-4154-a16e-a393c9db4f76
By default kcreg identifies to Keycloak server as client with clientId 'admin-cli'. It's a client automatically configured for every new realm to represent client tools like kcreg. We assume here that 'admin-cli' client has Access Type set to 'Confidential', and uses 'Client Id and Secret' for authentication. That's how we got the secret - from Credentials tab of Master realm's Clients section.
$ kcreg.sh create -s clientId=app-profile-jsp -s protocol=openid-connect -s rootUrl=http://localhost:8080/app-profile-jsp
That is enough to create a new public client using a standard flow for authentication - one for static html5 applications.
To see the configuration we just created we can use:
$ kcreg.sh get app-profile-jsp
For this little tour we want to create a client for a dynamic web application hosted on a server, so we'll make the client `confidential`.
$ kcreg.sh update app-profile-jsp -s publicClient=false
Now we want to get a configuration file to put inside our packaged web application:
$ kcreg.sh get app-profile-jsp -e install > keycloak.json
We can now put keycloak.json in WEB-INF directory of our .war file.
We may not need some client configuration any more. We can easily delete it:
$ kcreg.sh delete app-profile-jsp
This was a very simple tour tailored to interactive use. Client Registration CLI also supports more complex usage.
For example, it's possible to perform one time authentication for individual command, that doesn't save any tokens into a config file:
$ kcreg.sh create --no-config -s clientId=app-profile-jsp -s protocol=openid-connect -s rootUrl=http://localhost:8080/app-profile-jsp -s publicClient=false --server http://localhost:8180/auth --realm master --user admin --password admin --secret db2cd162-aa86-4154-a16e-a393c9db4f76
All the kcreg commands accept additional options which you can learn about by using --help.
Client Registration CLI doesn't use Keycloak Admin REST, but rather a separate Client Registration REST service. It is thus limited in its scope, and tailored to the special use case of configuring new clients in a self-service manner.
Another more general Admin CLI tool is in the making that will use Keycloak Admin REST, and eventually allow all Web Admin Console operations to be performed through CLI.
Why not give Client Registration CLI a try, and let us know what you think.
The first of the CLI tools - Client Registration CLI - is now available as part of Keycloak distribution. It allows creating and updating new clients - operations you would otherwise have to do in Web Admin Console under Clients section.
Client Registration CLI can be used by application developers that integrate their applications with Keycloak server, and don't necessarily have administrative privileges on the server itself. That is possible by way of special client creation tokens called Initial Access Tokens that can be issued by realm administrator, and distributed to developers for them to self-service. In that case developer doesn't even need a user account, Initial Access Token is their means of authenticating to perform client creation operations.
The Client Registration CLI can also be used by applications and services to dynamically self-register themselves. This makes it possible to automate the creation and management of client configuration by applications and services themselves.
In theory such self-service can be performed by using generic tools like curl or wget, but in reality the mechanics of handling the tokens requires writing code or shell script and debugging it before it starts to work properly. Client Registration CLI takes care of all of that. It can maintain state between invocations, it can handle tokens for you, and it's very easy to use.
You can find the tool in your KEYCLOAK/bin directory - it's called kcreg.sh (or kcreg.bat on Windows).
Here's a little tour to give you a sense of what you can do with it.
Register an Initial Access Token received from admin
$ kcreg.sh config initial-token --server http://localhost:8080/auth --realm demo
You will be prompted for the token issued to you by realm admin. The token will be saved to default configuration file at ~/.keycloak/kcreg.config
Declare which server and realm to use by default
$ kcreg.sh config credentials --server http://localhost:8080/auth --realm demo
Any operation from now on will use the set server, and realm as default values.
Alternatively you can login as user with client management rights - admin for example:
$ kcreg.sh config credentials --server http://localhost:8180/auth --realm master --user admin --password admin --secret db2cd162-aa86-4154-a16e-a393c9db4f76
By default kcreg identifies to Keycloak server as client with clientId 'admin-cli'. It's a client automatically configured for every new realm to represent client tools like kcreg. We assume here that 'admin-cli' client has Access Type set to 'Confidential', and uses 'Client Id and Secret' for authentication. That's how we got the secret - from Credentials tab of Master realm's Clients section.
Create a new client configuration
$ kcreg.sh create -s clientId=app-profile-jsp -s protocol=openid-connect -s rootUrl=http://localhost:8080/app-profile-jsp
That is enough to create a new public client using a standard flow for authentication - one for static html5 applications.
Get client configuration
To see the configuration we just created we can use:
$ kcreg.sh get app-profile-jsp
Update client configuration
For this little tour we want to create a client for a dynamic web application hosted on a server, so we'll make the client `confidential`.
$ kcreg.sh update app-profile-jsp -s publicClient=false
Get Keycloak Adapter configuration file
Now we want to get a configuration file to put inside our packaged web application:
$ kcreg.sh get app-profile-jsp -e install > keycloak.json
We can now put keycloak.json in WEB-INF directory of our .war file.
Delete client configuration
We may not need some client configuration any more. We can easily delete it:
$ kcreg.sh delete app-profile-jsp
This was a very simple tour tailored to interactive use. Client Registration CLI also supports more complex usage.
For example, it's possible to perform one time authentication for individual command, that doesn't save any tokens into a config file:
$ kcreg.sh create --no-config -s clientId=app-profile-jsp -s protocol=openid-connect -s rootUrl=http://localhost:8080/app-profile-jsp -s publicClient=false --server http://localhost:8180/auth --realm master --user admin --password admin --secret db2cd162-aa86-4154-a16e-a393c9db4f76
Client Registration CLI doesn't use Keycloak Admin REST, but rather a separate Client Registration REST service. It is thus limited in its scope, and tailored to the special use case of configuring new clients in a self-service manner.
Another more general Admin CLI tool is in the making that will use Keycloak Admin REST, and eventually allow all Web Admin Console operations to be performed through CLI.
Why not give Client Registration CLI a try, and let us know what you think.
↧
Keycloak 2.4.0.CR1 Released
We've just released Keycloak 2.4.0.CR1. This release is mainly a maintenance release and we've done a lot of minor improvements and bug fixes.
For the full list of issues resolved check out JIRA and to download the release go to the Keycloak homepage.↧
↧
Keycloak 2.4.0.Final Released
Keycloak 2.4.0.Final has just been released.
There are no changes since 2.4.0.CR1. To download the release go to the Keycloak homepage. Before you upgrade refer to the migration guide
↧
Considering removing Mongo from Keycloak
We are considering removing Mongo support from Keycloak in 3.x. The reasons behind it is that there are a fair few issues in the current implementation, especially around consistency due to lack of transaction support in Mongo and often we update multiple documents. In many cases we rely on transactions to rollback to prevent partial updates, but this obviously doesn't work in Mongo.
With the fact that Mongo is already partially broken and the constant maintenance involved we're considering removing it and rather focus purely on the relational database back-end.
Another point to make is that we are not considering supporting Mongo in the supported version of Keycloak (Red Hat Single Sign-On). So we are never able to provide the same level of care and attention to it as we can for relational databases.
If we do decide to remove it we would make sure we provide a seamless and easy option to migrate from Mongo to a relational database!
I would like to gather some feedback from the community before doing anything. So please vote on the following Doodle:
http://doodle.com/poll/nnimebpkx774ppus
Also, comments on this post is more than welcome!
I'll end with a comment - Time spent by core developer on maintaining Mongo could be better spent on awesome new features, testing and bug fixing!
↧
Keycloak 2.5.0.CR1 Released
We've released Keycloak 2.5.0.CR1 just in time for Christmas. This release mainly focuses on bug fixing and we've resolved an impressive 165 issues in this release! Due to Christmas holidays the final release won't be until early January.
Highlights of the release includes:
- User Storage SPI - We've removed the old User Federation SPI in this release. If you have custom user federation providers you will need to migrate them to the User Storage SPI.
- HMAC Key Provider - We've added a secret key provider to be able to do HMAC signatures. These are faster than RSA signatures and are used for signing cookies.
- Ability to disable Impersonation - If you don't want to allow admins to be able to impersonate users you can now fully disable this feature.
This is the second to last release in the Keycloak 2 series. Expect one more round of bug fixing and a 2.5.1.Final release towards the end of January. After that we'll get started on Keycloak 3!
Plans for Keycloak 3 are not finalized, but some things we're hoping to do next year include:
- Multi data center support - It's kinda possible at the moment, but we are planning to do a lot of improvements in this area
- Authentication SPI - We're aiming to cleanup the authentication SPI and may also be adding more built-in authentication capabilities
- Validation on Admin Endpoints and Console - There's currently a lack of validation on the admin endpoints which could result in bad configuration
- Profile SPI - Single configurable and extensible place to define validation for user validation for self-registration, account management and the admin console
- New Account Management - New modern and easier to use account management console
- Testing and CI - More automated testing, better test coverage and more Jenkins!
I'd like to wish everyone a merry christmas and a happy new year on behalf of the Keycloak team. We're looking forward to a adding loads more features and improvements to Keycloak in 2017!
For the full list of issues resolved check out JIRA and to download the release go to the Keycloak homepage.↧
Keycloak 2.5.0.Final Released
Keycloak 2.5.0.Final has just been released.
There are no changes since 2.5.0.CR1. To download the release go to the Keycloak homepage. Before you upgrade refer to the migration guide
↧
↧
Keycloak 2.5.1.Final Released
We've just released Keycloak 2.5.1.Final! There are no new features to brag about this time, but we did fix a good amount of issues so I recommend everyone to upgrade. This release will also be the basis for the next Red Hat Single-Sign On release.
To download the release go to the Keycloak homepage. Before you upgrade refer to the migration guide.
↧
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.
$ kcadm.sh create roles -r demo -s name=user
$ kcadm.sh create clients -r demo -s clientId=myapp -s publicClient=true -s 'redirectUris["http://localhost:8980/myapp/*"]' -o
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
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.
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=trueCreate 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/*"]' -oCreate 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-adminAdd realm roles to a user
$ kcadm.sh add-roles -r demo --uusername super --rolename admin --rolename userUpdate a user
$ kcadm.sh update users/$SUPER_ID -r demo -s enabled=trueChange user's password
$ kcadm.sh set-password -r demo --username super --password passwordWe 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 20Get existing clients
$ kcadm.sh get clients --fields id,clientId,publicClient,redirectUrisSetup login events logging
$ kcadm.sh update events/config -s eventsEnabled=trueGet last twenty login events
$ kcadm.sh get events --offset 0 --limit 100As 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.
↧
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.
↧
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.
↧
↧
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.
↧
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.
↧
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.
↧
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:
- 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 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!
↧
↧
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.
↧
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.
↧
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.
↧