Skip to main content

Okta Configuration

In this page, you will find a step-by-step guide that will help you integrate LittleHorse SSO Workflow Bridge with Okta. Firstly, you’ll find the recipe to plug Okta as an Identity Provider (IdP) into SSO Workflow Bridge API, and secondly, you’ll find the steps to do the same but this time using Keycloak as Identity Broker.

Before we jump into the configuration steps, you need to understand why there are two ways of integrating LittleHorse SSO Workflow Bridge with Okta, and why one of those involves Keycloak.

Why more than one way of integrating with Okta?​

Well, to answer this question we need to understand that SSO Workflow Bridge API has some user-data-related features that cannot be implemented just by using what OIDC standard provides. Therefore, SSO Workflow Bridge API implements adapters that are in charge of making those features a reality. Currently, we have not focused on developing an adapter that works with Okta, but rather just with Keycloak (given the fact that Keycloak is open source and comes with Identity Brokering configuration built-in), hence why we can leverage Keycloak’s adapter as a tool that can help our users to connect to SSO Workflow Bridge API using Okta as an IdP that can communicate with Keycloak.

Now, these features I just mentioned before can be ignored if you are not interested in them or don’t want your IdP to communicate with Keycloak. If that is your case, then you can go straight to the Okta Direct Integration section of this page.

Okta Direct Integration​

Let’s start with the easiest of the configurations.

Okta Settings​

  1. You can create an OIDC App Integration, or you can also integrate with an already existing OIDC application in Okta.

    1. If you already have a working OIDC Application in Okta, and you want to connect to SSO Workflow Bridge API, then in your Okta’s Admin Console go to the Applications section in order to find the OIDC application whose users will make requests to SSO Workflow Bridge API.

image-20241217-210903.png

  1. Once you locate your Application, you’ll need to copy the Client ID, because it will be used as one of the configuration properties in UserTasks' API oidc-properties.yaml file.

  2. Next, you’ll need to fetch the Issuer URI, which will also be used in the oidc-properties.yaml later on. To do that, in your Okta’s Admin Console go to the Security section, and then into API. There you will find a list of Authorization Servers, choose the one that you will use to authorize UserTasks API, and copy the Issuer URI.

okta-2-20241220-171145.png

  1. Now, what you will need is a couple of custom claims in your users' access tokens. The first one to pass in is the Tenant ID already created in LittleHorse server, and this custom claim MUST be present in all of the access tokens of all users making requests to SSO Workflow Bridge API. The second custom claim will be added to the access token of only those users that you want to designate as Administrators in LittleHorse UserTasks. In order to create these custom claims you will have to do the following:

    1. Tenant ID custom claim:

      1. Click on the Authorization Sever name that you previously chose.

      2. Once you are in the Authorization Server details page, click on the Claims tab

        okta-3-20241220-213039.png

      3. Now, you should see at least the sub claim created. To create a new custom claim, click on Add Claim

        okta-4-20241220-220451.png

      4. Fill in the popup form with Name = allowed_tenant, and in the Value field put the Tenant ID that is already created in LittleHorse server (Make sure to write it between single quotes so that in complies with Okta’s Expression Language). In the end you should have something like the following image:

        okta-5-20241220-220920.png

      5. After making sure you have the right Name and Value, check that the Token Type is Access Token, the Value Type is Expression and select Any Scope in Include In field, and now you can go ahead and Click on Create.

      6. If the claim’s creation was successful, you should see the newly created claim in the list of claims as follows:

        okta-6-20241220-222340.png

    2. Admin role custom claim: This is created in a very similar way in comparison to the tenantId claim.

      1. For convenience, we can just create a Group of users in Okta with the name lh-sso-workflow-bridge-admin, and then use it to set this claim as follows:

        okta-7-20241220-224125.png

      2. For the Name you can choose what you consider makes the most sense.

      3. Make sure that your Value Type is Groups .

      4. In the Filter you MUST pass the Group’s name. IMPORTANT: Make sure the name of the group is lh-sso-workflow-bridge-admin, as it is the mandatory value required by SSO Workflow Bridge API.

      5. After making sure everything is looking as the previous image, go ahead and Click on Create.

      6. If the claim’s creation was successful, you should see the newly created claim in the list of claims as follows:

        okta-8-20241220-224950.png

    3. Verify claims: To test if the claims will be part of the newly issued access tokens, you can go to the Token Preview tab and see if the custom claims are present.

      1. In the OAuth/OIDC client field fill in and choose the application name that you are integrating with LittleHorse UserTasks

      2. For the Grant Type field, choose Authorization Code

      3. For the User field, fill in and choose the a User that you previously added to lh-sso-workflow-bridge-admin group

      4. In the Scopes field, it’s good enough if you just add openid

      5. Click on Preview Token, and now you should see in the right panel, in the token tab a decoded sample of an access token containing your previously created claims as follows:

        okta-9-20241220-231424.png

      6. If the token preview looks like the previous image, then you’re are all set with the required basic configuration in Okta.

  2. By this point, you should have handy the following data:

    1. Issuer URL

    2. Name of the custom claim that will display the lh-sso-workflow-bridge-admin role within the access token

    3. Client Id

SSO Workflow Bridge API Settings​

Make sure that you edit the oidc-properties.yml file located within ./config/ directory.

Here's what you need to modify in that file:

  • iss: Here you need to paste the issuer url that you should already have after setting up your Okta integration

  • username-claim: This field is currently not being used, but it is part of Spring’s required configuration, so you can just leave it as is with the default value as preferred_username

  • authorities: Within this property you MUST set at least 1 JSON path that indicates from where the roles are going to be found within the token's claims, and this is important to help the API differentiate between ADMIN and NON-ADMIN users. Here you want to put something like: $.{name-of-custom-claim-created-in-okta}

  • vendor: This indicates who is the vendor or identity provider in charge of the authentication of users for the previously set issuer. Here you just set: okta

  • tenant-id: This property must match your Tenant that MUST be already created within LittleHorse Server.

  • client-id-claim: This property specifies what claim should be used to fetch the corresponding client id from the access token. In Okta’s case, we identified that the claim containing our clientId is cid, so just put that as well.

  • clients: Within this property you MUST set at least one client-id. In Okta’s case, just put the same client id that you should already have after setting up your Okta integration.

After you set all the values for these properties previously mentioned, your oidc-properties.yml file should look like the following image:

image-20250106-231355.png

If you have all properties correctly set, then you are ready to use access tokens from Okta to send your requests to SSO Workflow Bridge API.

Okta + Keycloak (Identity Brokering) Integration​

In order to make use of some user-related features, we need to leverage Keycloak’s Identity Brokering feature since we do not have a way to fetch user-related data from Okta directly, but we do have a Keycloak adapter implemented in SSO Workflow Bridge API in charge of performing those fetching actions.

Okta Settings​

From Okta’s side, the previous configuration applies just as well.

Keycloak Settings​

Coming up you will find Keycloak specific settings that you ought to follow if you want to successfully configure Okta as Identity Provider in Keycloak and then connect it to SSO Workflow Bridge API.

Creating an Identity Provider in Keycloak​

  1. The very first thing you want to do is log into your Keycloak Admin panel using your admin credentials

    keycloak-1-20250107-225220.png

  2. After successfully logging in, I will assume that you have a realm already created in Keycloak, but if you don’t, please, create a realm before continuing with the next steps

  3. Now, on the left panel you need to navigate to the Identity Providers section, and from there, click on the OpenID Connect v1.0 box

    keycloak-2-20250107-234805.png

  4. You will be shown a form where you need to fill in a few fields:

    keycloak-3-20250107-235626.png

    1. Alias: This is an identifier value that Keycloak will use to reference this Identity Provider. Also, this alias will be used to build the redirect URL, and later on to customize the login experience.

    2. Display name: This is an optional field which value will be used as a label that is displayed when listing the Identity Providers registered that a user can choose to log in.

    3. Display order: This field’s value indicates what is the order in which the current Identity Provider will be displayed in the given case where you have several Identity Providers registered in Keycloak. The lowest number will be applied first. No need to put anything here if you are configuring only one Identity Provider within the current realm.

    4. Use discovery endpoint: This field will let Keycloak know whether you want to fetch the different OIDC endpoints based on the discovery endpoint that you will later on provide. As per our configuration, keep this enabled.

    5. Discovery endpoint: Endpoint that will provide metadata info that Keycloak will automatically use to populate the rest of the OIDC required endpoints and URLs. By default the following fields will be populated if the discovery endpoint was correctly set:

      1. Authorization URL

      2. Token URL

      3. Logout URL

      4. User Info URL

      5. Issuer

      6. JWKS URL

    6. Client authentication: Here you set how we want Keycloak to internally authenticate against Okta. In our case, Client secret sent as postis what we need to set, because we already have Okta’s client id and client secret.

    7. Client ID: Here you just copy and paste the client id from your Okta settings.

    8. Client Secret: Here you just copy and paste the client secret from your Okta settings.

    9. If you find any additional fields, just keep the default values that they already have.

  5. After setting proper values in the fields mentioned above, go ahead and click on Add

    keycloak-4-20250108-225306.png

  6. Once you have created your Identity Provider in Keycloak, go all the way down to the Advance Settings section and follow the next steps to set values in some of the properties:

    1. Access Token is JWT: If it is not already enabled, enable it. This will make the profile mapping work (the concept of profile mappers is going to be introduced later on in this page alongside its use within this Okta + Keycloak integration).

    2. Trust Email: Enable it if you don’t want Keycloak to care about email verification for this provider.

    3. First login flow override: By default let this property preserve the value First login flow override. This property is also related to the profile mapping process.

    4. Post login flow: Let this property preserve the value Noneas we currently do not want Keycloak to do anything after a user has successfully logged in other than grant access to the requested resource.

    5. Sync mode: This property lets Keycloak perform updates on user data depending on what value you set it to. In our case, we want to set this property to Import, because we want Keycloak to only import the user once during first login of the user with this identity provider.

  7. After setting the values of the properties mentioned above, go ahead and click Save

    keycloak-5-20250108-232515.png

  8. And that is it. You have integrated Okta as an Identity Provider in Keycloak.

Now, let’s see how you can customize Keycloak so that the end users do not notice any Keycloak UI when logging into their proprietary UI.

Removing Keycloak Log In UI​

Since we want our customers' users to have a smooth experience when they log in, we don’t want them to see Keycloak’s Log In UI. Therefore, we need to customize the log in experience from Keycloak, and in order to achieve that, we need to follow the next steps:

  1. On the left panel you need to navigate to the Authentication section, and stay in the Flows tab

    keycloak-6-20250108-234406.png

  2. Here we need to take the browser flow as template, so you just:

    1. Locate the row that contains the browser flow

    2. Go to the three dots menu on the right part of the grid and click on it

    3. Click on Duplicate

      keycloak-7-20250108-234909.png

  3. After clicking on Duplicate, you will see a popup form, and in this new form, you only need to set a nameas a required field. Choose a name you like and help you identify that that is the flow in charge of showing Okta’s Log In without going through Keycloak’s Log In UI, and click on the popup’s Duplicate button

    keycloak-8-20250108-235715.png

  4. You will now see the following view:

    keycloak-9-20250109-000413.png

  5. As you are using this as a template, we will keep the following properties as they are:

    1. Cookie: Set to Alternative

    2. Kerberos: Set to Disabled

    3. Identity Provider Redirector: Set to Required

  6. Remove everything else just by clicking the Trash can icon.

  7. Locate the Identity Provider Redirector’s gear icon and click on it.

  8. Now, you will see a popup form. Go ahead and just fill in the Alias field. The value you need to put there is the same that you used when Creating Okta as Identity Provider in Keycloak in Step 4a

  9. After you set the proper Alias, click on Save.

    keycloak-10-20250109-002546.png

  10. Now, you should replace the browser flow with the flow that you just created. To do that:

    1. Go back to the Flow tab in the Authentication section

    2. Locate your flow in the list

    3. Click on the three dots menu on the right side

    4. Click on Bind Flow

      keycloak-11-20250109-003815.png

    5. A little popup form will appear.

    6. Choose Browser flow as the Binding Type.

    7. Click on Save.

      keycloak-12-20250109-004030.png

    8. Now the former browser flow should show “Not in use” under the Used By column, and your flow should show “Browser flow” under the same column of the grid.

      keycloak-13-20250109-004438.png

Now, you should NOT see Keycloak’s UI, but rather be directly shown Okta’s UI when Logging In.

Keycloak Client for SSO Workflow Bridge API​

By this point, we should have everything configured between Okta and Keycloak. Now you need to let SSO Workflow Bridge API know about Keycloak so that the whole Identity Brokering strategy is ready, and to do that, the first thing you need is a Keycloak Client, which you can create in the following way:

  1. In Keycloak’s Admin Panel, go to the Clients section on the left panel

  2. Stay in the Clients list tab and then click on Create client

    keycloak-14-20250109-154659.png

  3. You will see an initial form. You will start in the General Settings section where you need to do the following:

    1. Client Type: Keep OpenID Connect because that is the protocol used for this specific configuration. SSO Workflow Bridge API is not compatible with SAML, which is the other option that you can choose for this property.

    2. Client ID: Here you set a unique identifier for your client.

    3. Name: Optional. If you want you can use the same value that you used as Client ID.

    4. Description: Optional. If you want you can specify what this client is going to be used for.

    5. Always display in UI: Optional. Just keep the default value.

    6. Click on Next

      keycloak-15-20250109-162749.png

  4. After clicking on Next, you will now see the Capability config section, and there you should do the following:

    1. Enable Standard Flow and Direct access grant in the Authentication Flow

    2. Keep disabled the rest of the fields

      keycloak-16-20250109-165146.png

    3. Click on Next

  5. After clicking on Next, you will now see the Login settings section, and there you should do the following:

    1. As all this fields are optional, you can choose whether you want to set values right away in each one of the available fields, or you can do it later.

    2. If you rather setting the values right away, then do the following:.

      1. Root URL: Here you can set this value using Keycloak’s variable authBaseUrl

      2. Home URL: Here you need to put the URL from which you expect users to log in

      3. Valid redirect URIs: Here you can put the URIs that you want to allow to make requests to Keycloak. Initially, you can just set a wildcard value by using *

      4. Valid post logout redirect URIs: Again, here you put the URIs that make sense for your users. If you leave it empty, the default value will be what you enter as Valid redirect URIs

      5. Web origins: Here you put the allowed CORS origins. If you want to permit all, you need to set the value to /*

    3. Go ahead and click on Save

      keycloak-17-20250109-191851.png

    4. After clicking on Save, you will have completed the creation of your Keycloak client and be redirected to the Clients details view in Settings tab. If you scroll down a little bit, you will also see additional settings related to login and logout, but for now, you can ignore those and keep the default values already set.

      keycloak-18-20250109-192305.png

  6. You are now ready to go into SSO Workflow Bridge API 's oidc-properties.ymlfile and add the respective configuration there.

SSO Workflow Bridge API Settings​

If you have already read this section, you may already be familiar with the next steps. Let’s jump right into what to put in each field:

  • iss: Here you need to put the issuer url. You need to put Keycloak’s issuer URL, not Okta’s. So, the issuer URL in Keycloak is built as follows: Keycloak’s Base URL + /realms/ + your realm’s name

    • You will end up with something like: https://www.keycloak.com/realms/my-realm

  • username-claim: This field is currently not being used, but it is part of Spring’s required configuration, so you can just leave it as is with the default value as preferred_username

  • authorities: Within this property you MUST set at least 1 JSON path that indicates from where the roles are going to be found within the token's claims, and this is important to help the API differentiate between ADMIN and NON-ADMIN users. In Keycloak you have 2 types of roles, Realm roles and Client roles, and their claims are publicly known, so you just go ahead and put the 2 known JSON paths:

    • $.realm_access.roles

    • $.resource_access.*.roles

  • vendor: This indicates who is the vendor or identity provider in charge of the authentication of users for the previously set issuer. Here you just set: keycloak

  • tenant-id: This property must match your Tenant that MUST be already created within LittleHorse Server.

  • client-id-claim: This property specifies what claim should be used to fetch the corresponding client id from the access token. In Keycloak’s case, we identified that the claim containing the clientId is azp, so just put that as well.

  • clients: Within this property you MUST set at least one client-id. Just put the same client id that you should already have after creating it in the previous section of this page.

After setting all these values mentioned above, your oidc-properties.ymlfile should look like this:

keycloak-19-20250109-194753.png

And with that, you are all set and ready to test the whole integration end-to-end.