This page:

Services:

• Authentication Services
• Signature Services
• Identity Assertion Service

Management:

• Integrator Relying Party Management
• Custom Identifier Management

Thank you for subscribing to Freja eID services.

Freja eID is an electronic identification (eID) solution for citizens and organisations which can be used for identity assertion, authentication and signing. The essential part of Freja eID service is a smartphone application used for login and signing to all the services that are connected to the user´s eID. The second part is a web portal – My Pages – where the user can control how their eID is to be used and has a full record of user history.

In terms of relying parties, Freja eID offers great flexibility in terms of addressing end users. For example, the identity assurance level of end users registered with Freja eID can vary. If the user has followed an entry-level registration flow, their identity will be assured to level 2 within the scheme, also known as Freja eID Basic. At this level a user will have confirmed an email address and/or a mobile phone number, perfectly enough to allow, for example, login authentication in situations where an absolute identity is not of significance for the relying party - knowing that the end user accessing a relying party's service is the same one that accessed the service a week ago without the hassle of teaching the end user an additional password is perfectly enough for many web-based services.

However, if the end user opted for an extended registration process, their identity will be assured to level 3 within the scheme, also known as Freja eID+. The extended registration process involves, amongst other controls, vetting physical ID documents of the end user and face enrolment with Freja eID. Freja eID+ users can be referred to through their social security number (SSN). In Sweden, this would equate to having established a "personnummer" for the end user. Also, Freja eID+ users can be involved in interactions with web parties that involve login, but also legally binding signatures and identity assertion. If you want to find out more about identity assertion levels, please have a look at the Tillitsnivåer för elektronisk legitimation published by the Swedish e-Identification board.

This document contains instructions for enabling Relying Party (RP) applications to use services offered by Freja eID. It is of a technical nature - if you are not a software architect or developer, it is probably the wrong document to read.

Freja eID offers three services to RPs: Identity Assertion Service, Authentication service and Signing service. Our recommendation is to read the sections of interest to you in their entirety at least once. On later occasions, use the links to quickly navigate to the section of interest. 

Document Versions

Abbreviations

Getting started IN PROGRESS

About Freja eID environments

Freja eID system offers two environments:

• Test or Demo Environment, which is designed for testing purposes, it is intended to be used by Relying Parties during the process of integration with Freja eiD to test the integrated services.
• Production Environment, which is where the Freja eID services are actually available for business use and where the real-time staging of integrated services is executed.

Note that the Test Environment tries to resemble the Production Environment in all segments.

Before you begin

Test environment checklist

There are several technical requirements that must be in place before the integration with Freja eID can start. Before proceeding, you need to:

• Obtain an SSL/TLS client certificate providing you access to the Freja eID Test Environment. For more information, refer to the Certificates section.
• Import Freja eID Test root certificate as trusted into the trust store of your application.
• Using Freja eID mobile application, register one or more users with the Freja eID Test infrastructure.

Production environment checklist

In order to use Freja eID in a production environment, you must fulfil the following:

• Sign a contract allowing your organisation to access the production Freja eID Authentication service.
• Provide Freja eID with a logo suitable to represent your organisation in the mobile application, as well as a display name, a URL and a short description. Please note that:
  
  • The logo must be delivered in one of the vector file formats: AI (Adobe Illustrator Artwork), EPS (Encapsulated PostScript) or editable PDF (Portable Document Format). The preferable format is AI (filename extension is .ai).  
  • The display name is restricted to the maximum length of 20 characters and the description should not exceed 75 characters. The URL can be up to 100 characters long.
    
• Obtain an SSL/TLS client certificate providing you access to the Freja eID Production Environment. For more information, refer to the Certificates section.
• Import Freja eID Production root certificate as trusted into the trust store of your application.

Certificates in Freja eID

Freja eID system requires usage of SSL/TLS certificates for communication with Relying Party applications. The following certificates are used:

• Freja eID's server certificate:
  • Freja eID Test root certificate
  • Freja eID Production root certificate
• Relying Party's client certificate:
  • Test client certificate
  • Production client certificate
    

Additionaly, JWS certificates are used to digitally sign the results of authentication and signature requests.

Server certificate

Freja eID server certificate is used so that RPs can autheticate Freja eID as trusted in their environment. Freja eID's server certificate should be imported in the trust store of the RP's application. There are two server certificates which you need to use:

• Freja eID Test root certificate, when you want to start the integration in the Test Environment
• Freja eID Production root certificate, when you want to execute your integration in the Production Environment

Below are Freja eID's Test and Production root certificates, PEM encoded:

Client certificate

As mentioned before, to access and use Freja eID services, you need to obtain a client SSL/TLS certificate. Two client certificates are needed, one for access to the Testing Environment and one for access to the Production Environment. Client certificate autheticates your application when it tries to communicate with Freja eID services. Additionally, Freja eID uses your Client certificate to identify you in its system when you try to send an authentication or sigining request.

The following section provides you with instructions on how to generate an SSL/TLS key and a certificate signing request (CSR), which you can then send to Freja eID partner support to provide you with the ready-made client certificate. It also documents how to create a PKCS#12 file.

What is an SSL/TLS key and what is it used for?

The SSL/TLS key is a part of the Public Key Infrastructure (PKI) that is generally used in case of SSL/TLS certificates. A Public Key Infrastructure assumes asymmetric encryption, where two types of keys are used: a Private Key and a Public Key (included in an SSL/TLS certificate). The private key is based on the RSA algorithm and is used for authentication and the establishment of an SSL/TLS session. Since encrypted data transmission takes too much time in case of asymmetric encryption, this kind of encryption is only used for a secure exchange of the symmetric key, which is used for actual transmitted data encryption and decryption. 

What is a certificate signing request (CSR)?

A certificate signing request (also CSR or certification request) is a block of encoded text that is given to a certificate authority (CA) when applying for an SSL/TLS certificate. It is usually generated on the server where the certificate will be installed on and contains information that will be included in the certificate, such as the organisation name, common name (domain name), locality and country. It also contains the public key that will be included in the certificate. The private key is usually created at the same time as the CSR, thus making a key pair. A CSR is generally encoded using ASN.1, according to the PKCS #10 specification.

Distinguished name

SSL/TLS certificates contain identifying information, such as the qualified domain name used for DNS lookups of your server (also called Common Name), your organisation or company name and location information. This information is called the certificate's Distinguished Name. When generating a CSR on your server, you are asked to enter the Distinuguished Name, which uniquely identifies your server.

This is an example list of required fields for the Distinguished Name (i.e. Subject) used when generating a CSR request for a Freja eID Relying Party named "ACME AB":

Client certificate generation - Step-by-step guide

1. Launch Open SSL (preferably on the production server) and generate your private key with the genrsa command (see below). Command arguments are the location and file name where you wish to store your key and the key strength (with minimum value of 2048 bits). You will also be prompted to choose a secure passphrase for the key.

   openssl genrsa -F4 -aes256 -out <PATH_TO_YOUR_PRIVATE_KEY>.key 2048

   Security recommendations

   As the security relies on the integrity and security of this private key, it is the best practice to generate the key on the production system itself and also to make sure that this key is protected duly against unauthorised attacks by limiting access to thekeyfileitself. Once the PKCS#12 file has been generated, the key file can be removed or stored securely offline for backup purposes.

2. Next, generate the CSR using the key generated in the step 1 with the following command and put it in a file.

   openssl req -new -subj "/C=SE,2.5.4.97=556677-8888,OU=Production,O=ACME AB,CN=Document signing service" -key <PATH_TO_YOUR_PRIVATE_KEY>.key -out <PATH_TO_YOUR_CSR>.csr

3. Compress the file with ZIP/gZIP and email it to partnersupport@frejaeid.com. After the certificate is issued by the Freja eID Support, you will receive a ZIP file with your new certificate, along with required Freja eID CA certificates.

   Filename	Description	Distinguished Name	Issuer
   Freja eID Production Root.cer	Freja eID's offline root certificate	CN = Freja eID Root CA v1 OU = Production O = Verisec Freja eID AB 2.5.4.97 = 559110-4806 C = SE	CN = Freja eID Root CA v1 OU = Production O = Verisec Freja eID AB 2.5.4.97 = 559110-4806 C = SE
   Freja eID Production Issuing CA.cer	Freja eID's Issuing Certificate Authority	CN = Freja eID Issuing CA v1 OU = Production O = Verisec Freja eID AB 2.5.4.97 = 559110-4806 C = SE	CN = Freja eID Root CA v1 OU = Production O = Verisec Freja eID AB 2.5.4.97 = 559110-4806 C = SE
   Freja eID Production Certificates.pem	Freja eID certificate chain. Contains booth root and CA certificates
   <YOUR CERTIFICATE>.cer	Your relying party issued certificate	CN = Document signing service OU = Production O = ACME AB 2.5.4.97 = 556677-8888 C = SE	CN = Freja eID Issuing CA v1 OU = Production O = Verisec Freja eID AB 2.5.4.97 = 559110-4806 C = SE

4. Generate the PKCS#12 keystore file with the following command and choose a secure passphrase:

   openssl pkcs12 -aes256 -CAfile "Freja eID Production Certificates.pem" -export -in <YOUR CERTIFICATE>.cer -inkey <YOUR_PRIVATE_KEY>.key -out <YOUR_KEYSTORE>.pfx

   Security recommendations

   As the security relies on the integrity and security of this keystore, create it on the production system and protect it the production system itself and also make sure that this key is protected duly against unauthorised attacks by limiting access to the keystore file itself.

5. Verify connectivity against production with the following command:

   openssl s_client -verify_return_error -CAfile "Freja eID Production Certificates.pem" -export -in <YOUR CERTIFICATE>.cer -inkey <YOUR_PRIVATE_KEY>.key -connect services.prod.frejaeid.com 

   Reminder

   Once connectivity has been verified, files from the ZIP file should be deleted to avoid misunderstandings.

    

   
   

MIIEDTCCAvWgAwIBAgIUaKpKqy2TcGQeNQfUIZZD9jEzk5MwDQYJKoZIhvcNAQELBQAwgYMxCzA
JBgNVBAYTAlNFMRIwEAYDVQQHEwlTdG9ja2hvbG0xFDASBgNVBGETCzU1OTExMC00ODA2MR0wGw
YDVQQKExRWZXJpc2VjIEZyZWphIGVJRCBBQjENMAsGA1UECxMEVGVzdDEcMBoGA1UEAxMTUlNBI
FRFU1QgSXNzdWluZyBDQTAeFw0xNzA1MTcyMTE5MjNaFw0yMDA1MTcyMTE5MjNaMIGGMQswCQYD
VQQGEwJTRTESMBAGA1UEBxMJU3RvY2tob2xtMRQwEgYDVQRhEws1NTkxMTAtNDgwNjEdMBsGA1U
EChMUVmVyaXNlYyBGcmVqYSBlSUQgQUIxDTALBgNVBAsTBFRlc3QxHzAdBgNVBAMTFkRvY3VtZW
50YXRpb24gYW5kIERlbW8wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDBwTeuSLvrd
Ot8PJ3dfnlDS+tyTV5P35sm/UusrasPya0XUV3ctj8RxD2skLHYMZ10X87EvXBUw4FEKJ9YlwTO
A3UjZ3jXYX9TZlU/r0kZsvf4RBZO8MOje00oRRdx0go4L6SsTcoBQhgimkxBMcCY1aHqGDWMH61
DWxbepa/4Df6xuFegnMQp421mR2FFvRUi74HBCn35oVHZhYviWo7aTyPVFWd2wLN8GiV+jwunHU
Tdq61+f9pqhPJ0CM6VL9oAIl0D0LbDHbMUd4XuV1hB9wM5jKZaGQ3388rWs+9a83/BJjb1Wa5qD
9tICuIl8y/asOcQEuvX7fT7xyPwduvLAgMBAAGjdDByMA4GA1UdDwEB/wQEAwIGwDAMBgNVHRMB
Af8EAjAAMB8GA1UdIwQYMBaAFGp8ig+dcA4c2l8toDwmX4joFb+cMBIGA1UdIAQLMAkwBwYFKgM
EBQowHQYDVR0OBBYEFHgMFxByq68FGuntjoOa+TTXw/7/MA0GCSqGSIb3DQEBCwUAA4IBAQCV9g
0ZuHBWOIdqiLDss/kTr0Obaeap4DEF5uuuxqo2LKn0k1qGHh66uLdxS0i1nWyLZjphPi5l8CxxM
uhw0VZ90u4cguTYsUXy/s1dp12e48m7bVOz/SnghU8ag+2pAO1esSn3LJ0nOMlKe32IMuGLUXPR
ELG151DEam/3yWKeCtEkthPisDLUKHKoc9v6EQEo+IVkGluSWPaIpvdbJpISzW3c0m9Qzu+GqWj
A1ac/BzdHql0UyTIoXB6u2VVbuIAkTLVLeFWlnL6dOD4XoChN9LStqYKn4iovO+DA+AtQt8Q+4B
/8hQnMyNby0Zyn5BJw4dqDWCju5PIFct8IvYuu

eyJhbGciOiJSUzI1NiIsIng1dCI6InNIODBvb0F1Rzg5a1MxM2xfUl9Pdk1MM1daQSJ9

General information about Freja eID RESTful APIs

Authentication and Signature services are exposed through a RESTful API. This section presents information common to both services. Firstly, the following applies to HTTP response codes.

{
   "code": "Integer with error code value",
   "message": "Error description"
}