Page tree
Skip to end of metadata
Go to start of metadata

This article describes how to get started with Nexus GO Federated Signing. To get you up and running, Nexus will configure the service for you, including the identity providers (IdP) and service providers (SP) you want to use. 

You can easily implement signing operations in your web application using the Signing service and Support service that are provided in Nexus GO Federated Signing. For more information, see here in the section Nexus GO Federated Signing

Order and get started with the service

To start using Nexus GO Federated Signing, you must order the service from Nexus, and prepare the configuration files that are required by the Signing service, which is hosted by Nexus, and the Support service, which in this example is hosted by you:

  1. Prepare the signing validation certificate and the metadata for the signing federation: 
    1. Prepare metadata for the one or multiple SAML IdPs to be used. See the following example: 

       Example: EntitiesDescriptor.xml
      Example: EntitiesDescriptor.xml
      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <md:EntitiesDescriptor xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui" xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      	<md:EntityDescriptor entityID="https://idp.local">
      		<md:Extensions>
      			<mdattr:EntityAttributes>
      				<saml:Attribute Name="urn:oasis:names:tc:SAML:attribute:assurance-certification" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      					<saml:AttributeValue xsi:type="xs:string">http://id.elegnamnden.se/loa/1.0/loa2</saml:AttributeValue>
      					<saml:AttributeValue xsi:type="xs:string">http://id.elegnamnden.se/loa/1.0/loa3</saml:AttributeValue>
      					<saml:AttributeValue xsi:type="xs:string">http://id.elegnamnden.se/loa/1.0/loa4</saml:AttributeValue>
      					<saml:AttributeValue xsi:type="xs:string">http://id.elegnamnden.se/loa/1.0/loa2-sigmessage</saml:AttributeValue>
      					<saml:AttributeValue xsi:type="xs:string">http://id.elegnamnden.se/loa/1.0/loa3-sigmessage</saml:AttributeValue>
      					<saml:AttributeValue xsi:type="xs:string">http://id.elegnamnden.se/loa/1.0/loa4-sigmessage</saml:AttributeValue>
      				</saml:Attribute>
      				<saml:Attribute Name="http://macedir.org/entity-category" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      					<saml:AttributeValue xsi:type="xs:string">http://id.elegnamnden.se/ec/1.0/loa3-pnr</saml:AttributeValue>
      				</saml:Attribute>
      			</mdattr:EntityAttributes>
      		</md:Extensions>
      		<md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
      			<md:Extensions>
      				<mdui:UIInfo>
      					<mdui:DisplayName xml:lang="en">Test Identity Provider</mdui:DisplayName>
      					<mdui:DisplayName xml:lang="sv">Test Legitimeringstjänst för test</mdui:DisplayName>
      					<mdui:Description xml:lang="en">Test Identity Provider for Example IDP test federation</mdui:Description>
      					<mdui:Description xml:lang="sv">Test Legitimeringstjänst för Example IDP test federation</mdui:Description>
      					<mdui:Logo height="60" width="168">https://idp.local/logo.svg</mdui:Logo>
      					<mdui:Logo height="60" width="60">https://idp.local/logo.svg</mdui:Logo>
      				</mdui:UIInfo>
      			</md:Extensions>
      			<md:KeyDescriptor use="signing">
      				<ds:KeyInfo>
      					<ds:X509Data>
      						<ds:X509Certificate>...</ds:X509Certificate>
      					</ds:X509Data>
      				</ds:KeyInfo>
      			</md:KeyDescriptor>
      			<md:KeyDescriptor use="encryption">
      				<ds:KeyInfo>
      					<ds:X509Data>	
      						<ds:X509Certificate>...</ds:X509Certificate>
      					</ds:X509Data>
      				</ds:KeyInfo>
      			</md:KeyDescriptor>
      			<md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
      			<md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
      			<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.local/profile/SAML2/Redirect/SSO"/>
      			<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://idp.local/profile/SAML2/POST/SSO"/>
      		</md:IDPSSODescriptor>
      		<md:Organization>
      			<md:OrganizationName xml:lang="en">Example IDP</md:OrganizationName>
      			<md:OrganizationName xml:lang="sv">Example IDP</md:OrganizationName>
      			<md:OrganizationDisplayName xml:lang="en">Example IDP</md:OrganizationDisplayName>
      			<md:OrganizationDisplayName xml:lang="sv">Example IDP</md:OrganizationDisplayName>
      			<md:OrganizationURL xml:lang="en">https://idp.local</md:OrganizationURL>
      		</md:Organization>
      		<md:ContactPerson contactType="support">
      			<md:Company>Example IDP</md:Company>
      			<md:EmailAddress>jon@doe.local</md:EmailAddress>
      		</md:ContactPerson>
      		<md:ContactPerson contactType="technical">
      			<md:Company>Example IDP</md:Company>
      			<md:EmailAddress>jon@doe.local</md:EmailAddress>
      		</md:ContactPerson>
      	</md:EntityDescriptor>
      </md:EntitiesDescriptor>

      If you do not have an identity provider, it is available to order as part of the Nexus Smart ID offering. For more information, see Identity provider or contact Nexus.

    2. Create a signing key and self-signed signing certificate. 

      Here is an example on how to create a signing key and certificate with OpenSSL: 

      Example: OpenSSL command
      openssl req -x509 -days 1095 -newkey rsa:2048 -sha256 -keyout signing-key.pem -out signing-certificate.pem -subj "/CN=sign-support TEST"
      • The private signing key will be used by the Support service to sign the requests sent to the Signing service.
      • The public signing certificate will be used by the Signing service to validate the integrity and authenticity of the signed requests sent by the Support service.
      • On Windows you may have to use the format: "//CN=sign-support TEST" in the OpenSSL command.
    3. Select an entity ID to identify your web application (the signing requester), preferably including your domain name, for example urn:sign-requester:test.example.com

  2. Contact Nexus to order the Signing service and the Support service, and provide the following information as defined in the previous step: 
    1. IdP metadata, for example EntitiesDescriptor.xml

    2. Signing certificate, for example signing-certificate.pem

      Make sure you do not include the private key file.

    3. Entity ID, for example urn:sign-requester:test.example.com
    Nexus will review and approve the information, and then create a federation for you. You will get an email with the following information: 
    • Validation certificate, used to validate the signing response
    • Signing service entity ID
    • Signing URL, see the sequence diagram here for more information 
    • Signing service SAML service provider (SP) metadata, so that you can add trust to the signing SP in your IdP 
  3. When you have received a reply from Nexus, create a configuration file called profile.json

    1. Copy the following content to a new file profile.json

       Example: profile.json
      Example: profile.json
      {
          "signRequesterEntityId": "https://sign-requester.example.com",
          "signResponseReturnUrl": "https://sp.example.com/response",
          "signServiceEntityId": "urn:dss-dev.go.nexusgroup.com:4279c695-7a8f-43a1-bb59-0889da39a9d3",
          "certificateType": "PKC",
          "signatureAlgorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
          "requestedCertAttributes": [
              {
                  "certAttributeRef": "2.5.4.5",
                  "certNameType": "rdn",
                  "required": true,
                  "friendlyName": "serialNumber",
                  "samlAttributes": [
                      {
                          "order": 0,
                          "urn": "urn:oid:1.2.752.29.4.13"
                      },
                      {
                          "order": 1,
                          "urn": "urn:oid:1.2.752.201.3.4"
                      }
                  ]
              },
              {
                  "certAttributeRef": "2.5.4.6",
                  "certNameType": "rdn",
                  "required": true,
                  "friendlyName": "country",
                  "defaultValue": "SE",
                  "samlAttributes": [
                      {
                          "urn": "urn:oid:2.5.4.6"
                      }
                  ]
              },
              {
                  "certAttributeRef": "2.5.4.42",
                  "certNameType": "rdn",
                  "required": true,
                  "friendlyName": "givenName",
                  "samlAttributes": [
                      {
                          "urn": "urn:oid:2.5.4.42"
                      }
                  ]
              },
              {
                  "certAttributeRef": "1",
                  "certNameType": "san",
                  "required": false,
                  "friendlyName": "e-mail",
                  "samlAttributes": [
                      {
                          "urn": "urn:oid:0.9.2342.19200300.100.1.3"
                      }
                  ]
              },
              {
                  "certAttributeRef": "2.5.4.3",
                  "certNameType": "rdn",
                  "required": false,
                  "friendlyName": "commonName",
                  "samlAttributes": [
                      {
                          "order": 0,
                          "urn": "urn:oid:2.16.840.1.113730.3.1.241"
                      },
                      {
                          "order": 1,
                          "urn": "urn:oid:2.5.4.3"
                      }
                  ]
              },
              {
                  "certAttributeRef": "2.5.4.4",
                  "certNameType": "rdn",
                  "required": true,
                  "friendlyName": "surname",
                  "samlAttributes": [
                      {
                          "urn": "urn:oid:2.5.4.4"
                      }
                  ]
              }
          ]
      }
      
      
    2. Edit the file profile.json as follows: 
      1. Set signRequesterEntityId to the unique entity ID of the signing requester
      2. Set signResponseReturnUrl to the endpoint in your web application (the signing requester) that should receive the signing response.
      3. Set signServiceEntityId to the unique entity ID of the Signing service, that has been provided by Nexus 
  4. Copy the following files to the folder to be mounted, for example c:/sign-support/test/files/. See the Support service Docker container example below. 
    1. The provided validation certificate
    2. Your signing certificate and signing key 
  5. Add trust to the Signing service SP: 
    1. Add trust to the provided SP SAML metadata in your IdP. 
    2. Start the Support service Docker container, for example:

      Example: Start Support service Docker container
      docker run --interactive --volume c:/sign-support/test/files/:/home/docker/additional/:ro \
      --env APPLICATION_SIGNSUPPORT_SIGNING_KEY=file:/home/docker/additional/signing-key.pem \
      --env APPLICATION_SIGNSUPPORT_SIGNING_KEY_PASSWORD=******* \
      --env APPLICATION_SIGNSUPPORT_SIGNING_CERTIFICATE=file:/home/docker/additional/signing-certificate.pem \
      --env APPLICATION_SIGNSUPPORT_VALIDATION_CERTIFICATE=file:/home/docker/additional/validation-certificate.cer \
      --env APPLICATION_SIGNSUPPORT_PROFILE_CONFIG=file:/home/docker/additional/profile.json \
      --env APPLICATION_SIGNSUPPORT_ENTITIES_DESCRIPTOR=file:/home/docker/additional/entities-descriptor.xml \
      --publish 8081:8080 technologynexus/sign-support

      The Support service Docker image is available here: https://hub.docker.com/r/technologynexus/sign-support/

    Now you are ready to sign PDF and XML documents. 

    To explore the Support service API, open the following URL in your browser: