FrejaID

Token example

Triggered with acr_values=urn:grn:authn:se:frejaid. This example includes all claims that are generally available.

Test users

FrejaID is available to anyone, but some features are only available for Swedish citizens and for EEA citizens with a coordination number (samordningsnummer) issued by the Swedish Tax Authority. For testing, you can generate a test user with your chosen level of access (which FrejaID calls the “registration level”). To generate URLs for testing, use the Authorize URL Builder.

1. Install the Freja app

Testing uses the regular Freja app, switched to test mode. Download it from the App Store or Google Play.

2. Configure the app for testing

To activate test mode:

1. Open the Freja app.
2. Tap New User.
3. Tap Get Started.
4. Toggle General Terms & Conditions six times.
5. You should see a Welcome to Test Mode screen. Tap Start Test Mode.
6. Tap OK in the popup warning. The Freja app will close.

3. Create a Basic test user

With the app in test mode:

1. Open the Freja app.
2. Tap New User.
3. Tap Get Started.
4. Accept the General Terms & Conditions, the Privacy Policy, and the disclaimer about falsifying identities.
5. Tap Continue twice.
6. Tap Set Notifications if you want to test push notifications.
7. Tap Allow in the notification popup from your device.
8. Enter a real email address where you can receive email.
9. Tap Send to confirm your email.
10. Open your email account and click Confirm in the email from Freja - TEST MODE.
11. Back in the Freja app, choose a PIN code, enter it in both fields, and tap Confirm.
12. Your device may offer to register biometrics such as FaceID or a fingerprint for Freja. Tap Allow to use them, then tap OK.
13. Tap Later when the app asks about upgrading your account.

You now have a Basic Freja test user.

Upgrade to Freja Extended

Extended gives the test user access to more scopes.

1. Go to the Freja Test Vetting Portal.
2. Enter the email address you registered the test user with, and click Upgrade.
3. Select Sweden if you want access to test all features of Freja (and if you want to upgrade to Freja+ later), and click Next.
4. Enter a first name, last name, birth date, and gender for the test user.
5. Click Generate to get a personal identity number (social security number) for the test user.
6. Write down the generated personal identity number. The portal won’t show it again.
7. Click Upgrade.

Upgrade to Freja+

Freja+ gives the test user access to more scopes than Extended. To upgrade an Extended test user to Freja+:

1. Go to the Freja Test Vetting Portal.
2. Enter the email address you registered the test user with, and click Upgrade.

Add a phone number

Registering a phone number lets you test user binding via phone number.

1. Open the Freja app and tap Settings in the bottom right.
2. Tap My Pages, then Log In.
3. Tap Approve in the popup and confirm with your PIN or biometrics.
4. Tap the hamburger menu in the top left, then User Details.
5. Scroll down to Phone number and tap the green + next to the header.
6. Select your country code and enter a real phone number that can receive SMS.
7. Tap Add.
8. Tap Yes.
9. Tap Approve in the popup.
10. Wait for the SMS from Freja with an activation code.
11. Enter the code in Enter activation code and tap Add.
12. Close the website popup.

You can now use the phone number to bind requests to your test user.

Integrate with FrejaID

Registration levels

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.

Scopes for FrejaID

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.

Common scopes

The following scopes are available for all FrejaID users:

• email_address: the primary email address of the user
• all_email_addresses: all email addresses registered for the user
• all_phone_numbers: all phone numbers registered for the user (may be an empty list)
• registration_level: the actual registration level of the user

Scopes that require Freja Extended or Freja Plus

The following scopes are only available for FrejaID users with registration level Extended or Plus:

• basic_user_info: the first and last name of the user
• date_of_birth: the user’s date of birth
• age: the user’s age
• ssn: 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 document
• photo: a photo of the user
• document_photo: a photo of the user’s registration document

To 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.

Special scopes

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 services
• loa_level: the eIDAS Level of Assurance of the user
• custom_identifier: a custom identifier registered by your organization in FrejaID’s systems
• document_photo: a photo of the user’s registration document

Set a minimum registration level

Some scopes are only available for certain registration levels. You can select a minimum registration level with one of the following login_hints:

• Basic: minregistrationlevel:basic
• Extended: minregistrationlevel:extended
• Plus: minregistrationlevel:plus

Note that you will get an error if you select a minimum registration level that does not include the scopes you request.

Prefill user information

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:

• The email address of the user
• The phone number of the user
• The country and social security number (SSN) of the user

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.

Verify user identity with a photo

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.

Sign text and data with FrejaID

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

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

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

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.

Signature responses

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.

Features available for all signature types

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).

Phone authentication with FrejaID

FrejaID can be used for user authentication during a live call or while the user is waiting in the call queue. When doing so, you must prefill user information.

For details and integration instructions, please refer to Caller Authentication with CIBA.

Order FrejaID

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 Idura. Please contact sales to initiate the process. The whole process typically takes 7-10 business days.

Once your organization and your intended use of FrejaID has been approved we will create and install the actual certificate in your Idura tenant. You can then follow the steps in Move to production.