Certificates

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

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

1. In PRIME Designer 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. Insert excerpt
   Set up authentication profile in Identity Manager Set up authentication profile in Identity Manager nopanel true

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.

Each SAML federation can have multiple service providers, for example PRIME Explorer 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 PRIME_Explorer_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://prime.local/sp.
   2. Replace certificate data with the base64 encoded SAML certificate, for example prime.saml.pem.
   3. In Location: enter the location, for example http://localhost:8080/prime_explorer/saml/SSO/alias/explorer.  

<?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://localhost:8080/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: 

After the metadata files have been created they must be uploaded to the authentication profile in PRIME Designer Identity Manager Admin. Multiple service providers can be configured, for example for the different PRIME 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. 

PRIME Smart ID Self-Service needs the following additional configurations:

1. Make sure that SAML is enabled in the configuration file /prime-ussp/assets/config/config.json:
   

   Code Block
   language xml title Example: config.json
   /prime-ussp/assets/config/config.json ... { ... "saml": { "enabled": true } }

   
   

2. Set up the communication between PRIME Smart ID Self-Service and PRIME ExplorerIdentity Manager:
   1. Open the file \prime_ussp\WEB-INF\classes\application.yaml.

   2. Adapt the URLs pointing to PRIME Explorerthat point to Identity Manager. If you use HTTPS instead of HTTP you must ensure that the SSL server certificate of PRIME Explorer of Identity Manager is trusted by the java environment that runs the PRIME Smart ID Self-Service (tomcat). 

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

      This is the default configuration.

      Code Block
      language xml title Example: application.yaml
      application.yaml ... zuul: ... routes: ... saml: path: /saml sensitiveHeaders: url: http://localhost:8080/prime_explorer/saml/login samllogin: path: /saml/** sensitiveHeaders: url: http://localhost:8080/prime_explorer/saml/

      
      

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

Example - Add server certificate in Hybrid Digital Access Gatewaycomponent: 

1. Log in to Hybrid Digital Access Gateway administration interfaceAdmin.
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:
   

   Panel
   title Example: Add server certificate
   Display Name: hag.local Certificate: hag.local.pem Key: key.pem

   
   

5. Click Next > to finish the wizard.

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 Hybrid Digital Access Gateway to use the SAML certificate for signing:

1. Log in to Hybrid Digital Access Gateway administration interfaceAdmin.
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:

   Panel
   title Example: Add SAML certificate
   Display Name: SAML IdP Signing Certificate: hag.saml.pem Key: hag.saml.key.pem

   
   

   Note

   The Hybrid The Digital Access Gateway SAML certificate must be trusted by the Java installation that runs PRIME Identity Manager to have a secure communication between them. To allow SSL communication between PRIME Explorer and PRIME 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: Code Block title Example: java keytool command keytool -export -keystore prime.local.jks -alias selfsigned -file prime.local.cer

   
   

5. Click Next > to finish the wizard.

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 Hybrid Digital Access Gateway as identity provider, follow the steps here to create a DNS name.

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

1. Log in to Hybrid Digital Access Gateway administration interfaceAdmin.
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 Hybrid Digital Access Gateway server certificate, for example hag.local.pem.
   
5. Click Add and then Save.  

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

Example - Download the metadata from Hybrid Digital Access Gateway: 

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 PRIME Explorer Identity Manager and select the Type as METADATA. No File Properties needs to be configured for the identity provider meta-data.

After the metadata files have been created they must be uploaded to the authentication profile in PRIME DesignerIdentity 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 Hybrid Digital Access Gateway. 
   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.