Keycloak: Custom Authentication Flows

hello everybody hola todos chez chefsky in this video i'm going to show you how you can extend key cloak using its rich authenticator spi the example i'm going to show you is simple but together with the source code it's a great starting point to build more complex setup and if you want to do super complex stuff super complex custom authentication logic you can do it all in key cloak spis for java and javascript are very well covered in the documentation it is also a pretty big topic which i won't be able to cover in a single video and i really recommend you check out the documentation okay so what i'm going to show you is ip based authenticator i'm going to walk you through it and will show you how to use it to add a custom java authenticator and use provided out of the box conditional otp form component to build a new custom authentication flow and my idea is simple i want to force mfa otp check if the user is trying to sign in from a non-trusted network if the user uses corporate network corporate vpn then it is a trusted network and i will skip otp step so let's do this i will use a simple project which i wrote and i made available on github you can find a link to this project in the description of this video you can clone it to your machine it's a java maven project and you can import it into your favorite ide okay so we need a java project with two components factory authenticator factory and authenticator the factory will create authenticator instances it looks like this it has to implement the authenticator factory uh it has its own id which is identified inside the key cloak it has get display type which is a more user-friendly name which we will see in the ui the most important method is of course the create method which creates a new authenticator instance in our case it is ip authenticator which i will show you in a second and actually this interface defines an other method that we will need which is get config properties we want to define a load ip address for our authenticator so you can define it in config properties so i defined such a config property of type string it has its name which i have in this static variable and i set a label and help text which are actually shown in the ui so i will be able to configure my ip authenticator and i will be able to set a load ip address for every instance of the ip authenticator that i will be using so let's take a look at how the ip authenticator implementation looks like okay it has to implement the authenticator interface and the most important method in this interface is the authenticate it takes one object as an argument authentication flow context from the context i can get some interesting objects that i can use to implement my custom authentication logic in here i'm using the key clock session rail model and user model okay so the logic looks like this from the connection i get the remote ip address i also get the allot ip address from from where from the config from the authenticator config which i defined at the ip authenticator factory level and here is where i get the value which i will set in the ui so now that i have these two values i compare them if they differ i print any information in the log and i also set a user attribute of this value ip underscore paste the underscore otp underscore conditional to either force or skip i will set it to force if the ip addresses will differ i will set it to skip if the addresses match and in this case i assume that the user is coming from a trusted network and i don't have to do um additional mfa otp verification in this method i'm always calling context success if i would like to be more rigorous and for example always fail the authentication when the ip addresses differ i could remove just this body in here and write context dot failure provide a error code in this method and then return it this way key cloak would always stop here and will present an error to the end user but for me for this example i will only force mfa or skip it that is why i always call context.success okay last final note i have to provide the authenticator factory implementation name inside this file that's the name of the interface and in here i provide the implementation of this interface uh when we will build the jar file and deploy it to key cloak key cloak will read this file will read the name of the authenticator factory and we'll use this factory to create instances of our ip authenticator okay so let's build it now maven package and then i will copy the jar file to key cloak home slash standalone slash deployments okay and i see that yeah uh there was a redeployment because i actually already deployed this uh authenticator to my key cloak but yeah we can see that keyclaw detected it and redeployed it okay so let's see how we can configure a new authentication flow okay so this is the default browser authentication flow as you can see i cannot really change it so i have to make a copy of it i will call it mfa skip for trusted networks and you can see that i can now actually change the order and i have some additional uh actions that i can perform on these uh items so uh cabarrus is disabled so i'm going to actually uh delete it and yeah we can actually see that at the top level there are three alternative um out steps the first one is cookie it means that if i utter the authenticated in key cloak and i will be redirected to key cloak key cloak will actually check the cookie and if the cookie is still valid it will not ask you for your username and password or mfa it will simply redirect you back to the application with an information that you are successfully authenticated already the second option identity provider redirector if we set up this step it will redirect you to the identity provider website the identity provider will actually similar to keto cookie will detect its own cookie will verify if you are under the sign in into identity provider and if so it will return to key clock and the key cloak in turn will return to to you or to the end user and the third alternative step is the forms step so if this will fail forms step will kick in and the form steps contains the username password form and and conditional mfa step if you actually at the realm level require mfa setup then it will actually be required for all the users all the users will have to as a part of their sign in journey will have to provide the mfa otp token so um i'm going to actually remove this part and replace it with our own authentication flow so i'm actually going to delete this part okay so i will add the first component and i will and it will be our ip authenticator right that's the display name which we saw earlier in the java code and hit save i showed you in the code that there's a config available for this authenticator and if you click actions you can actually see it okay so uh that's the label which we configured in the java code and if we hover over the question mark there is the help text that we also saw in the java code so as you can see from this help text and also by looking at the source code you know that i'm doing a simple java string equals method so i only accept ip addresses i don't support masks or ranges or anything complex just ip addresses and they have to equal i have to provide an alias so i will call it ip authenticator and for the purpose of the demo let's assume that my trusted network is 1001 okay and now let's add another execution and this time i will add conditional otp form this conditional otp form on market as required differs from the standard otp form in in a way that you can configure it and if you click actions you can see that yes there's config in here you can see that you can actually either skip or force otp based on roles or headers and in my example i actually used otp control using the user attribute and if you hover over the question marks it will actually tell you that if you want to force the otp it has to have a value of force and if you want to skip it it has to be have a value of skip so the user attribute i will copy it from our source code that's this attribute that we will be setting to either force or skip and then in the key cloak conditional otp form we will check uh this attribute um fully automatically so it will be ip authenticator okay and important thing to remember set the fallback otp handling uh play it safe and say set it to force um whenever there is an error or a problem with any of these uh it's actually the best um the best way to actually force otp just in case okay and the authentication flow looks like this uh okay if you want to use it we have to change the bindings the default browser flow is still browser so we are going to change it to mfa skip for trusted networks and i'm going to click save okay i'm in a customer tool so i will change and log in with my test user okay so it expired so one more attempt okay and i presented with one time code so that's actually the conditional otp form that we see in here and let's quickly take a look at the key cloak console and you can actually see that we see the message that we we generate when ip do not match and you can see that the realm customer 99 expected 1001 ip address but user l2 logged from the localhost and yes i'm actually using localhost for the purpose of this demo and yes we can see that i was forced to a conditional otp form step so to make ip address match i'm actually going to change the allot ip address i'm going to config and i will change it to loopback okay and i'm going to save it i'm going to restart login and this time i'm logged in into key cloak and i go straight to my account page so uh the otp step didn't show up because i came from a trusted network so guys with the key cloaks spi you can build any complex authentication flows that you want for example if you have a separate key clock client that you use to for example authenticate users to your critical production system you can check you can make a call to jira if you have some sort of ticketing system that for example uh contain approvals for the users you can check if the user that is signing in has a ticket created in this system and the ticket was approved by um by manager or by another peer and only then for example allow the the user to sign in into your application so basically sky is the limit uh you can do really complex things with the authenticator spi in key club so guys that's all for this video if you liked the video hit the like button and subscribe to my channel thanks

Channel: Łukasz Budnik

Views: 2,261

Rating: 4.891892 out of 5

Keywords: keycloak, mfa, authentication, identity management, access management, java

Id: u36QK9oyrtM

Length: 20min 13sec (1213 seconds)

Published: Tue Jun 22 2021