Powered by its Identity & Access Management platform Carerix offers multiple ways to setup Single Sign-On. It allows customers to configure various identity providers for user authentication. This article provides a step-by-step overview of the process of configuring Okta via OpenID as an identity provider for Carerix.
Setup of an OpenID Connect Application in OKTA and an Identity Provider in Carerix
Carerix and Okta need to be configured in parallel so make sure you have administrator rights in both applications or have the people with these permission on the table before you start.
➕ 1. Add an OpenID Connect Application in Okta
To be able to add an Identity Provider in Carerix using Okta it is necessary to create an OpenID Connect Application in Okta.
⚙️ 2. Configuration of the OpenID Connect Application
To configure the Connect Application in Okta you need to provide an application name and the Login redirect URI.
Application name is the name that will be used in your Okta environment.
Redirect URI is a URL provided by Carerix which needs a bit adjustment before you can register it. The format of the redirect URI looks like this:
https://id.carerix.io/auth/realms/{CARERIX_TENANT_NAME_LOWERCASE}/broker/{ALIAS_TO_BE_USED_IN_IDP_CREATION}/endpoint
The parts between the {brackets} need to be adjusted to your system and IDP setup.
CARERIX_TENANT_NAME_LOWERCASE: this should be the first part of your Carerix application in lowercase. For example: If customer.carerix.net is your Carerix application name, than you put 'customer' in the redirect uri. Remember to always use lowercase!
IDP ALIAS: This is the alias to be used in the Carerix Identity Provider setup. We recommend to use 'okta'. However, it can have any chosen value as long as you keep it identical here and in the Carerix Identity Provider later on.
To sum it up: if your Carerix application name is customer.carerix.net and the alias you want to use is okta the redirect URI to be set in the Okta OpenID Connect Application is:
https://id.carerix.io/auth/realms/customer/broker/okta/endpoint
Now you can save and the OpenID Connect Application will be created.
🔐 3. OpenID Connect Application Client ID & Client secret
To let third party software use the OpenID Connect Application they need to indicate what Connect Application it wants to refer to and provide a client secret (aka very long and complicated password) to gain access. The Client ID & Secret are accessible in Okta in the General tab of the main screen of your Connect Application. Copy the ClientID and Client Secret to be used in the Carerix Idenity Provider setup.
📝 4. Generate the Okta OpenID metadata file
Now we have to generate the metadata file which is needed to setup the Identity Provider in Carerix. To do so one needs to call the following URL:
https://{OKTA_DOMAIN_NAME}/.well-known/openid-configuration
Replace {OKTA_DOMAIN_NAME} with your Okta application name. Now open the url you will get to see something like this:
Save this file as a .json file to your local machine and name it something like 'carerix_okta' or equivalent to your liking.
➕ 5. Add an OpenID Identity Provider in Carerix
To use your Okta OpenID Connect Application as an Identity Provider in Carerix we need to add it to the Identity Access Menu, available for administrators in the maintenance section of the left side menu.
Import - Upload here the metadate .json file as generated in step 4
Alias - Fill out the alias as you have chosen in step 2 setting up the redirect URI. It should be identical. Note: the alias cannot be altered after IDP creation as that would mean a change in the redirect URI too, which should be changed on the Okta side as well than.
Active - defines whether this Identity Provider will be available for users to login to Carerix
Display Name - defines the button label used on the login screen of Carerix for this Identity Provider. It can be changed afterwards anytime.
Automatically redirect - indicates whether visitors of customer.carerix.net are being redirected to the Azure login page immediately and automatically (YES) or not (NO). Note: be advised to leave this option off until you have tested your configuration working properly. The value for this setting can be changed any time.
Client id - use the client ID as generated in step 3 during the Okta OpenID Connect Application generation.
Client secret - use the client secret as generated in step 2 during the Okta OpenID Connect Application generation. Note: if you use copy/paste: check if you do not accidentally copy an extra space. This would mean an invalid client secret and result in a not functioning identity provider.
After filling out the (mandatory) fields click on the save button. Your Identity Provider is added to Carerix.
Now open your newly create Identity provider in Carerix. See that the redirect URI now is also visible here. Check if it is the same here as in your Okta OpenID Connect Application. If yes, you are almost ready to go.
📛 6. Adjust user names in Carerix
To be able to successfully use Okta OpenID as an identity provider in Carerix it is necessary to make sure that all usernames in Carerix are equal to the email addresses of those users registered in Okta. Currently the only scope supported for Okta OpenID is the openID profile email.
👥 7. Assign users to the OpenID Connect Application in Okta
Users that should be able to login to Carerix should be assigned to the OpenID Connect Application in Octa. To add people go to the application in Okta and open the 'Assignments' tab. Every single user should be present here to log on to Carerix.
