eIDs
Learn more about FrejaID token contents, how to create test users and how to gain access to production.
Triggered with acr_values=urn:grn:authn:se:frejaid
.
This example includes all claims that are generally available.
FrejaID is available to anyone, but some features are only available for Swedish citizens and EEA citizens with a coordination number (samordningsnummer) issued by the Swedish Tax Authority. For testing, you can easily generate a test user with your chosen level of access (which FrejaID calls the "registration level"). You can use the Authorize URL builder to generate URLs for testing.
You can use the regular Freja app for testing. Simply download the app from the App Store or Google Play.
To use the Freja app for testing, you must activate test mode. Note that the app will stay in test mode until you delete it from your device, so you should not use your normal Freja app for testing.
To activate test mode in the Freja app:
To create a Basic test user for the Freja app in test mode:
You now have a Basic Freja test user.
To upgrade your Basic test user to Freja Extended in test mode:
Your test user will now be registered as Extended, which gives you access to testing with more scopes.
To upgrade your Extended test user to Freja+ in test mode:
Your test user will now be registered as Freja+, which gives you access to testing with even more scopes.
To add a phone number to your test user (for testing user binding via phone number):
You can now use the phone number to bind requests to your test user.
FrejaID users can be registered at three different levels. The registration level of the user determines the scopes that will be available for that user.
Anyone can register for FrejaID with just their email, and will then get registration level Basic. Users from most countries can register with their ID (e.g. their passport) and a photo, and will then get registration level Extended. Users who have a Swedish identity number ("personnummer") or coordination number ("samordningsnummer") will instead get registration level Plus when they register with their ID.
You must use scopes on each authentication to select what information about the user you require.
All scopes mentioned below must be prefixed with frejaid:
.
You will always receive a sub
value uniquely identifying the user for your service, even if you request no scopes.
The following scopes are available for all FrejaID users:
email_address
: the primary email address of the userall_email_addresses
: all email addresses registered for the userall_phone_numbers
: all phone numbers registered for the user (may be an empty list)registration_level
: the actual registration level of the userThe following scopes are only available for FrejaID users with registration level Extended or Plus:
basic_user_info
: the first and last name of the userdate_of_birth
: the user's date of birthage
: the user's agessn
: the user's social security number (based on the registration document)addresses
: the addresses registered for the user (may be an empty list)document
: information from the registration document, such as the type and expiry date of the documentphoto
: a photo of the userdocument_photo
: a photo of the user's registration documentTo request these scopes, you must also set the minimum registration level to at least Extended (see below).
Note that the photo
and document_photo
scopes produce very large JWTs containing images.
These JWTs are not suitable as access tokens because they are too large for most browsers to store as cookies.
For this reason, single-sign on functionality is automatically disabled for authentications started with these scopes.
Additionally, JWTs containing photos are too large to return via an URL.
For this reason, you cannot request the photo
or document_photo
scopes in combination with a response_type
and response_mode
that would return the token in an URL.
For example, a request with response_type=id_token
and response_mode=fragment
will be rejected if it includes the photo
scope.
The following scopes are only available by special arrangement. Contact support if you would like to use them:
unique_personal_identifier
: a unique personal identifier which can be used to link FrejaID users across servicesloa_level
: the eIDAS Level of Assurance of the usercustom_identifier
: a custom identifier registered by your organization in FrejaID's systemsSome scopes are only available for certain registration levels.
You can select a minimum registration level with one of the following login_hints
:
minregistrationlevel:basic
minregistrationlevel:extended
minregistrationlevel:plus
Note that you will get an error if you select a minimum registration level that does not include the scopes you request.
In some special cases, you may already know who you expect the user to be before they authenticate. In these cases, you can restrict the authentication to the specific user by supplying one of the following pieces of information:
To supply an email address, use the login_hint
: sub:email:<email>
. Replace <email>
with the email of the user.
To supply a phone number, use the login_hint
: sub:phone:<phone number>
. Replace <phone number>
with the phone number of the user (including a +
and a country code).
Supplying a country and an identity number is only supported for citizens of Sweden, Denmark, Finland and Norway.
To supply the country of the user, use the login_hint
: sub:ssncountry:<country>
. Replace <country>
with one of SE
, DK
, NO
, or FI
.
To supply the SSN of the user, use the login_hint
: sub:ssn:<ssn>
. Replace <ssn>
with the SSN of the user.
For Swedish, Norwegian and Danish users, the SSN must be supplied without spaces or hyphens.
For Finnish users, the SSN must be supplied with a hyphen or the letter A
before the last four characters of the SSN.
For users registered with a photo (i.e. users who are on registration level Extended or Plus), FrejaID supports additional verification of the user's identity on each transaction.
Enabling photo verification will force the user to take a photo of themselves when authenticating, then compare it with the registered photo for that user.
If the photos do not match, the user will be unable to approve the transaction.
You can enable photo verification with the login_hint
: userconfirmationmethod:defaultandface
.
FrejaID supports signing text and binary data as part of a regular authentication flow. There are three types of signatures: Simple, Extended and Advanced. All of the signature types allow you to present text to the user in the Freja app.
Simple signatures can be used to sign plain text.
The Simple signature flow is activated by adding action:sign
in the login_hint
.
The text must be provided in the login_hint
using the message
hint.
The text must be base64 encoded and no longer than 4096 characters (prior to base64 encoding).
The text will be shown to the user in the Freja app while authenticating.
Try out an example Simple signature in our Authorize URL builder.
Extended signatures can be used to sign plain text and some additional binary data.
The Extended signature flow is activated by adding action:sign_extended
in the login_hint
.
The text must be provided in the login_hint
using the message
hint, while the binary data must be provided using the nonVisibleData
hint.
Both the text and the binary data must be base64 encoded.
The text must be no longer than 4096 characters and the binary data no larger than 5 MB (both prior to base64 encoding).
The text will be shown to the user in the Freja app while authenticating, but the binary data will not be shown to the user.
Try out an example Extended signature in our Authorize URL builder.
Advanced signatures can be used to sign plain text and receive a response that is compatible with the "Mina meddelanden" digital communication platform in Sweden.
The Advanced signature response is tied to the user's personal data and can be independently validated.
The Advanced signature flow is activated by adding action:sign_advanced
in the login_hint
.
The text must be provided in the login_hint
using the message
hint.
The text must be base64 encoded and no longer than 4096 characters (prior to base64 encoding).
The text will be shown to the user in the Freja app while authenticating.
Advanced signatures are only available for Swedish users. Advanced signatures require the Social Security Number and the Basic User Information (i.e. name) of the user. These scopes will automatically be added to your request if the Advanced signature flow is activated.
Try out an example Advanced signature in our Authorize URL builder.
When the user has approved a Simple or an Extended signature, the JWT will contain the claims certificateStatus
and userSignature
.
When the user has approved an Advanced signature, the JWT will contain the claims certificateStatus
, userSignature
and advancedSignature
.
The certificateStatus
claim contains the OCSP response regarding the user certificate status when the signature was validated.
The userSignature
claim contains the signature of the user.
The advancedSignature
claim contains an XML signature containing the signature method, signature value, certificate chain, signing time and text presented to the user in the Freja app.
Note that signing can produce very large JWTs which are not appropriate for use in Bearer
headers.
This means that JWTs produced from signature flows can often not be used for authentication.
You can add a title to be displayed in the Freja app over the text to sign by adding the title
hint in the login_hint
.
The text in the title
hint must be base64 encoded and no longer than 128 characters (prior to base64 encoding).
The Freja app may sometimes send a push notification to the user's device if the user information is prefilled.
The push notification will contain a default title and message, but you can customize it.
Use the pushTitle
and pushText
hints in the login_hint
to override the default push notification.
Both the push notification title and the push notification text must be base64 encoded and no longer than 256 characters each (prior to base64 encoding).
To start accepting real users with FrejaID, you must first request a certificate to identify your organization. You will have to go through a simple approval process with FrejaID. The process is managed by Criipto. Please contact sales to initiate the process.
Once your organization and your intended use of FrejaID has been approved we will create and install the actual certificate in your Criipto tenant. You will then be ready to continue the process in the getting ready for production guide.