Freja eID Authenticator Plugin

This project provides an opens source Freja eID Authenticator plug-in for the Curity Identity Server. This allows an administrator to add functionality to Curity which will then enable end users to login using their Freja eID credentials.

Building the Plugin

You can build the plugin by issue the command mvn package. This will produce a JAR file in the target directory, which can be installed.

Installing the Plugin

To install the plugin, copy the compiled JAR (and all of its dependencies) into the ${IDSVR_HOME}/usr/share/plugins/${pluginGroup} on each node, including the admin node. For more information about installing plugins, refer to the curity.io/plugins.

Creating a Freja eID Authenticator in Curity

Configuration using the Admin GUI

To configure a new Freja eID authenticator using the Curity admin UI, do the following after logging in:

1. Go to the Authenticators page of the authentication profile wherein the authenticator instance should be created.

2. Click the New Authenticator button.

3. Enter a name (e.g., freja-eid1).

4. For the type, pick the Freja eID option.

5. On the next page, you can define all of the standard authenticator configuration options like any previous authenticator that should run, the resulting ACR, transformers that should be executed, etc. At the bottom of the configuration page, the Freja eID-specific options can be found.

   

6. Certain required configuration settings should be provided. One of these required settings is the HTTP Client setting. This is the HTTP client that will be used to communicate with the Freja eID OAuth server. You need to configure a Client SSL Keystore and a Server Trust Store before you create a Http Client.

Create Client SSL Keystore

1. Click the Facilities button at the top-right of the screen.
2. Next to Client SSL Keys under Crypto, click New.
3. Enter some name (e.g., freja-eid-clientSSLKeystore).
4. Select Upload Existing and click Next.
5. Upload the Keystore and enter its password with an optional alias.
6. Click Add & Commit.

Create Server Trust Store

1. Click the Facilities button at the top-right of the screen.
2. Next to Server Trust Stores under Crypto, click New.
3. Enter some name (e.g., frejaEidTrustStore).
4. Upload Public key file.
5. Click Add.

Create Http Client

1. Click the Facilities button at the top-right of the screen.
2. Next to HTTP, click New.
3. Enter some name (e.g., freja-eidClient).
4. Enable Use Truststore toggle button.
5. Select the keystore that you just created in the steps above from the Client Keystore dropdown.
6. Click Apply.

7. Back in the Freja eID authenticator instance that you started to define, select the new HTTP client from the dropdown.

   

8. Select the Environment to use, either Production or Pre Production.

9. Select the User Info Type from dropdown. It has Email or SSN as the allowed options. SSN corresponds to Username.

10. If applicable, you may also need to configure the Relying Party ID.

Once all of these changes are made, they will be staged, but not committed (i.e., not running). To make them active, click the Commit menu option in the Changes menu. Optionally enter a comment in the Deploy Changes dialogue and click OK.

Once the configuration is committed and running, the authenticator can be used like any other.

Enabling QR Code Authentication

When QR Code Authentication is enabled, the authenticator will not present the user with a field to enter their identifier (email/ssn/phone). Instead, a QR code will be displayed that the user must scan in order to perform authentication. The Freja API returns N/A as the userInfo in this case, so the subject of the authentication must be taken from the attributesToReturn. The authenticator will select the subject based on which attributes where present in the response in the following order:

1. Custom Identifier
2. Integrator Specific User ID
3. Relying Party User ID
4. Social Security Number
5. Email

If none of these attributes above are returned, the authentication will fail and the user will be redirected to the authentication endpoint so they may try a different authenticator (if configured) or try to login again.

Note: When QR Code is enabled, the authenticator will try to autostart the Freja e-id mobile app. This can be disabled by overriding the template freja-eid/authenticate/wait.vm and removing the parsing of authentication-app-launcher fragment. In case the authenticator is to be used by a specific mobile app, it is possible to override freja-eid/handle-auto-start-uri.vm to pass an extra parameter to the url so the Freja e-id application can go back to the original application.

Testing Instructions

To test the plugin in Pre Production environment, follow the below instructions.

1. Download app from AppStore or PlayStore.
2. Start the app in Test Mode by following instructions from Verisec.
3. Activate your ID by entering your email and confirming it.
4. Now you can use this email for testing.
5. In order to use SSN for testing, you need to vet your ID first
6. Upgrade your account from mobile app
7. Vet your ID by following the instructions from Verisec.
8. After that you can use your SSN for testing.

Note :: You can find detailed instructions from documentation provided by Verisec.

Run Mock Node Server

You can also use mock node server for testing which will act as Freja e-id server.

Follow the instructions below to run and use mock node server.

1. Start the node server using docker compose. Docker and Docker compose should be installed on your machine.

   docker-compose up

2. Change the host value to localhost in FrejaEidAuthenticatorPluginConfig.kt like below.

3. Rebuild the plugin and test the authentication flow using test mock server.

More Information

Please visit curity.io for more information about the Curity Identity Server.