An authenticator that uses the Signicat signing service to do authentication
Switch branches/tags
Clone or download

README.rst

Signicat Authenticator Plug-in

https://travis-ci.org/curityio/signicat-authenticator.svg?branch=master

An authenticator that uses the Signicat login and signing services to do authentication.

This project provides an open source Signicat 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 Signicat credentials -- or more exactly -- the credentials of some E-ID provider, like BankID or NemID. The app that integrates with Curity will be provided with all of the attributes released by the user at Signicat, including the user's personal number and other biographical information.

System Requirements

Curity Identity Server 2.4.0 and its system requirements

Requirements for Building from Source

The source code is written entirely in Kotlin. It can be compiled using Maven 3. For this to succeed, however, the Signicat Connector for Java needs to be installed into a Maven repository which is accessible during compilation. The POM may need to be updated depending on the Maven Coordinates (Group, Artifact, Version) used during installation. Refer to the Maven guide for information about installing third-party JARs. Once the Signicat Connector's JAR and its associated OpenSAML version are installed, the project can be compiled from a shell by issuing a command like this: mvn package.

Installation

To install this plug-in, either download a binary version available from the releases section of this project's GitHub repository or compile it from source (as described above). If you compiled the plug-in from source, the package will be placed in the target subdirectory. The resulting JAR file or the one downloaded from GitHub needs to placed in the directory ${IDSVR_HOME}/usr/share/plugins/signicat. (The name of the last directory, signicat, which is the plug-in group, is arbitrary and can be anything.) All of the dependent JAR files must be placed in this directory as well. These include:

  • signicat-client-lib-4.0.1.jar
  • signicat-opensaml-1.1-PATCH-6.jar
  • commons-codec-1.10.jar
  • xmlsec-1.5.8.jar

All of these JAR files can be obtained by downloading the Signicat Connector for Java. Apache Commons Codec and Apache Santuario can also be downloaded from Maven central or their respective project web sites.

Note

The Signicat Connector ZIP file contains other JAR files as well (e.g., SLF4J, Apache Commons Logging, etc.). These are not required by this plug-in, and should not be installed. Including SLF4J in particular will cause an error on startup. If you get such an error, ensure that only the above dependencies are copied to the plug-in group directory.

Once the plug-in and its dependencies are placed into the plug-in group directory, it will become available as soon as each node is restarted.

For a more detailed explanation of installing plug-ins, refer to the Curity developer guide.

Installing from Source

During development of the plug-in, it is very easy to copy the plug-in JAR and its dependencies with the following one-liner:

mvn install dependency:copy-dependencies \
    -DincludeScope=runtime \
    -DoutputDirectory=$IDSVR_HOME/lib/plugins/signicat && \
    cp target/identityserver.plugins.authenticators.signicat-*.jar $IDSVR_HOME/lib/plugins/signicat

Because the server must be restarted after this, it can be quite tedious and time consuming. For that reason, it is better to use Intellij's HotSwap capability to reload the classes after compilation. This will allow a developer to HotSwap changes without requiring a restart. If it fails to HotSwap some change, however, the above technique can be used.

Creating a Signicat Authenticator in Curity

The easiest way to configure a new Signicat authenticator is using the Curity admin UI. The configuration for this can be downloaded as XML or CLI commands later, so only the steps to do this in the GUI will be described.

  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., signicat1). For production, this name needs to match the URI component in the callback URL whitelisted by Signicat.

  4. For the type, pick the Signicat 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 executed, etc. At the bottom of the configuration page, the Signicat-specific options can be found.

    docs/images/signicat-authenticator-type-in-curity.png

    Using these inputs, certain required and optional configuration settings may be provided.

    Note

    The Signicat-specific configuration is generated dynamically based on the configuration model defined in the Kotlin interface.

  6. From the Country dropdown box, pick the country's kind of E-ID that should be used. For example, pick sweden to use Swedish BankID or denmark to use NemID.

  7. Enter the Service Name that you have registered with Signicat or use the default of demo for testing.

  8. From the Environment dropdown box, select either standard-environment or custom-environment. The former should be used if you are not using a custom domain (e.g., signicat.example.com). If not, then select standard-environment and pick either production or pre-production. pre-production will cause certain test certificates to be used and warnings to be logged in the server log.

  9. Optionally, enter the name of a graphics profile in the Graphics Profile text field.

  10. If signing should be used to perform authentication, toggle on the option Use Singing and enter the Secret used to identify your organization to the Signicat signing service.

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.

Note

When using the authenticator with the Curity Security Token Service (i.e., the "OAuth server"), if the client application sends the OpenID-Connect-defined ui_locales request parameter, that will be passed to Signicat as the preferred language. Also, if a request has been made by some other client (in the same browser) using the ui_locales, this preferred language will be propagated to Signicat even if the application does not explicitly provide it in the request.

License

This plugin and its associated documentation is listed under the Apache 2 license.

More Information

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

Copyright (C) 2018 Curity AB.