Nexus' software components have new names:

Nexus PRIME -> Smart ID Identity Manager
Nexus Certificate Manager -> Smart ID Certificate Manager
Nexus Hybrid Access Gateway -> Smart ID Digital Access component
Nexus Personal -> Smart ID clients

Go to Nexus homepage for overviews of Nexus' solutions, customer cases, news and more.


Skip to end of metadata
Go to start of metadata

This article describes how to enable two-factor authentication to the Smart ID Identity Manager (PRIME) clients Identity Manager operator UI (PRIME Explorer) and Smart ID Self-Service

This is solved by setting up a SAML 2.0 federation in Digital Access with Identity Manager as a Service Provider and an Identity Provider, such as Smart ID Digital Access component (Hybrid Access Gateway)


Expand/Collapse All

Prerequisites

 Prerequisites

Installations

Identity Manager must be set up:

The identity provider must be set up. If Digital Access component is used, see here:


Certificates

SSL server certificates for https communication:

  • For Identity Manager, SSL server certificate in PKCS#12 format. 
    • Exampleidm.p12
  • For Digital Access as identity provider, SSL server certificate and private key as PKCS#8 PEM files. 
    • Example: Certificate: da.pemPrivate Key: da.key.pem

SAML certificates for signing and encryption:

  • For Identity Manager, SAML certificate in PKCS#12 format. 
    Example: idm.saml.p12
  • For Digital Access as identity provider, SAML certificate and private key as PKCS#8 PEM files.
    Example:Certificate: da.saml.pemPrivate Key: da.saml.key.pem 

If you need instructions to create demo certificates or extract certificates to the required formats, see Create or extract certificates for SSL and SAML.

Set up Identity Manager as service provider

 Set up authentication profile

To integrate Identity Manager with SAML SSO, the SAML authentication profile must be used.

  1. In Identity Manager Admin, go to Authentication Profiles, and add a new profile with the type SAML SSO Core Object. See Set up authentication profile in Identity Manager.
  2. Open the created authentication profile for editiing.
  3. Go to the General tab and do the following settings:
    1. Check Activate SAML Authentication.
      With this switch you decide if SAML authentication should be used or not. This switch is disabled by default.
    2. In User identification, select SAML SSO Core Object.
      1. In Identity template, select one or more core object types, for example, Employee and Contractor, on which the core object search will be performed. The first matching template will be used.
      2. In User name field, select the core object field to match the user principal, for example UPN or Email. Identity Manager will use it to search the core object in the selected identity template.
      3. In User display, enter fields in a comma separated list, for example FirstName, LastName. These fields are used to display the logged in user in Identity Manager operator UI or Smart ID Self-Service.
 Upload keystore file

The defined keystore file must contain the certificates and the private key used for signing and decryption.

A keystore is mandatory to configure. Trying to save a configuration without a keystore, triggers an error message. 

  1. Go to the SAML Configuration tab.  
  2. Under Keystore configuration, click the upload symbol, browse for the keystore file and select it. 
  3. In Password, enter the keystore password. If objects in the key store are protected with a password, then they must have the same password as the keystore. 

    When the keystore configuration has been uploaded, then Available key aliases shows a list of the aliases of all available private keys in the key store.
 Create service provider metadata files

Each SAML federation can have multiple service providers, for example Identity Manager, Smart ID Self-Service and any other application to be included in the federation. Each service provider must have a metadata file. 

For each service provider, do the following to create a metadata file: 

  1. Create a metadata file in .xml format, and give it a file name such as IdM_saml_metadata.xml.
  2. Open the file for editing. Copy and paste the example file content from below.
  3. Do the following changes:
    1. In entityID: enter a meaningful name for the service provider, for example https://<idmhost>/sp.
    2. Replace certificate data with the base64 encoded SAML certificate, for example idm.saml.pem.
    3. In Location: enter the location, for example http://<idmhost>/prime_explorer/saml/SSO/alias/explorer.  
Example: Service Provider metadata file
<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor entityID="sp.example" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
    <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" AuthnRequestsSigned="true" WantAssertionsSigned="false">
        <md:KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>certificate data</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>
        <md:KeyDescriptor use="encryption">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>certificate data</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName</md:NameIDFormat>
        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://<idmhost>/prime_explorer/saml/SSO/alias/explorer" index="0"/>
    </md:SPSSODescriptor>
</md:EntityDescriptor>


This table describes some elements and attributes of the Service Provider metadata xml file: 

ElementAttributeDescription

EntityDescriptor 

The common root element for definitions of IDP and SP.

entityID 

By convention, a symbolic URL can be used both for an IDP and a SP but any identifier is allowed. The number of characters is limited to 1024.

xmlns:md 

Namespace definition of SAML V2.0 metadata.

KeyDescriptor 

Provides information about the cryptographic key(s) an entity uses for signing and encryption. The contents, including the certificate, follow the XML Signature standard.


use Allowed values are "signing" and "encryption". This attribute is optional. If it is not used the assumption is that the same certificate is used for both signing and encryption.
NameIDFormat Elements indicate what SAML name identifier formats the service supports.

SPSSODescriptor:

Element for the definition of a SP.

protocolSupportEnumeration 

Support for the SAML V2.0 protocol namespace.

AuthnRequestsSigned 

Indicates if the SAML request sent by the SP must be signed. This attribute is optional. Defaults to "false" if not set.

WantAssertionsSigned 

Indicates if the Assertion elements in the SAML response must be signed. This attribute is optional. Defaults to "false" if not set.

AssertionConsumerService

The service the SP defines to process the SAML response.

Binding 

Mapping of the SAML protocol message onto a standard communication protocol. Value "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" required.

Location 

The URI under which the endpoint is reachable. Must include the path /saml/SSO/alias/<alias>.

index A unique integer of the endpoint for reference in a protocol message.
 Upload service provider metadata files to authentication profile

After the metadata files have been created they must be uploaded to the authentication profile in Identity Manager Admin. Multiple service providers can be configured, for example for the different Identity Manager applications and any other applications to be included in the federation. 

  1. Open the SAML SSO authentication profile that was created earlier.
  2. Go to the SAML Configuration tab.  
  3. Under Service Provider Configuration, do the following for each service provider:
    1. Click on the + button to add a service provider. 
    2. In Service Provider Details, define the service provider as follows: 
      1. In Configuration file, click on the upload symbol and select the metadata file. 
      2. In Alias, enter a name to define the service provider. This must match the <alias> in the Location in the metadata file. If needed, multiple aliases can be given to the same application.
        Example: explorer or self-service.  
      3. In Alias for Signing Key and Alias for Encryption Key, enter the names of the private keys for signing and encryption that must be available in Available Key Aliases

The metadata file for the SAML identity provider will be uploaded in a later step.

 Additional configurations for Smart ID Self-Service

Enable or disable SAML in Smart ID Self-Service

Smart ID Self-Service has an additional configuration directly in the program, where SAML can be set to enabled or disabled. This means that multiple Self-Service instances with the same tenant, but different authentication methods, are allowed. While both of them use the same tenant, one instance can use SAML whereas the other one doesn't.

  1. To disable SAML for a Self-Service instance, add "enabled": false to its config.json. This example shows how to enable SAML.

    Example: config.json, SAML enabled
    /prime-ussp/assets/config/config.json
     
    ...
    {
      ...
     
      "saml": {
        "enabled": true
      }
    }

Set up communication between Smart ID Self-Service and Identity Manager

To set up the communication between Smart ID Self-Service and Identity Manager:

  1. Open the file \prime_ussp\WEB-INF\classes\application.yaml.
  2. Adapt the URLs that point to Identity Manager. If you use HTTPS instead of HTTP you must ensure that the SSL server certificate of Identity Manager is trusted by the java environment that runs the Smart ID Self-Service (tomcat). 

  3. Make sure that cookie forwarding is activated, that is, that there are empty values for the property sensitiveHeaders for the SAML routes in the configuration file.

    This is the default configuration.

    Example: application.yaml
     
    ...
    zuul:
      ...
      routes:
        ...
        saml:
          path: /saml/**
          sensitiveHeaders:
          url: http://localhost:8080/idm/saml/login
 Install Identity Provider server certificate

To have a secure communication between the identity provider and Identity Manager, server certificates must be provided by each server. 

Example - Add server certificate in Digital Access component: 

  1. Log in to Digital Access Admin.
  2. Go to Manage System > Certificates.
  3. In Server Certificates, click Add Server Certificate… 
  4. Enter a Display Name and browse for the files, to define Certificate and Key:

    Example: Add server certificate

    Display Name: hag.local

    Certificate: hag.local.pem

    Key: key.pem

  5. Click Next > to finish the wizard. 

Set up identity provider, for example Digital Access component

 Import Identity Provider SAML certificate

Private keys are used to digitally sign SAML messages and encrypt their content. Both parties need their own key-pair that could be created in self-signed mode (for testing purpose) or received from a public key infrastructure (for productive systems). 

Example - Enable Digital Access to use the SAML certificate for signing:

  1. Log in to Digital Access Admin.
  2. Go to Manage System > Certificates.
  3. In Server Certificates, click Add Server Certificate… 
  4. Enter a Display Name and browse for the files, to define Certificate and Key:

    Example: Add SAML certificate

    Display Name: SAML IdP Signing

    Certificate: hag.saml.pem

    Key: hag.saml.key.pem

    The Digital Access SAML certificate must be trusted by the Java installation that runs Identity Manager to have a secure communication between them.

    To allow SSL communication between Identity Manager and Smart ID Self-Service, the SSL certificate needs to be trusted as well by the Java installation. The SSL certificate can be exported from the Java Key Store with the following command:

    Example: java keytool command
    keytool -export -keystore idm.jks -alias selfsigned -file idm.cer


  5. Click Next > to finish the wizard.
 Optional: Create DNS name for identity provider

As identity provider, you can use any SAML2 compliant system. Follow the instructions of that software in order to configure it as SAML IdP. If you use Digital Access as identity provider, follow the steps here to create a DNS name.

Example - Create a DNS name for the Digital Access access point:

  1. Log in to Digital Access Admin.
  2. Go to Manage Resource Access > Global Resource Settings.
  3. Go to the DNS Name Pool tab.
  4. Add a new DNS name for the access point. Give the DNS name, for example idp.hag.local, and select the corresponding Digital Access server certificate, for example hag.local.pem.
  5. Click Add and then Save 
 Create SAML Federation

The identity provider must be configured to define the SAML federation with the service provider, using the metadata created in Identity Manager. 

Example - Add service provider in Digital Access:

  1. Go to Manage Resource Access > SAML Federation.
  2. Click Add SAML Federation....
  3. Enter a Display Name, for example IDENTITYMANAGER.
  4. Check Acting as Identity Provider.
  5. Uncheck Import metadata automatically.
  6. Go to the Export tab.
  7. Give a unique Entity ID: for example https://hag.local/idp.
  8. Select the Signing Certificate, for example SAML IdP Signing.
  9. Go to the Role Identity Provider tab and click Add service provider...
  10. Verify that SAML 2.0 is checked.
  11. Upload SAML 2.0 metadata, click Choose file and select the file that was created before (for example prime_explorer_saml_metadata.xml). Click Next.
  12. Confirm the message about the signer certificate by clicking Yes.
  13. Click Finish Wizard.
  14. Click on the created service provider, to open it.
    The Display Name and Entity ID is now updated according to the metadata file.

    Entity ID must be unique within the federation, for example https://<idmhost>/sp

    Service Provider URL is where the IdP will redirect the user after successful authentication, so this must be an exact match with the SP domain, in this case https://<idmhost>/prime_explorer/saml/SSO 

    Example: https://<idmhost>/prime_explorer/saml/SSO  

    <idmhost> must be the same as the url that was called initially. To be sure that the SAML request and response belong together, the communication must go to the same url and protocol (http or https), and both IdP and SP must be synchronized in terms of time.

    To set up NTP in Digital Access, see Deploy Digital Access component.

     

  15. Disable Require signed authentication request 

  16. Go to the Assertion Settings tab.

  17. In Subject > Select source of subject: select E-mail. This is the unique identifier Identity Manager uses in standard cases, and will be used when Digital Access sends a SAML ticket to Identity Manager.

  18. Go to the tab Manage Access Rules.

  19. Select any suitable access rule or leave it as Any Authentication 

  20. Click Finish Wizard and then Add. 

  21. Repeat the same steps to add Smart ID Self-Service as an additional service provider.  

 Download SAML metadata

After the service provider was configured successfully in the identity provider, the SAML metadata must be downloaded and uploaded in Identity Manager.

Example - Download the metadata from Digital Access: 

  1. Go to Manage Resource Access > SAML Federation.
  2. Click on the created service provider, to open it.
  3. Go to the tab Export.
  4. Click Download metadata.
  5. Upload the metadata file to the SAML Authentication Profile in Identity Manager and select the Type as METADATA. No File Properties needs to be configured for the identity provider meta-data.

Make sure that the Identity Manager server and the Digital Access server have the same time configured.

Upload identity provider metadata to Identity Manager

 Upload identity provider metadata to SAML authentication profile in Identity Manager

After the metadata files have been created they must be uploaded to the authentication profile in Identity Manager Admin. This section describes how to upload the identity provider metadata files. 

  1. Open the SAML SSO authentication profile that was created earlier.
  2. Go to the SAML Configuration tab.  
  3. Under Identity Provider Configuration, do the following:
    1. In Configuration File, click the upload symbol to browse for and select the metadata file that has been provided from the identity provider, for example downloaded from Digital Access. 
    2. In Attribute Type, select either option for where the authentication information shall be communicated: 
      1. NameID refers to the subject of a SAML response. Use an appropriate value that matches the desired field in the CoreObject.
      2. Attribute Statement refers to attributes associated with the subject of a SAML response.
    3. If Attribute Statement was selected, then also enter one or more names in Attribute Name

Make sure that the Identity Manager server and the Identity Provider server (for example Digital Access) have the same time configured.