v4.8.1

Okta Module

Disclaimer

You can't use Active directory together with Okta. You have to decide for one Module.

In contrast to the Active Directory module, where the users in charge are being synchronized to the Helmut4 system periodically with a cronjob, the Okta module is performing the steps of authentication, user creation/update and parameter assignment on the fly. So no periodic synchronization is taking place and all the steps are being performed ones the user clicks the okta login button, which appears on the login page ones the module gets activated.

Pre-requirements

First of all you have to register Helmut4 product in Okta administration section as a Web Application with the following scopes okta.users.read.self & okta.groups.read. You also need to define a callback url which looks like follows https://<helmut4Server>/login/okta/callback. You will be provided with two authentication parameters Okta Client Id and Okta Client Secret

Module activation and property description

  • okta base url: This is the base url to your okta server

  • callback url: This is the callback h4 url mentioned above (landing point after successful okta authentication)

  • Client Id and Client Secret as mentioned above

  • Group assignment: Similar to Active Directory Module you create a group assignment between Okta groups and Helmut4 groups together with other parameters, like access presets or products a user should be allowed to see. You can define as many bindings as you want, but the order is important, as all parameters of the last definition win over all the other parameters for previous groups bindings. Example: You are part of two Okta groups, okta1 and okta2, which you would like to bind to Helmut4 group1 and group2. If you define the first binding okta1 to group1 with user type USER and the second one with ADMIN the result would be a user with ADMIN privileges in both groups, as Helmut4 can only handle one user type per user entity.

Okta login user perspective

The user experience is very simple. In the login screen he just clicks on the "Login with Okta" button, that appears automatically if an admin activated the module. He will be forwarded to okta, where he provides his credentials and authenticates himself. After that he will automatically land back in Helmut4 in a loading screen (as long as CREATE_USER and CONNECTED streams are running) and after that on the first default Helmut4 page. So a user just needs to click one button and provide Okta auth (username/password/2fa) to log into Helmut4 system.

Okta login technical doc

  1. frontend

    • https://<oktaServerUrl>/oauth2/v1/authorize?client_id=<clientId>&redirect_uri=https://<Helmut4Url>/login/okta/callback&response_type=code&state=helmut_login&scope=openid%20groups%20profile%20email

    • there is no secret involved

    • after successful login we land on https://<Helmut4Url>/login/okta/callback also frontend with this url: https://<Helmut4Url>/login/okta/callback?code=<codeReturnedFromFirstRequest>&state=helmut_login

    • from there we do http request against users endpoint with the code returned

  2. backend users

    • grep all prefs (challange code auth) where now secret is included

    • do token endpoint request with the code received in callback like this: https://<oktaServerUrl>/oauth2/v1/token?client_id=<clientId>&redirect_uri=https://<Helmut4Url>/login/okta/callback&client_secret=<clientSecret>&scope=openid groups profile email&grant_type=authorization_code&code=<codeReturnedFromFirstRequest>

    • reponse body of this request:

    {
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "<some jwt token>",
"scope": "openid groups profile email",
"id_token": "<some jwt token>"
}

  3. backend users

    • request user info endpoint with the bearer token from /token request

    • https://<oktaServerUrl>/oauth2/v1/userinfo with Auth header Bearer ...

    • response is user object with group assignments:

    {
"sub": "00u1d2mm47atQd2Jz0h9",
"name": "Artur Grafov",
"locale": "FR",
"email": "helmut.external@helmut.com",
"preferred_username": "helmut.external@helmut.com",
"given_name": "Helmut",
"family_name": "Helmut.external",
"zoneinfo": "America/Los_Angeles",
"updated_at": 1683301790,
"email_verified": true,
"groups": [
    "Okta Group 1",
    "Okta Group 2"
]
}

    • users endpoint uses this info to create/update user and assign him to group(s) plus changes his properties of being an ADMIN/USER, his access presets and the products he is allowed to access