Configuring Login : OKTA

Ben Hoe

Updated 13 December 2023 22:47

Disclaimer: This guide is intended for product versions 2.9.0.0 and greater.

Background

Out of the box, the LemonEdge WebService supports JWT Bearer tokens as the means for clients to authenticate with the system.

Valid clients could be :

The LemonEdge WPF Application
The 'Universal Console'
An API user using the examples libraries or the Connector
Postman or a similar REST client.

The WebService must have configuration changes in order to extend this default behaviour to other providers. The currently supported providers are as follows:

JWT : via the WebService as the Authority
AAD : Azure Active Directory
B2C : Azure Active Directory Business to Consumer
OKTA : JWT Bearer
Windows : Negotiate

This Article is for OKTA. Please see related articles for the other providers.

Note: To login in via third-party provider, LemonEdge users must be set up with a Windows Login Domain that represents the underlying third-party username.

OKTA Configuration

Authorization Server

You must have a valid OKTA account, with admin access to configure your auth server, and create 'Applications'. Login to your OKTA dashboard, and ensure an Authorization Server exists. You will need these details to configure the WebService and the Client below.

Click the pencil to edit / view more settings.

Make a note of the Audience and Issuer. Then open the Metadata URI link in a new tab, as we will need more information from there for the client configuration.

Edit the claims as follows:

Applications

Create 2 Applications - one that represents the WebService, and one that represents the Client.

Copy the WebService 'Client ID' for use in Server Configuration.

Copy the WPF/Client 'Client ID' for use in Client Configuration.

Open the WebService Application settings by clicking the application name hyperlink. Ensure that the following scopes are granted consent:

okta.users.read | okta.sessions.read | okta.roles.read | okta.apps.read

Now open the Client / WPF Application settings.

Grant these two scopes:

okta.users.read | okta.sessions.read

Ensure that the General tab matches the following configuration:

Note: Redirect URIs must use http://localhost and have a valid port (i.e. 5000)

This should complete the setup of OKTA. Keep these pages open, so you have access to the settings for configuring the WebService and Client below.

Server Configuration

Once OKTA has been configured, open the appSettings.json for the WebService, as you will need to add a new section. Be aware that the format for these settings are different if the WebService is hosted in Azure or AWS. The Keys and values are still the same, but the format of the settings can vary.

You must add the following settings to the LemonEdge config node:

{
  "LemonEdge": {
    "ServerAuthenticationSettings": {
      "JWT": {},
      "AAD": {},
      "B2C": {},
      "OKTA": {
        "Audience": "{ Security > API > Authorization Servers > Audience }",
        "Issuer": "{ Security > API > Authorization Servers > Issuer URI }",
        "ClientId": "{ Client ID copied from the webservice application }"
      }
    }
  }
}

Run the WebService - you should see the following in the logs:

And going to this URL in the browser:

https://{your server}/Authentication/GetLoginProviders

should return:

["OKTA"] - (or more a complex object as of 3.1.2305.1204)

If this is not the case, contact development to help debug the issue.

Client Configuration

Version >= 3.1.2305.1204

As of this version, you must add the client settings to the Web Service, instead of the WPF Client.

The Web Service now sends this information to clients, so there's no need to update the client, and you have a single source of truth.

The Web Service configuration should now look like this:

{
  "LemonEdge": {
    "ServerAuthenticationSettings": {
      "EmailClaimType": "", // optional
      "JWT": {},
      "AAD": {},
      "B2C": {},
      "OKTA": {
        "Audience": "{ Security > API > Authorization Servers > Audience }",
        "Issuer": "{ Security > API > Authorization Servers > Issuer URI }",
        "ClientId": "{ Client ID copied from the webservice application }"
      }
    },
    "ClientAuthenticationSettings": {
      "OKTA": {
        "Domain": "https://{your okta subdomain}.okta.com/oauth2/default",
        "TokenUrl": "https://{your okta subdomain}.okta.com/oauth2/default/v1/token",
        "UserInfoUrl": "https://{your okta subdomain}.okta.com/oauth2/default/v1/userinfo",
        "AuthorizeUrl": "https://{your okta subdomain}.okta.com/oauth2/default/v1/authorize",
        "RedirectUrl": "https://localhost:5000",
        "ClientId": "{your client application's client id}",
        "Scopes": "openid profile email"
      }
    }
  }
}

Note: The EmailClaimType property is only available on version >= 3.2.2312.1303

Note: The EmailClaimType property is case-insensitive. If not provided, the system will look for the following case-sensitive claim types to identify the user's email address.

Version < 3.1.2305.1204

The client requires a few more settings than the server to get running.

The appSettings.json should look like this:

{
  "LemonEdge": {
    "ClientAuthenticationSettings": {
      "OKTA": {
        "Domain": "https://{your okta subdomain}.okta.com/oauth2/default",
        "TokenUrl": "https://{your okta subdomain}.okta.com/oauth2/default/v1/token",
        "UserInfoUrl": "https://{your okta subdomain}.okta.com/oauth2/default/v1/userinfo",
        "AuthorizeUrl": "https://{your okta subdomain}.okta.com/oauth2/default/v1/authorize",
        "RedirectUrl": "com.okta.{your okta subdomain}:/callback",
        "ClientId": "{your client application's client id}",
        "Scopes": "openid profile email"
      }
    }
  }
}

Remember, in OKTA > Security > API > default > Settings, there's a Metadata URI that contains all this information in JSON format.

When you run the application, and select WebService as the login profile, then Okta as the provider, you should see the OKTA login popup when you click login.

See Logging In for how to log in.

Related to: