# Migrating from Enterprise
This page applies to customers interested in migrating from Enterprise to the Signicat Digital Trust Platform (DTP). Below, you can find more context to help you understand the differences between the two platforms next to suggestions for migrating in a seamless way.
For the Signicat Digital Trust Platform (DTP), we have built a new OpenID Connect server. The new server is certified by the OpenID Connect Foundation and offers more flexibility while adhering better to standards. You can read more about this in the OIDC Server documentation.
The new server design features consistent OIDC scopes and claims, improved configuration options (on the client and per request) and self-service access to resources configuration.
Page contents
# Key differences
The platforms differ on the following features:
- Endpoints: Changes to domains and paths while keeping the same endpoints.
- Token structure: Same basic structure with differences in claims name and values.
- Scopes and claims: Changes to National ID and IdP-specific scopes and claims.
- Key rotation: Keys are rotated more often.
- Request parameters: Changes to the format and values of certain OIDC request parameters.
- Subject IDs: Access Enterprise subject IDs in DTP after migration.
- Finnish Trust Network (FTN) specifics: Different implementation of MLE.
- SSO and SLO: Default SSO for new clients and improved SLO support.
Note that the new DTP platform has changed also on general aspects like the concept of organisations and accounts, ID methods, and platform design.
Read more about high-level concepts in the General information section or find answers to common questions about OIDC in the OIDC FAQs.
Note
This page covers the changes that affect your OIDC integration(s) towards Signicat.
To find out general guidelines for setting up your integration with Signicat, visit the Initial setup instructions page.
# Endpoints
All endpoints have changed and new endpoints have been added.
You can find an overview of the endpoints in the OpenID well-known configuration endpoint.
| Old endpoint (Enterprise) | New endpoint (DTP) |
|---|---|
https://{ENV}.signicat.com/oidc/.well-known/openid-configuration | https://{YOUR_SIGNICAT_DOMAIN}/auth/open/.well-known/openid-configuration |
An example OpenID well-known configuration DTP endpoint is https://demo.app.signicat.com/auth/open/.well-known/openid-configuration (opens new window).
# Token structure
The basic structure of tokens is defined by standards, and therefore token structure has not changed. However, we added, removed and updated some claims for the access and ID tokens, as displayed in the tables below:
# Access token
| Old claim (Enterprise) | New claim (DTP) | Comment |
|---|---|---|
iss | iss | Same name, but new values. New value because domain and path structure is different in DTP. |
scp | scope | New name, but same value. |
cid | client_id | New name, but same value. |
sub | sub | Same name, but new values. Learn more in the Subject IDs section. |
snm | - | Removed field. The concept of “service” does not apply in DTP. You can deduce the account by looking at client_id and iss. |
# ID token
| Old claim (Enterprise) | New claim (DTP) | Comment |
|---|---|---|
iss | iss | Same name, but new values. New value because domain and path structure is different in DTP. |
amr | amr | Same name, but new values. DTP has more accurate use of this field, it signifies the “sub-type” type of authentication used for a given IdP. For example, 2FA, fingerprint, id-card. |
acr | idp | Same name, but new values. The usage of this field has been improved. The new claim idp_id is now used to signify which IdP the end-user used to authenticate. |
sub | sub | Same name, but new values. Learn more in the Subject IDs section. |
| - | transaction_id | New field. An internal transaction ID for DTP, useful when contacting Signicat support. |
| - | sandbox | New field. Boolean field to signify if the client belongs to a sandbox or production account. |
# Scopes and claims
Standard scopes and claims have not changed, but there are some specific changes covered below.
# Claim for National ID
It is important to note that the old scope/claim signicat.national_id has been changed to nin. We updated this to avoid issues with coding libraries and to align with industry, and Signicat, standards.
We offer support for mitigation by introducing a “Custom claim alias”. To use this:
- In the Signicat Dashboard, go to eID Hub > OIDC clients (opens new window).
- Select your OIDC client. If you haven't configured a client, see Set up an OIDC client.
- In the menu for the OIDC client, select Advanced > Custom claims, then Add custom claim.
- Enter
ninin the Claim box and entersignicat.national_idin the Alias box. - Now, select Create.
With a “Custom claim alias”, the OIDC client will always return a signicat.national_id claim whenever it returns the nin claim. Both claims will have the same exact value.
# IdP-specific scopes and claims
Scopes and claims specific to an identity provider may be different in the new platform.
Learn more about IdP-specific scopes and claims in the ID methods documentation.
# Key rotation
The signing and encryption keys that belong to the new Signicat OIDC server are rotated more frequently - on a weekly basis. We changed this to improve platform security. Learn more in our Key rotation page.
# Request parameters
We changed the format of some OIDC request parameters. The details are below:
# ACR values
The format of acr_value has changed to make the parameter more flexible, consistent and easier to use. Also, many new configuration options to control ACR values in the new platform are now available.
Important
Note that the way you use ACR values to specify IdP (ID methods) has changed.
If you use the old format, the acr_value will be ignored (as an unknown value) and the end-user will be presented with an IdP selection screen with all the IdPs available for that account.
Refer to acr_values section for more details.
# Login hint
The format for the login_hint parameter has changed. The available values may also have changed according to the IdP-specific definition. Learn more in the Login hint documentation.
# Theming (signicat_profile)
Theming has changed fundamentally in DTP. The old Enterprise URL parameter signicat_profile is now ignored. Learn more in the Theming documentation.
# Enterprise portals
The Enterprise concept of portals for authentication to customise IdP selection screens has been deprecated in DTP. You can mitigate this by specifying a list of IdPs in the ACR values or setting up an account with only certain IdPs enabled. Theming can also help to replicate some of the old functionality.
# Subject IDs
DTP introduces a new format for Subject IDs. This might affect your migration, if you are using the Enterprise Subject IDs as a primary index key or other type of unique identifier for your internal user systems. The fact that DTP has new subject IDs for the same physical persons can be a potential blocker for your migration journey.
To mitigate this, we released a feature called “Enterprise Subject Lookups” that allows you to gain access to Enterprise subject IDs from DTP after migration. Note that this is a temporary migration feature that will be deprecated once all customers have moved away from using old enterprise subject IDs and adopted the new DTP format.
If you plan to use the “Enterprise Subject Lookups” feature, we strongly recommend that you start mapping the (old) Enterprise subject IDs to the new DTP subject IDs and prefer the latter when they are available to you. Following these steps early on will save you time when the old enterprise subject IDs will get deprecated.
How to activate “Enterprise Subject Lookups”
To enable the “Enterprise Subject Lookups” feature, contact Signicat Support at support@signicat.com.
“Enterprise Subject Lookups” will be enabled only if necessary in your migration to DTP.
# Finnish Trust Network (FTN) specifics
The implementation of Message-Level Encryption (MLE) in DTP has been improved. It is now more flexible and can be managed completely with self-service. Note that there are some differences in the implementation as explained in the FTN specifics for OIDC section and in the FTN documentation.
# SSO and SLO
When you create a new OIDC client in DTP, it will have Single sign-on (SSO) by default. Learn more in the SSO documentation.
To reproduce the old Enterprise way without SSO, you can specify the URL parameter prompt=login in each authorisation request in DTP. This prompts the end-user to authenticate each time.
DTP also has better support for Single log-out (SLO). Learn more in the SLO documentation.