# Okta Integration Guide (OIDC)
This integration guide aims to explain how Signicat’s eIDs can be used in combination with Okta, from a technical perspective. Okta provides an Identity Access Management (IAM) platform that helps companies manage and secure user authentication into applications, where Signicat provides an identity hub with many eIDs, suitable for the onboarding of new users and authentication for recurring users. A full list of all available eIDs is available at the Authentication Overview.
When using both platform, synergy is achieved through the simplicity of technically linking both services. This means that Okta customers can easily add Signicat services through configurational activities, rather than spending time & effort on development capacity. This integration guide will further detail how Signicat services can be added through OpenID Connect (OIDC).
# Supported Features
Signicat supports an identity hub that is able to provide many different eIDs over a single OIDC integration, this allows for customers to easily add any eID to your own application in your Okta tenant. Currently Signicat only supports Service Provider (SP)- Initiated Authentication flows. Since many different eIDs require specific configurations, the generic eID hub allows for the usage of login hints during the authorisation flow. More information about these login hints can be found at OIDC section
The first step in the integration guide is to make sure you have both accounts setup correctly, which is a requirement before starting to configure any Application or Identity Provider.
# Okta registration
In order to add Signicat’s eIDs through Okta, you will need access to your own Okta tenant. In case you don’t have an Okta tenant yet, go to Okta.com (opens new window) and request an account. After registration Okta will provide you with an admin dashboard, which is required in Step 2.
# Signicat registration
When adding Signicat’s eIDs in the Okta dashboard, you’ll need to have OIDC client credentials (Client ID & Client Secret). Signicat has an open sandbox / demo environment that can be used without account registration. These sandbox client credentials can be found at the demo service. In case you’d like to request your own client credentials, you can sign up (opens new window).
Once you have access to the Okta admin dashboard and you have the Signicat client credentials for the OIDC connection, you’re ready to proceed with ‘Step 2 – Add Signicat OIDC Application’ and add Signicat’s eIDs to the Okta tenant.
# Configuration Steps
This section aims to provide a full overview of all the configurational activities which are required to connect Signicat eIDs as Identity Providers through your Okta tenant.
# Step 1 - Add Signicat OIDC Application
The purpose of this step is to add the Signicat OIDC application in the Okta tenant. This application will be required later in the process when adding Signicat eID’s as Identity Providers. The Signicat OIDC Application is available through the Okta Integration Network.
Add Signicat OIDC Application
Navigate to the ‘Application’ section in the Okta dashboard and click on Add Application as illustrated below.
The next step is to find the Signicat application by typing in ‘Signicat’ in the search bar. Once you have found the Signicat application, click on “Add”. In this section you’ll be asked to define a Application label to the application that will be created. You can also configure the visibility of the application at this step. Once everything is defined, click on “Done”, this will trigger the creation of the application.
Once the application is created, you’ll be navigated to the homepage of the Signicat OIDC Application where you can perform configurations. This OIDC Application will generate a Client ID and Client secret, both are visible on the ‘Sign On’ tab and will look similar as shown below. These client credentials can be used to communicate with the application and are required at a later stage.
At this section, it’s also possible to add redirect URIs that you’d like to use during your own OIDC flow. Currently the application allows for two different redirect URIs to be added, as illustrated below. Click on “Edit” at the top of the sections tab in order to add any redirect URI.
Adding these redirect URIs here means they are added to the Signicat OIDC Application in Okta, it’s also mandatory to add the exact same values for the redirect URIs to the Signicat platform. Please contact email@example.com to make sure the same redirect URIs are also added at Signicat side. Without adding the redirect URIs to both platforms, you’ll not be able to complete any end-to-end OIDC flow.
# Step 2 - Add Signicat eIDs through OIDC
Once the Signicat OIDC Application has been setup correctly, it’s possible to start adding Signicat eIDs. In order to do so, navigate to the ‘Security’ tab in the Okta dashboard and click on ‘Identity Providers’ in the submenu. At this section it’s possible to start adding individual eIDs as Identity Providers.
Click on “Add Identity Provider”, as illustrated above, to start adding a new Signicat eID. In the submenu of “Add Identity Provider”, select “Add OpenID Connect IdP”. This will open a new tab, as shown below, with information that needs to be filled in during the configuration. All values that need to be filled in, are provided by Signicat.
Below a summary and definitions of the values that need to be provided
- Name. Name of this specific connection, you’re free to decide this
- Client ID. This is the Client ID of the OIDC connection as setup by Signicat, this is provided at Step 1 of this guide
- Client Secret. This is the Client Secret of the OIDC connection as setup by Signicat, this is provided at Step 1 of this guide
- Scopes. The scopes will determine which attributes are returned as output of the OIDC flow, but are of course dependent on the chosen eID method. Different eID methods return different values. Please always take this into consideration. Okta will by default always prefill,
profile. Dependent on the desired eID, you might need to include / remove other scopes. Please contact firstname.lastname@example.org in case you have specific questions about an eID.
- Issuer. This is the Issuer value of the Signicat connection and can be derived from the well-known endpoint provided during the account setup at Step 1.
- Authorisation endpoint. This value should list the oidc/authorise URL that has been provided to you during the account setup at Step 1 and should be the URL that has to be invoked when triggering the eID on Signicat side. Please note that the
acr_valuesin this URL are different for each eID. More information about the authorisation endpoint can be found here.
- Token endpoint. This value should list the oidc/token endpoint that has been provided to you during the account setup at Step 1.
- JWKS endpoint. This value should list the oidc/jwks.json endpoint that has been provided to you during the account setup at Step 1.
- Userinfo endpoint. This value should list the oidc/userinfo endpoint that has been provided to you during the account setup at Step 1.
Once all the values are filled in, it’s time to add the Identity Provider, by clicking on “Add Identity Provider” at the bottom of the window. You can always go back into the configuration and make updates to the setup. In case you’d like to add multiple Identity Providers (meaning multiple eIDs), step 3 can be repeated for each of the applicable eIDs.
As mentioned earlier, differentiation between eIDs can be achieved by changing the
acr_values in the authorisation endpoint.
Under the “Advanced Settings” when adding the IdP, it’s possible to define specific configurations, such as JIT (Just-In-Time) provisioning of users, when the IdP is used by a user and the user is not known in Okta. To learn more about such configurations, please refer to the Okta documentation on Adding Identity Providers (opens new window)
# Step 3 - Routing Rules & Attribute Mapping
# Routing Rules
In case the Identity Provider has been setup correctly, the IdP can be linked to the Signicat OIDC Application through Routing Rules. In order to do so, navigate to the Identity Provider section under the ‘Security’ tab. This page will list all the configured eIDs as IdPs. Navigate to the ‘Routing Rules’ and select the applicable Identity Provider on the left-hand side, this will lead to a similar view as seen below.
In the screenshot below you’ll see an example of a setup that has multiple eIDs enabled on the tenant. At this section, it’s required to route the eID over the earlier created application. Therefore, click on ‘Edit’ and type in ‘Signicat’ in the search bar and select the applicable application. And add the rule. To learn more about Routing Rules, please refer to the Okta documentation about Routing Rules (opens new window)
# Attribute Mapping
Each Signicat eID will deliver a different set of identity attributes, therefore Okta needs to understand which values will be provided by each specific eID such that these values can be mapped to the Okta user profile. All of these mappings are defined in the ‘Profile Editor’
Each eID that has been added has a so-called IdP User Profile that will be mapped to an Okta user profile. This Okta user profile has a standard set of predefined attributes. This may or may not be sufficient for a specific Signicat eID, which is dependent on the provided set of attributes by that specific eID.
The standard ‘Okta user profile’ can be viewed, when navigating to the ‘Directory’ tab and selecting the ‘Profile Editor’ in the submenu, this will lead to an overview with all the defined user profiles. This also contains the standard Okta user profile that will be used to map against each specific IdP user profile. Which predefined values are part of the Okta user profile, can be viewed when opening the profile. Please have a look at the Okta user profile to understand if the default predefined profile will be sufficient to map all the attributes that will be returned by the Signicat eID.
When this is not the case, additional custom attribute fields need to be added to the Okta user profile. Please refer to the Okta documentation on custom attributes (opens new window)
Once all the attributes are added to the Okta profile, it’s time to map the Signicat eID attributes, that are returned through the previously configured Identity Provider to the Okta user profile. In order to do so, click on ‘Mapping’ of the corresponding IdP user profile in the ‘Profile Editor’. This will open a window where all the Signicat eID attributes can be mapped to the Okta user profile.
More information about this topic can be found on the Okta documentation about attribute mapping
During the mapping of the attributes it’s possible to use expressions to concatenate, manipulate or convert data types. How this works, is well described in the Okta Expression Language documentation (opens new window)
For each required eID, the steps as described above can be repeated to fill the generic Okta user profile with the attributes of the added Signicat eID. Additional information can be found on the Okta website about Profiles & Attributes (opens new window)
# Step 4 - Testing
One of the last steps in the process is to test the configured flow, this can be achieved by either adding the OIDC flow to an frontend application or directly triggering the OIDC flow from the Okta tenant. In order to directly test the OIDC flow from the Okta tenant as an HTML link, please follow the steps as described in the Okta documentation on HTML links (opens new window)
Once the Authorisation URL is composed, the flow can be triggered directly from the browser. Please follow the steps as described here (opens new window) in the Okta documentation on make sure the integration is working.
After the OIDC flow has been completed, it’s good practice to see if the user has been onboarded successfully. This can be either reviewed in the Okta dashboard under the ‘Directory’ tab in the ‘People’ submenu, by searching for the user that has been onboarded.
Additionally Okta provides good debug capabilities, to understand and review all the events that took place on the connection. This can be looked into by navigating to ‘Reports’ and accessing the ‘System Logs’, illustrated below.
# Step 5 - Go-live
After the testing has been successfully completed, you’re ready to use the flow in production. This will require you to use the Signicat Client ID & Client Secret from the production environment. Furthermore please make sure that you’re using the production endpoints as provided by Signicat in the Step 3, to make sure the production OIDC flow is triggered.
Please also take a look at the Okta pre-launch checklist (opens new window) to make sure the entire setup is ready to be launched in the production environment!
In case of technical questions on Signicat related topics, please contact email@example.com