PhenixID

Step by Step – Consume SWAMID user authentication with PhenixID Authentication and Signing Services

Summary

This document will guide you through the steps to configure PhenixID Authentication Services and/or PhenixID Signing Services to consume user authentication from the university federation SWAMID.

PhenixID Authentication Services (PAS) will act as a SAML Service Provider against the SWAMID federation.

Background

SWAMID is a large university federation containing thousands of university identity providers. With PhenixID, you can:

  • Sign documents and transactions electronically using your SWAMID account (=your university account)
  • Protect web- and cloud apps (SAML SPs, OIDC RPs) with SWAMID authentication
  • Protect internal PhenixID web apps, such as the MyApps portal, with SWAMID authentication

This is particularly useful if you need to protect apps with different authentication methods, where SWAMID is one alternative.

System requirements

  • PhenixID Authentication Services 4.0 or higher

Instruction

Configure PhenixID Authentication Services

Add authenticator

  • Login to Configuration Manager
  • Advanced->Authenticators-HTTP
  • Depending on the service you protect, you need to create an authenticator:

– Protecting internal web application (for example Myapps, self service, signing) -> SAMLServiceProviderAuthN. Please view this instruction.

– Protecting external service which is a SAML SP -> SAMLSPBroker. Please view this instruction.

– Protecting external service which is an OIDC RP -> OIDCToSAMLBroker. Please view this instruction.

Define a signing and encryption keystore on the SP object.

Make sure to set this parameter on the authenticator:

“targetIDP”: “dummy”

Example configuration (in this example the activateonetouch web app will be protected by SWAMID authentication):

 {
"id": "c0742d0c-6d01-47d2-8b37-f4f0ecd5988e",
"alias": "c0742d0c-6d01-47d2-8b37-f4f0ecd5988e",
"name": "SAMLServiceProviderAuthN",
"displayName": "SWAMID",
"configuration": {
"successURL": "/activateonetouch/",
"sp": "https://x.phenixid.net/saml/sp",
"pipeID": "assertionConsumer",
"targetIDP": "dummy",
"acsUrl": "https://x.phenixid.net/activateonetouch/authenticate/c0742d0c-6d01-47d2-8b37-f4f0ecd5988e",
"entityID": "https://x.phenixid.net/saml/sp"
}
}

Fetch and edit SAML SP Metadata

  • Fetch your sp metadata by opening the URL:

For a SAMLServiceProviderAuthN authenticator : <acsUrl_in_authenticator_conf>?getSPMeta

For a SAMLSPBroker or OIDCToSAMLBroker authenticator : <acsUrl_in_authenticator_conf>?getMeta

  • Save the produced metadata to a xml file.
  • Open the metadata xml file in a text editor
  • (For a detailed requirement specification of the metadata required, please view https://wiki.sunet.se/display/SWAMID/SAML+SP+Best+Current+Practice)

    Make the following changes to the metadata:

    1. Add entity category(ies) to the metadata (below the EntityDescriptor tag):

      <md:Extensions>
      <mdattr:EntityAttributes>
      <samla:Attribute NameFormat=”urn:oasis:names:tc:SAML:2.0:attrname-format:uri” Name=”http://macedir.org/entity-category”>
      <samla:AttributeValue>http://refeds.org/category/research-and-scholarship</samla:AttributeValue>
      </samla:Attribute>
      </mdattr:EntityAttributes>
      </md:Extensions>

       

    2. Add this part below the SPSSODescriptor tag.

      <md:Extensions>
      <mdui:UIInfo xmlns:mdui=”urn:oasis:names:tc:SAML:metadata:ui”>
      <mdui:DisplayName xml:lang=”sv”>YOUR_ORGANIZATION_NAME</mdui:DisplayName>
      <mdui:DisplayName xml:lang=”en”>YOUR_ORGANIZATION_NAME</mdui:DisplayName>
      <mdui:Description xml:lang=”sv”>YOUR_ORGANIZATION_NAME</mdui:Description>
      <mdui:Description xml:lang=”en”>YOUR_ORGANIZATION_NAME</mdui:Description>
      <mdui:InformationURL xml:lang=”sv”>YOUR_ORGANIZATION_URL</mdui:InformationURL>
      <mdui:InformationURL xml:lang=”en”>YOUR_ORGANIZATION_URL</mdui:InformationURL>
      <mdui:PrivacyStatementURL xml:lang=”sv”>YOUR_ORGANIZATION_GDPR_URL</mdui:PrivacyStatementURL>
      <mdui:PrivacyStatementURL xml:lang=”en”>YOUR_ORGANIZATION_GDPR_URL</mdui:PrivacyStatementURL>
      </mdui:UIInfo>
      </md:Extensions>
      <md:Organization>
      <md:OrganizationName xml:lang=”sv”>YOUR_ORGANIZATION_NAME</md:OrganizationName>
      <md:OrganizationName xml:lang=”en”>YOUR_ORGANIZATION_NAME</md:OrganizationName>
      <md:OrganizationDisplayName xml:lang=”sv”>YOUR_ORGANIZATION_NAME</md:OrganizationDisplayName>
      <md:OrganizationDisplayName xml:lang=”en”>YOUR_ORGANIZATION_NAME</md:OrganizationDisplayName>
      <md:OrganizationURL xml:lang=”sv”>YOUR_ORGANIZATION_URL</md:OrganizationURL>
      <md:OrganizationURL xml:lang=”en”>YOUR_ORGANIZATION_URL</md:OrganizationURL>
      </md:Organization>
      <md:ContactPerson contactType=”administrative”>
      <md:GivenName>YOUR_ORGANIZATION_ADMIN_CONTACT</md:GivenName>
      <md:EmailAddress>mailto:YOUR_ORGANIZATION_ADMIN_EMAIL</md:EmailAddress>
      </md:ContactPerson>
      <md:ContactPerson contactType=”technical”>
      <md:GivenName>YOUR_ORGANIZATION_TECH_CONTACT</md:GivenName>
      <md:EmailAddress>mailto:YOUR_ORGANIZATION_TECH_EMAIL</md:EmailAddress>
      </md:ContactPerson>

      Replace these values:
      YOUR_ORGANIZATION_NAME = Your organization name
      YOUR_ORGANIZATION_URL = Your organization web site url
      YOUR_ORGANIZATION_GDPR_URL = Your organization privacy statement url
      YOUR_ORGANIZATION_ADMIN_CONTACT = Your organization administrative contact name
      YOUR_ORGANIZATION_TECH_CONTACT = Your organization tech contact name
      YOUR_ORGANIZATION_ADMIN_EMAIL = Your organization administrative contact email address
      YOUR_ORGANIZATION_TECH_CONTACT = Your organization tech contact email address

    3. Save the file
    4. Send an email with the metadata to SWAMID operations and request the SP to be added to the SWAMID federation.
      https://wiki.sunet.se/display/SWAMID/Contact+SWAMID
  • Metadata example:
    <?xml version=”1.0″ encoding=”UTF-8″?>
    <md:EntityDescriptor xmlns:mdattr=”urn:oasis:names:tc:SAML:metadata:attribute” xmlns:samla=”urn:oasis:names:tc:SAML:2.0:assertion” xmlns:md=”urn:oasis:names:tc:SAML:2.0:metadata” ID=”_655bab96-8a4f-413b-bb5c-583481bda4cc” entityID=”https://phenixid.se/saml/sp”>
    <md:Extensions>
    <mdattr:EntityAttributes>
    <samla:Attribute NameFormat=”urn:oasis:names:tc:SAML:2.0:attrname-format:uri” Name=”http://macedir.org/entity-category”>
    <samla:AttributeValue>http://refeds.org/category/research-and-scholarship</samla:AttributeValue>
    </samla:Attribute>
    </mdattr:EntityAttributes>
    </md:Extensions>
    <md:SPSSODescriptor AuthnRequestsSigned=”true” WantAssertionsSigned=”true” protocolSupportEnumeration=”urn:oasis:names:tc:SAML:2.0:protocol”>
    <md:Extensions>
    <mdui:UIInfo xmlns:mdui=”urn:oasis:names:tc:SAML:metadata:ui”>
    <mdui:DisplayName xml:lang=”sv”>PhenixID AB</mdui:DisplayName>
    <mdui:DisplayName xml:lang=”en”>PhenixID AB</mdui:DisplayName>
    <mdui:Description xml:lang=”sv”>PhenixID AB</mdui:Description>
    <mdui:Description xml:lang=”en”>PhenixID AB</mdui:Description>
    <mdui:InformationURL xml:lang=”sv”>http://www.phenixid.se</mdui:InformationURL>
    <mdui:InformationURL xml:lang=”en”>http://www.phenixid.se</mdui:InformationURL>
    <mdui:PrivacyStatementURL xml:lang=”sv”>https://www.phenixid.se/privacy-statement/</mdui:PrivacyStatementURL>
    <mdui:PrivacyStatementURL xml:lang=”en”>https://www.phenixid.se/privacy-statement/</mdui:PrivacyStatementURL>
    </mdui:UIInfo>
    </md:Extensions>
    <md:Organization>
    <md:OrganizationName xml:lang=”sv”>PhenixID AB</md:OrganizationName>
    <md:OrganizationName xml:lang=”en”>PhenixID AB</md:OrganizationName>
    <md:OrganizationDisplayName xml:lang=”sv”>PhenixID AB</md:OrganizationDisplayName>
    <md:OrganizationDisplayName xml:lang=”en”>PhenixID AB</md:OrganizationDisplayName>
    <md:OrganizationURL xml:lang=”sv”>https://www.phenixid.se/</md:OrganizationURL>
    <md:OrganizationURL xml:lang=”en”>https://www.phenixid.se/</md:OrganizationURL>
    </md:Organization>
    <md:ContactPerson contactType=”administrative”>
    <md:GivenName>IT Management</md:GivenName>
    <md:EmailAddress>mailto:bounce@phenixid.se</md:EmailAddress>
    </md:ContactPerson>
    <md:ContactPerson contactType=”technical”>
    <md:GivenName>IT Operations</md:GivenName>
    <md:EmailAddress>mailto:bounce@phenixid.se</md:EmailAddress>
    </md:ContactPerson>
    <md:KeyDescriptor use=”signing”>
    <ds:KeyInfo xmlns:ds=”http://www.w3.org/2000/09/xmldsig#”>
    <ds:X509Data>
    <ds:X509Certificate>MIIDMzCCAhugAwIBAgIGAXxUdcuYMA0GCSqGSIb3DQEBCwUAMEIxDTALBgNVBAMMBGF1dG8xETAP
    BgNVBAsMCGN1c3RvbWVyMREwDwYDVQQKDAhQaGVuaXhJRDELMAkGA1UEBhMCU0UwHhcNMjExMDA2
    MDcxNjE4WhcNMjYxMDA1MDcxNjE4WjBCMQ0wCwYDVQQDDARhdXRvMREwDwYDVQQLDAhjdXN0b21l
    cjERMA8GA1UECgwIUGhlbml4SUQxCzAJBgNVBAYTAlNFMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A
    MIIBCgKCAQEAoYC4Jy5qJbvADhy2JQTpjbis02Or25XBl2DWnJWS+ONnUclYJZv/51o+TOYwuvtX
    GR/Dmqvj61liB2SuZXZ7nAGd0j9FsD4ZmjS+lC2VDxOPykrM7KuUergCf78p6Sg8rWPnpKVf2cL7
    uPOKMHaf0Iatf7e0hbpvrxaFaxVv9ePq+eKxU+UCMOkUr4tN1/V0KjlIMoFbWmKaotYSVryLkVzT
    QHhalFt/INcs6GRXL3OxUmjmriOwF1YOLEXHmMS0N5bgn/9LRpRMufJDpNzvDP+TF1ApQtAobbIT
    rC5RSQFmrsNoi9ErceOjMuTJYuV0Fo+L+m/RFpxf6pIwxBQSAQIDAQABoy8wLTAOBgNVHQ8BAf8E
    BAMCBaAwGwYDVR0RBBQwEocEwQoM84IKcGhpZC5rYi5zZTANBgkqhkiG9w0BAQsFAAOCAQEAZj0j
    zkMw8tpk+S4/7OY3vRkK+CGhCup4YICsFqKS6HvnPju/RWLd493sMoMSlDp1TjaVn8asf4dHHdxk
    5JmVoQrUI9jFoc2UUDR//DvWnsX3zydykd4VMrjjTXw+JCIUQy6PQIdBoN9nA2WHTMSCrJAUrckj
    YemNMQDVnj7tuW4tj91+s7pTk3NqbEmbmQI4xEkPnPEEYyOJRkG0eHgL4gRVZlDhghFj3JZjD85G
    KuY7VwHosxj3oCFpHtAZyi96gVawvhRbgKEL+fKg+ydZhPLuFWsVGHiRZ94gHg/afBrl3h6KnPW3
    USOOI2K1p71ha4JKrQS8xUlRSw3G1vB8Yg==</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>MIIDMzCCAhugAwIBAgIGAXxUdcuYMA0GCSqGSIb3DQEBCwUAMEIxDTALBgNVBAMMBGF1dG8xETAP
    BgNVBAsMCGN1c3RvbWVyMREwDwYDVQQKDAhQaGVuaXhJRDELMAkGA1UEBhMCU0UwHhcNMjExMDA2
    MDcxNjE4WhcNMjYxMDA1MDcxNjE4WjBCMQ0wCwYDVQQDDARhdXRvMREwDwYDVQQLDAhjdXN0b21l
    cjERMA8GA1UECgwIUGhlbml4SUQxCzAJBgNVBAYTAlNFMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A
    MIIBCgKCAQEAoYC4Jy5qJbvADhy2JQTpjbis02Or25XBl2DWnJWS+ONnUclYJZv/51o+TOYwuvtX
    GR/Dmqvj61liB2SuZXZ7nAGd0j9FsD4ZmjS+lC2VDxOPykrM7KuUergCf78p6Sg8rWPnpKVf2cL7
    uPOKMHaf0Iatf7e0hbpvrxaFaxVv9ePq+eKxU+UCMOkUr4tN1/V0KjlIMoFbWmKaotYSVryLkVzT
    QHhalFt/INcs6GRXL3OxUmjmriOwF1YOLEXHmMS0N5bgn/9LRpRMufJDpNzvDP+TF1ApQtAobbIT
    rC5RSQFmrsNoi9ErceOjMuTJYuV0Fo+L+m/RFpxf6pIwxBQSAQIDAQABoy8wLTAOBgNVHQ8BAf8E
    BAMCBaAwGwYDVR0RBBQwEocEwQoM84IKcGhpZC5rYi5zZTANBgkqhkiG9w0BAQsFAAOCAQEAZj0j
    zkMw8tpk+S4/7OY3vRkK+CGhCup4YICsFqKS6HvnPju/RWLd493sMoMSlDp1TjaVn8asf4dHHdxk
    5JmVoQrUI9jFoc2UUDR//DvWnsX3zydykd4VMrjjTXw+JCIUQy6PQIdBoN9nA2WHTMSCrJAUrckj
    YemNMQDVnj7tuW4tj91+s7pTk3NqbEmbmQI4xEkPnPEEYyOJRkG0eHgL4gRVZlDhghFj3JZjD85G
    KuY7VwHosxj3oCFpHtAZyi96gVawvhRbgKEL+fKg+ydZhPLuFWsVGHiRZ94gHg/afBrl3h6KnPW3
    USOOI2K1p71ha4JKrQS8xUlRSw3G1vB8Yg==</ds:X509Certificate>
    </ds:X509Data>
    </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
    <md:AssertionConsumerService Binding=”urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST” Location=”https://phenixid.se/saml/authenticate/swamid” index=”0″ isDefault=”true”/>
    </md:SPSSODescriptor>
    </md:EntityDescriptor>

Add trust to SWAMID federation

  1. Login to Configuration manager
  2. Scenarios->Federation->SAML Metadata upload
  3. Point to the SWAMID registered identity providers SAML metadata feed (view information here: https://wiki.sunet.se/display/SWAMID/SAML+Metadata+and+Trust#SAMLMetadataandTrust-SWAMIDMetadataFeeds)

Point SAML SP to federation idp discovery URL

  1. Login to Configuration manager
  2. Advanced
  3. Authentication – HTTP
  4. Locate your SAML SP authenticator
  5. Add idp discovery url by adding the discoveryUrl parameter to the config. Idp discovery URL for SWAMID can be found at https://wiki.sunet.se/display/SWAMID/Identity+Provider+Discovery.

    Example:
    {
    “id”: “c0742d0c-6d01-47d2-8b37-f4f0ecd5988e”,
    “alias”: “c0742d0c-6d01-47d2-8b37-f4f0ecd5988e”,
    “name”: “SAMLServiceProviderAuthN”,
    “displayName”: “SWAMID”,
    “configuration”: {
    “successURL”: “/activateonetouch/”,
    “sp”: “https://x.phenixid.net/saml/sp”,
    “pipeID”: “assertionConsumer”,
    “targetIDP”: “dummy”,
    “acsUrl”: “https://x.phenixid.net/activateonetouch/authenticate/c0742d0c-6d01-47d2-8b37-f4f0ecd5988e”,
    “discoveryUrl”: “https://service.seamlessaccess.org/ds/”,
    “entityID”: “https://x.phenixid.net/saml/sp”
    }
    }

Handle SWAMID attributes

  1. Login to Configuration Manager
  2. Click Advanced
  3. Click Pipes and locate the pipe used by the SP authenticator.
  4. Append these valves to the pipe: 
    {
      "name" : "SessionLoadValve",
      "config" : {
        "id" : "{{request.session_id}}"
      }
    }, {
      "name" : "PropertyFromSessionToItem",
      "config" : {
        "source" : "urn:oid:0.9.2342.19200300.100.1.3"
      }
    }, {
      "name" : "PropertyRenameValve",
      "config" : {
        "source" : "urn:oid:0.9.2342.19200300.100.1.3",
        "dest" : "mail"
      }
    }, {
      "name" : "SessionPropertyReplaceValve",
      "config" : {
        "name" : "mail",
        "value" : "{{item.mail}}"
      }
    }, {
      "name" : "PropertyFromSessionToItem",
      "config" : {
        "source" : "urn:oid:2.5.4.42"
      }
    }, {
      "name" : "PropertyRenameValve",
      "config" : {
        "source" : "urn:oid:2.5.4.42",
        "dest" : "givenName"
      }
    }, {
      "name" : "SessionPropertyReplaceValve",
      "config" : {
        "name" : "givenName",
        "value" : "{{item.givenName}}"
      }
    }, {
      "name" : "PropertyFromSessionToItem",
      "config" : {
        "source" : "urn:oid:2.5.4.4"
      }
    }, {
      "name" : "PropertyRenameValve",
      "config" : {
        "source" : "urn:oid:2.5.4.4",
        "dest" : "sn"
      }
    }, {
      "name" : "SessionPropertyReplaceValve",
      "config" : {
        "name" : "sn",
        "value" : "{{item.sn}}"
      }
    }, {
      "name" : "SessionPersistValve",
      "config" : { }
    } ]
  }




  5. Click Stage changes and commit changes

Test

When receiving acknowledgment from SWAMID operations that the SP has been added to the SWAMID federation, you are ready to test.

  • Trigger the authentication flow where the SWAMID authentication is involved (for example https://x.phenixid.net/activateonetouch/)
  • Your browser should be redirected to the SWAMID idp discovery
  • Select an idp where you are able to authenticate
  • Authenticate on the IdP
  • Your browser should be redirected back to PhenixID Authentication Services with a SAML assertion
  • You should now be logged in to the service protected by SWAMID authentication

Debugging

  • Use a SAML debugging tool, such as SAML Tracer, to retrieve the SAML messages
  • Use PhenixID server.log in debug mode to find detailed information about backend errors.

DISCLAIMER
Information provided in this document is for your information only. PhenixID makes no explicit or implied claims to the validity of this information. Any trademarks referenced in this document are the property of their respective owners.

The origin of this information may be internal or external to PhenixID. PhenixID makes all reasonable efforts to verify this information.

PhenixID - support.phenixid.se